aboutsummaryrefslogtreecommitdiffhomepage
path: root/backends/lua.md
diff options
context:
space:
mode:
authorcbdev <cb@cbcdn.com>2019-07-06 17:25:12 +0200
committercbdev <cb@cbcdn.com>2019-07-06 17:25:12 +0200
commitb618c4a6b74a52f830ca53029e1cc680d56a2501 (patch)
tree6da5459b45db4448936cb8f0225490b9f5135b1e /backends/lua.md
parentee75bee08b8fb280fc1d76e8635cf29c576835da (diff)
downloadmidimonster-b618c4a6b74a52f830ca53029e1cc680d56a2501.tar.gz
midimonster-b618c4a6b74a52f830ca53029e1cc680d56a2501.tar.bz2
midimonster-b618c4a6b74a52f830ca53029e1cc680d56a2501.zip
Implement Lua backend
Diffstat (limited to 'backends/lua.md')
-rw-r--r--backends/lua.md49
1 files changed, 49 insertions, 0 deletions
diff --git a/backends/lua.md b/backends/lua.md
new file mode 100644
index 0000000..91e8fe2
--- /dev/null
+++ b/backends/lua.md
@@ -0,0 +1,49 @@
+### The `lua` backend
+
+The `lua` backend provides a flexible programming environment, allowing users to route and manipulate
+events using the Lua programming language.
+
+Every instance has it's own interpreter state which can be loaded with custom handler scripts.
+
+To process incoming channel events, the MIDIMonster calls corresponding Lua functions with
+the value (as a Lua `number` type) as parameter. To send output on a channel, the Lua environment
+provides the function `output(channel-name, value)`.
+
+Example script:
+```
+function bar(value)
+ output("foo", value / 2)
+end
+```
+
+Input values range between 0.0 and 1.0, output values are clamped to the same range.
+
+#### Global configuration
+
+The backend does not take any global configuration.
+
+#### Instance configuration
+
+| Option | Example value | Default value | Description |
+|---------------|-----------------------|-----------------------|-----------------------|
+| `source` | `script.lua` | none | Lua source file |
+
+A single instance may have multiple `source` options specified, which will all be read cumulatively.
+
+#### Channel specification
+
+Channel names may be any valid Lua function name.
+
+Example mapping:
+```
+lua1.foo > lua2.bar
+```
+
+#### Known bugs / problems
+
+Using `output` as an input channel name to a Lua instance does not work, as the interpreter has
+`output` globally assigned to the event output function. Using `output` as an output channel name
+via `output("output", value)` works as intended.
+
+The path to the Lua source files is relative to the current working directory. This may lead
+to problems when copying configuration between installations.