mididings - Core Module Reference

Functions

config(**kwargs)

Changes global mididings settings. This should be called only once, before constructing any processing units.
Possible keyword arguments are:

• backend: MIDI backend to be used:
  • 'alsa': Use the ALSA sequencer (this is the default).
  • 'jack': Use JACK MIDI. All MIDI events are buffered and processed outside the JACK process callback, and will thus be delayed by (at least) one period.
  • 'jack-rt': MIDI events are processed directly in the JACK process callback. It's not safe to run Python code in a realtime context, so it's recommended to avoid Process(), which might cause xruns (or worse). All other units should be safe to use.
• client_name: MIDI client name to be used.
• in_ports / out_ports: Defines the number and names of input and output ports, and optionally external ports to connect them to. Possible values are:
  • Integers: Simply indicates the number of ports to create (named in_n and out_n, respectively).
    Create two input ports with default names (in_1 and in_2):

    config(in_ports=2)
  • Lists of ports, where each port is described by a string specifying its name, or a list/tuple containing the port name, followed by any number of regular expressions specifying ports to connect to. These regular expressions are matched against the full name (clientname:portname) of each external port. ALSA clients and ports can be specified using either their names or numbers.
    Create three output ports with custom names, and automatically connect two of those ports to other clients:

    config(out_ports=[
        'foo',
        ('bar', '24:0', 'yoshimi:midi in'),
        ('baz', 'LinuxSampler:.*'),
    ])
• data_offset: 1 (default) or 0. Determines whether program, port and channel numbers will be in the range 1-128 or 0-127.
• octave_offset: Offset in octaves from note number 0 to C0. Default is 2, meaning that note number 24 (that is, two octaves up from 0) is designated as C0, and "middle C" (note number 60) is C3.
• initial_scene: The number of the first scene to be activated.
• start_delay: The number of seconds before sending any MIDI events (i.e. switching to the first scene). A small value like 0.5 can be used to give tools like qjackctl's patchbay time to connect the ports. A value of 0 instructs mididings to wait for the user to press enter. Default is None.

hook(*args)

Registers "hook" objects, that can be used to extend the functionality of mididings.

run(patch)

Starts the MIDI processing. This is usually the last function called by a mididings script.

• patch: A single patch.

run(scenes=..., control=None, pre=None, post=None)

Starts the MIDI processing, using multiple scenes. The SceneSwitch() unit can be used to switch between these scenes.

• scenes: A dictionary with program numbers as keys, and Scene objects or plain patches as values. Values can also be tuples with two items, the first being an init-patch that's executed once every time the scenes is selected, and the second being the actual patch that processes incoming events.
• control: The "control" patch, which is always active, and runs in parallel to the current scene.
• pre / post: Allows processing to take place before/after every scene. Does not affect the control patch.

process_file(infile, outfile, patch)

Requires mididings to be compiled with support for libsmf.
Reads a standard MIDI file, processes it, then writes the result back to a file.

Classes

Scene(name, patch, init_patch=None)

Constructs a Scene object to be used with the run() function.

• name: A string describing the scene.
• patch: The patch defining the MIDI processing to take place for incoming events.
• init_patch: An optional patch that will be triggered when switching to this scene.

SceneGroup(name, [subscene, ...])

Constructs a SceneGroup object. This can be used to group multiple scenes under a common name and program number. Each of the subscenes should be a Scene object.

SceneGroup("Example Song", [
    Scene("Intro", intro_patch),
    Scene("Verse", verse_patch),
    Scene("Chorus", chorus_patch),
])

Constants

Event Types

Every event has one of these types:

• NOTEON
• NOTEOFF
• CTRL
• PROGRAM
• PITCHBEND
• AFTERTOUCH
• POLY_AFTERTOUCH
• SYSEX
• SYSCM_QFRAME
• SYSCM_SONGPOS
• SYSCM_SONGSEL
• SYSCM_TUNEREQ
• SYSRT_CLOCK
• SYSRT_START
• SYSRT_CONTINUE
• SYSRT_STOP
• SYSRT_SENSING
• SYSRT_RESET

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

• NOTE = NOTEON | NOTEOFF
• SYSCM = SYSCM_*
• SYSRT = SYSRT_*
• SYSTEM = SYSEX | SYSCM | SYSRT
• NONE
• ANY

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

Event Attributes

These constants are used by generator units and the SceneSwitch() unit to refer to an event's data attributes:

• EVENT_PORT
• EVENT_CHANNEL
• EVENT_DATA1
• EVENT_DATA2
• EVENT_NOTE
• EVENT_VELOCITY
• EVENT_CTRL
• EVENT_VALUE
• EVENT_PROGRAM