aboutsummaryrefslogtreecommitdiffhomepage
path: root/backends/python.md
diff options
context:
space:
mode:
authorcbdev <cb@cbcdn.com>2020-03-23 00:15:00 +0100
committercbdev <cb@cbcdn.com>2020-03-23 00:15:00 +0100
commit37e712edf23a49be5387f945ab9ea57cc0b57f22 (patch)
tree5037b14bdbd08baa8f104f7e4946aa5643281a94 /backends/python.md
parent666aec036f9bf0de82c435bd7eace271613cee1e (diff)
parentaa02ccf3abf183207b24fcbb9460cbd904a698e2 (diff)
downloadmidimonster-37e712edf23a49be5387f945ab9ea57cc0b57f22.tar.gz
midimonster-37e712edf23a49be5387f945ab9ea57cc0b57f22.tar.bz2
midimonster-37e712edf23a49be5387f945ab9ea57cc0b57f22.zip
Merge current master
Diffstat (limited to 'backends/python.md')
-rw-r--r--backends/python.md101
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.