Merge current master

1 files changed, 101 insertions, 0 deletions

diff --git a/backends/python.md b/backends/python.md
new file mode 100644
index 0000000..6852a79
--- /dev/null
+++ b/backends/python.md
@@ -0,0 +1,101 @@
+### The `python` backend
+
+The `python` backend provides a flexible programming environment, allowing users
+to route, generate and manipulate channel events using the Python 3 scripting language.
+
+Every instance has its own interpreter, which can be loaded with multiple Python modules.
+These modules may contain member functions accepting a single `float` parameter, which can
+then be used as target channels. For each incoming event, the handler function is called.
+Channels in the global scope may be assigned a default handler function.
+
+Python modules may also register `socket` objects (and an associated callback function) with
+the MIDIMonster core, which will then alert the module when there is data ready to be read.
+
+To interact with the MIDIMonster core, import the `midimonster` module from within your module.
+
+The `midimonster` module provides the following functions:
+
+| Function			| Usage example				| Description					|
+|-------------------------------|---------------------------------------|-----------------------------------------------|
+| `output(string, float)`	| `midimonster.output("foo", 0.75)`	| Output a value event to a channel		|
+| `inputvalue(string)`		| `midimonster.inputvalue("foo")`	| Get the last input value on a channel		|
+| `outputvalue(string)`		| `midimonster.outputvalue("bar")`	| Get the last output value on a channel 	|
+| `current()`			| `print(midimonster.current())`	| Returns the name of the input channel whose handler function is currently running or `None` if the interpreter was called from another context |
+| `timestamp()`			| `print(midimonster.timestamp())`	| Get the internal core timestamp (in milliseconds)	|
+| `interval(function, long)`	| `midimonster.interval(toggle, 100)`	| Register a function to be called periodically. Interval is specified in milliseconds (accurate to 10msec). Calling `interval` with the same function again updates the interval. Specifying the interval as `0` cancels the interval |
+| `manage(function, socket)`	| `midimonster.manage(handler, socket)`| Register a (connected/listening) socket to the MIDIMonster core. Calls `function(socket)` when the socket is ready to read. Calling this method with `None` as the function argument unregisters the socket. A socket may only have one associated handler |
+
+Example Python module:
+```python
+import socket
+import midimonster
+
+# Simple channel handler
+def in1(value):
+	midimonster.output("out1", 1 - value)
+
+# Socket data handler
+def socket_handler(sock):
+	# This should get some more error handling
+	data = sock.recv(1024)
+	print("Received %d bytes from socket: %s" % (len(data), data))
+	if(len(data) == 0):
+		# Unmanage the socket if it has been closed
+		midimonster.manage(None, sock)
+		sock.close()
+
+# Interval handler
+def ping():
+	print(midimonster.timestamp())
+
+# Register an interval
+midimonster.interval(ping, 1000)
+# Create and register a client socket (add error handling as you like)
+s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+s.connect(("localhost", 8990))
+midimonster.manage(socket_handler, s)
+```
+
+Input values range between 0.0 and 1.0, output values are clamped to the same range.
+
+Note that registered sockets that have been closed (`socket.recv()` returned 0 bytes)
+need to be unregistered from the MIDIMonster core, otherwise the core socket multiplexing
+mechanism will report an error and shut down the MIDIMonster.
+
+#### Global configuration
+
+The `python` backend does not take any global configuration.
+
+#### Instance configuration
+
+| Option		| Example value		| Default value 	| Description					|
+|-----------------------|-----------------------|-----------------------|-----------------------------------------------|
+| `module`		| `my_handlers.py`	| none			| (Path to) Python module source file, relative to configuration file location |
+| `default-handler`	| `mu_handlers.default`	| none			| Function to be called as handler for all top-level channels (not belonging to a module) |
+
+A single instance may have multiple `module` options specified. This will make all handlers available within their
+module namespaces (see the section on channel specification).
+
+#### Channel specification
+
+Channel names may be any valid Python function name. To call handler functions in a module,
+specify the channel as the functions qualified path (by prefixing it with the module name and a dot).
+
+Example mappings:
+```
+py1.my_handlers.in1 < py1.foo
+py1.out1 > py2.module.handler
+```
+
+#### Known bugs / problems
+
+Output values will not trigger corresponding input event handlers unless the channel is mapped
+back in the MIDIMonster configuration. This is intentional.
+
+Importing a Python module named `midimonster` is probably a bad idea and thus unsupported.
+
+The MIDIMonster is, at its core, single-threaded. Do not try to use Python's `threading`
+module with the MIDIMonster.
+
+Note that executing Python code blocks the MIDIMonster core. It is not a good idea to call functions that
+take a long time to complete (such as `time.sleep()`) within your Python modules.