Miscellaneous¶

Event Types¶

Every event has one of the following types:

Symbolic constant	MIDI event type
`NOTEON`	Note-on event
`NOTEOFF`	Note-off event
`CTRL`	Control change event
`PROGRAM`	Program change event
`PITCHBEND`	Pitchbend event
`AFTERTOUCH`	Channel aftertouch event
`POLY_AFTERTOUCH`	Polyphonic aftertouch event
`SYSEX`	System exclusive event
`SYSCM_QFRAME`	MTC quarter frame
`SYSCM_SONGPOS`	Song position pointer
`SYSCM_SONGSEL`	Song select
`SYSCM_TUNEREQ`	Tune request
`SYSRT_CLOCK`	Timing clock
`SYSRT_START`	Start sequence
`SYSRT_CONTINUE`	Continue sequence
`SYSRT_STOP`	Stop sequence
`SYSRT_SENSING`	Active sensing
`SYSRT_RESET`	System reset

For use in filters, the following constants are also defined:

Symbolic constant	Matched MIDI event types
`NOTE`	Any note event (`NOTEON` \| `NOTEOFF`)
`SYSCM`	Any system common event (`SYSCM_QFRAME` \| `SYSCM_SONGPOS` \| `SYSCM_SONGSEL` \| `SYSCM_TUNEREQ`)
`SYSRT`	Any system realtime event (`SYSRT_CLOCK` \| `SYSRT_START` \| `SYSRT_CONTINUE` \| `SYSRT_STOP` \| `SYSRT_SENSING` \| `SYSRT_RESET`)
`SYSTEM`	Any system (non-channel) event (`SYSEX` \| `SYSCM` \| `SYSRT`)
`NONE`	No event
`ANY`	Any event

Event types are bit masks, so when building filters, they can be combined using operators | (bitwise or) and ~ (bitwise negation).

Event Attributes¶

These constants are used by Generators and the SceneSwitch() unit to refer to an event’s data attributes:

Symbolic constant
`EVENT_PORT`
`EVENT_CHANNEL`
`EVENT_DATA1`
`EVENT_DATA2`
`EVENT_NOTE`
`EVENT_VELOCITY`
`EVENT_CTRL`
`EVENT_VALUE`
`EVENT_PROGRAM`

Note Names and Ranges¶

Many mididings units accept notes and/or note ranges as parameters. Notes can be specified either as a MIDI note number or by their name, consisting of one letter, optionally 'b' or '#', and an octave number. Examples of valid note names are 'c3', 'g#4', or 'eb2'.

Note ranges can be specified either as a 2-tuple of note numbers or names, e.g. (48, 60) or ('c2', 'c3'), or as two note names separated by a colon, e.g. 'g#3:c6'.

Like all ranges in Python, note ranges are semi-open (do not include their upper limit), so 'g#3:c6' matches notes from g#3 up to b5, but not c6. It’s also possible to omit either the upper or the lower limit, for example 'c4:' matches all notes above (and including) c4, while ':a2' matches all note up to (but not including) a2.

Port Names¶

Internally, ports are always referred to by their number. For instance, when an event is received on the second input port, and is not explicitly routed to another port, it will be sent to the second output port, regardless of port names.

If you named your input and output ports using the in_ports and out_ports parameters to config(), you can also refer to them by their names in all units that accept ports as parameters.

To avoid ambiguities, port names should be unique (with the JACK backend they must be).

mididings and Python¶

mididings is a little peculiar in the way it uses Python, so here’s a couple of things you might need to know…

Overloaded Functions¶

Python does not support overloaded functions per se, but mididings implements a mechanism that allows functions to have behave differently depending not only on the number of arguments, but also on the parameters’ names.

For example, while Velocity(offset=32) increases MIDI note velocities by 32, Velocity(fixed=32) changes velocities to a fixed value of 32.

When multiple versions of a function accept the same number of parameters, it’s necessary to explicitly name the parameters of the version you’d like to use. Cases where parameter names are mandatory are indicated in this documentation by an equal sign followed by an ellipsis, as in Velocity(fixed=…). Most functions also have a “default” version that does not require specifying the name of any parameter. In mididings it is usually possible to explicitly name parameters though, regardless of whether it’s actually required for a particular function invocation.

Other than that, the documentation follows common Python conventions for the notation of positional arguments, variable arguments and keyword arguments.

Everything is an Object¶

Everything in mididings is a Python object, and can be assigned to variables, returned from functions, etc.:

# add a fifth (7 semitones) above each note, and route all events
# to channel 2 (of course there are easier ways to do this)
def add_interval(n):
    return Pass() // Transpose(n)

route = Channel(2)
mypatch = add_interval(7) >> route

run(mypatch)

Line Break and Indentation¶

As in any other Python code, line breaks delimit statements, and indentation delimits blocks. However, as a rule of thumb, both line breaks and indentation are irrelevant as long as at least one parenthesis or bracket remains open.

Many mididings patches consist of lists and dictionaries, so line breaks and indentation may not be an issue, but often it is convenient to put patches in parentheses in order to allow them to span multiple lines:

mypatch = (
    Filter(~PROGRAM) >> Print("this line is getting kind of long") >>
    Transpose(12) >> Velocity(curve=1.0)
)

Operator Precedence¶

Overloading operators in Python can not change their precedence. This is a list of all operators relevant to mididings, in order of their precedence (highest to lowest):

Operator	Meaning in mididings
(…) [A, B, …]	Binding (parentheses) Connection in parallel (list)
~F -F +F	Filter inversion Filter negation Apply to duplicate
A // B S % A	Connection in parallel Selector “then”
A >> B	Connection in series
S1 & S2	Selector “and”
S1 \| S2	Selector “or”

In short, remember that…

parallel connection binds stronger than serial.
selectors (of more than one filter) must be in parentheses.
when in doubt, you can always use additional parentheses.

Note

Operator overloading doesn’t apply if both sides of the operator are builtin Python types like list or dict. In some cases it may be necessary to wrap those in Fork() or Split().