mididings configuration files are just Python scripts, although mididings uses some of Python's features in ways
for which they weren't intended ;)
Basically, the MIDI processing setup is defined in Python, while the actual event processing is done entirely
in C++. It is however possible to explicitly call back into Python, if necessary.
Changes global mididings settings. This should be called only once, before constructing any processing units.
Possible keyword arguments are:
Registers "hook" objects, that can be used to extend the functionality of mididings.
Starts the MIDI processing. This is usually the last function called by a mididings script.
Starts the MIDI processing, using multiple scenes. The SceneSwitch() unit can be used to switch between these scenes.
Requires mididings to be compiled with support for libsmf.
Reads a standard MIDI file, processes it, then writes the result back to a file.
Used in conjunction with the Process() and Call() units.
A MidiEvent object has the following attributes:
There are also aliases for these attributes, some of which are only valid for certain types of events:
Every event has one of these types:
For use in filters, the following constants are also defined:
When building filters, event types can be combined using | (bitwise or) and ~ (bitwise negation).
These constants are used to refer to an event's data attributes:
Connects two units in series. Incoming MIDI events will be processed by unit A first, then by unit B. If the event is filtered out by unit A, it is not processed any further, and unit B will not be called.
Connects two units in parallel. Both units will be called with identical copies of incoming MIDI events. The output will be the sum of all the units' outputs. Note that operator // has higher precedence than >>.
Connects an arbitrary number of units in parallel.
Same as the above, with some additional features:
Using Fork() explicitly (instead of just a list) is also useful in situations where both sides of operator >> would otherwise be lists, which Python does not allow.
Splits by event type. Equivalent to [ Filter(T1) >> A, Filter(T2) >> B, ... ].
Same as the above. Like Fork(), this can be useful to make operator >> work.
Inverts the filter F. Note that for filters which only affect certain kinds of events, other events will remain unaffected when the filter is inverted. For example, an inverted KeyFilter will match a different note range, but neither the original nor the inverted filter will have any effect on control or program changes.
Inverts the filter F. Unlike ~F, -F matches exactly the events that F doesn't.
Applies A only to events which match filter F, but keeps events which don't. Equivalent to [ F >> A, -F ].
Applies A only to events which match all filters F1, F2, etc.
These are the basic building blocks from which you can build your patches.
Filters by one or more event types.
Filters by event port or channel.
Filters by key or key-range. Keys can be MIDI note numbers or note names (e.g. 'g#3'). Ranges can be 2-tuples of note numbers, or note names (e.g. 'g#3:c6').
Filters by note velocity. A lower or upper value of 0 means no limit.
Filters by CC number.
Filters by CC value.
Filters by PC number.
Filters by sysex data, specified as a string or as a sequence of integers. If sysex does end with F7, partial matches that start with the given data bytes are accepted.
Filters by sysex manufacturer id, which can be a string or a sequence of integers, with a length of one or three bytes.
Splits by port or channel.
Splits by key. Non-note events are sent to all units.
Splits by velocity. Non-note events are sent to all units.
Splits by controller number. Non-controller events are left unchanged, but not sent to any of the units.
Splits by controller value. Non-controller events are left unchanged, but not sent to any of the units.
Splits by program number. Non-program-change events are left unchanged, but not sent to any of the units.
Splits by sysex data or manufacturer id.
Changes port or channel.
Transposes all note events.
Changes velocity by adding an offset, multiplying with a factor, setting it to a fixed value, or applying a velocity-curve.
gamma uses a quadratic function, where values greater than 1 increase velocity, while values between 0 and 1 decrease it.
curve uses a somewhat smoother exponential function, where positive values increase velocity, while negative values decrease it.
Changes velocity, applying a linear slope between different notes.
Both parameters must be lists/tuples of the same length, where one velocity value corresponds to each note.
This can be used for example to fade-in a sound over a region of the keyboard.
Confines velocity to values between lower and upper (inclusive).
Maps one controller to another (i.e. changes the CC number).
Maps controller range in to out.
An input value of in_min or less results in an output value of out_min.
Likewise, an in value of in_max or greater results in an output value of out_max.
Changes the type of the event.
If port and channel are omitted, the values of the input event are used.
To "reuse" other values from the incoming event, one of the EVENT_* constants can be used in place of any parameter.
Creates a new system exclusive event. sysex can be a string or a sequence of integers, and must include the leading F0 and trailing F7 bytes.
Generic generator. System common and system realtime events can only be generated this way.
Calls a Python function. This will stall any other MIDI processing until the function returns.
Schedules a Python function for execution, and continues MIDI processing immediately.
Like Call(), but runs the function in its own thread.
Runs an arbitrary shell command, without waiting for the command to complete.
Does nothing.
Discards the current event.
Switches to another scene. number should be a scene number, or one of the EVENT_* constants. Without parameters, the program number of the incoming event (should be a program change) will be used.
Executes patch when switching to the scene containing this unit (essentially adding it to the init-patch, see run() for more information).
Routes incoming events to the specified port/channel. Optionally, when switching to the scene containing this unit, a program change and/or volume change (CC 7) can be sent. To send a bank select in addition to the program change, program can be a tuple with two elements, where the first element is the bank number, and the second is the program number.
Prints event data.
Prints a fixed string.
Makes sure the event is a valid MIDI message. Events with invalid port, channel, controller, program or note number are discarded, note velocity and controller values are confined to the range 0-127.
These units are defined in the mididings.extra module, and offer some more advanced/specific functionality,
based on the more basic mididings units.
Some of these are implemented in Python using Process(), and thus not safe to use with the jack-rt backend.
A diatonic harmonizer.
Limits the "MIDI polyphony" to max_polyphony.
If remove_oldest is true, the oldest notes will be stopped when the maximum polyphony is exceeded.
If remove_oldest is false, no new notes are accepted while max_polyphony notes are held.
Note that the actual polyphony of a connected synthesizer can still be higher than the limit set here,
e.g. due to a long release phase.
Makes the MIDI signal "monophonic", i.e. only one note can be played at any given time. When a note is released while another one is still held (but silent), the previous one will be retriggered.
Filters out program changes if the same program had previously been selected on the same port/channel.
Converts sustain pedal CCs to note-off events (delaying note-offs until the pedal is released). Acts either like a regular sustain pedal (the default) or like a sostenuto pedal.
Filters notes by key color.
A hook object that saves the currently selected scene number to a file when terminating mididings, and restores it at the next startup. memo_file is the path of the file to be used to store the scene number.
Defined in mididings.extra.osc. Requires pyliblo.
A hook object that allows controlling mididings via OSC. These messages are currently understood:
Defined in mididings.extra.osc. Requires pyliblo.
Sends an OSC message. Parameters are the same as for liblo.send().
Additionally, rather than a concrete value, each data argument can be a Python function instead.
The function should then take a single MidiEvent parameter, and return the value to be sent.
Defined in mididings.extra.dbus. Requires dbus-python.
Sends a DBUS message. Rather than a concrete value, each data argument can be a Python function instead.
The function should then take a single MidiEvent parameter, and return the value to be sent.
Defined in mididings.extra.inotify. Requires pyinotify ≥ 0.8.
A hook object that automatically restarts mididings when the script changes.
If modules is True, all imported local Python modules are monitored for changes as well.
The filenames parameter allows specifying additional files to be monitored.
This restarts the entire mididings script, so MIDI processing is interrupted, and mididings does not take care of
reestablishing any ALSA/JACK connections.
If the new script contains errors that prevent it from running, mididings exits and needs to be restarted manually
once the errors are fixed.