1 files changed, 52 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fdfce52
--- /dev/null
+++ b/README.md
@@ -0,0 +1,52 @@
+# melisma
+
+Melisma is a scriptable and extensible audio engine. It can be used for
+algorithmic composition, custom digital instruments and interactive audio
+installations. Most of melismas functionality is implemented in Lua modules
+written in C, using an API defined in [melisma.h](../tree/include/melisma.h).
+The core program only implements the Jack client, event system and port
+creation/manipulation. You can find some of my modules [here](../../melisma-modules.git/about),
+and some examples [here](../../melisma-examples.git/about).
+
+## Building and installing
+
+To build melisma from source, you'll need to have pkg-config, Lua 5.3 and Jack
+installed. To build and install, run
+
+```bash
+$ make install PREFIX=/usr/local
+```
+
+## Usage
+
+```bash
+$ melisma script.lua
+```
+
+## Building modules
+
+Melisma modules are written in C. They should be namespaced to melisma, so they
+should be installed to a subdirectory melisma/ in LUA_CPATH, and the entry point
+should look something like this:
+
+```c
+// mymodule.c
+
+#include "melisma.h"
+
+// ...
+
+int luaopen_melisma_mymodule(lua_State *state) {
+  ml_check_version();
+
+  // ...
+
+  return 1;
+}
+```
+
+Building the module may look something like this:
+
+```bash
+$ cc -o mymodule.so -shared -fPIC $(pkg-config --cflags melisma.h) mymodule.c
+```