blob: fae313912afb4327f6ed5b8b3e7b42f2951a2964 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
|
### 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.
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 |
Example Python module:
```
import midimonster
def in1(value):
midimonster.output("out1", 1 - value)
```
Input values range between 0.0 and 1.0, output values are clamped to the same range.
#### 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 |
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` may cause problems and is unsupported.
There is currently no functionality for cyclic execution. This may be implemented in a future
release.
|
