Module mididings

Global Configuration

These global settings can be configured using the config() function described below:

backend

The MIDI backend to be used:

  • 'alsa': Use the ALSA sequencer.
  • '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': Use JACK MIDI. All MIDI events are processed directly in the JACK process callback, with no additional latency.

The default, if available, is 'alsa'.

Note

Python code is not realtime safe, so it’s recommended not to use the Process() unit in conjunction with the jack-rt backend.

With the buffering jack backend, Python code that does not finish in time merely causes MIDI events from mididings to be slightly delayed. With the jack-rt backend, it causes xruns which are potentially audible, may cause loss of MIDI events, and also affect other JACK clients!

In practice, if you require sample-accurate MIDI processing with zero latency, but your JACK period size is large enough, you can often get away with jack-rt running Python code in a realtime context. On the other hand, if your JACK period size is small, the single period of delay caused by the buffering jack backend is likely to be unnoticable.

client_name

The ALSA or JACK client name to be used. The default is 'mididings'.

in_ports
out_ports

Defines the number and names of input and output ports, and optionally external ports to connect them to. The default is one input and one output port.

Possible values are:

  • Integer: Indicates the number of ports to be created (named in_n and out_n, respectively, where n is the port number).
  • List of ports: Each port is either described by a single string specifying its name, or by 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 (client:port) of each external port. ALSA clients and ports can be referred to using either their names or numbers.
# create two input ports
in_ports = 2

# create three output ports with custom names, and automatically
# connect two of those ports to other clients
out_ports = [
    'foo',
    ('bar', '24:0', 'yoshimi:midi in'),
    ('baz', 'LinuxSampler:.*'),
]
data_offset

Determines whether program, port, channel and scene numbers used in your script are in the range 1-128 (with data_offset = 1) or 0-127 (with data_offset = 0). The default is 1.

octave_offset

The note-octave notation used in your script, specified as the number of octaves between MIDI note number 0 and the note called “C0”. The default is 2, meaning that “middle C” (note number 60) is named “C3”. Another typical value is 1, meaning that “middle C” is “C4”.

initial_scene

The number of the first scene to be activated. The default is the scene with the lowest number. Also see MemorizeScene.

start_delay

The number of seconds to wait before sending any MIDI events (i.e. switching to the first scene). A small delay like 0.5 s can be used to give tools like QjackCtl’s patchbay time to connect ports before sending initial MIDI events. A value of 0 instructs mididings to wait for the user to press enter. The default is None, meaning not to wait at all.

Functions

config(**kwargs)

Change global settings. This should usually be called only once at the beginning of the script, before constructing any processing units.

Parameters:

**kwargs – an arbitrary number of keyword arguments, matching the names and values described in section Global Configuration.

# set some configuration values
config(
    client_name = 'test',
    out_ports = 2,
    octave_offset = 1,
)
hook(*args)

Register “hook” objects, that can be used to extend the functionality of mididings. Hook classes that ship with mididings are described in section Hooks.

Parameters:

*args – an arbitrary number of hook objects.

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

Start the MIDI processing. This is usually the last function called by a mididings script. The first version just runs a single patch, while the second version allows switching between multiple scenes.

Parameters:

  • patch – a single patch.

  • scenes – a dictionary with program numbers as keys, and Scene objects, SceneGroup objects or plain patches as values.

  • control – an optional “control” patch, which is always active, and runs in parallel to the current scene.

  • pre – an optional patch that allows common processing to take place before every scene. Does not affect the control patch.

  • post – an optional patch that allows common processing to take place after every scene. Does not affect the control patch.

Classes

class Scene(name, patch, init_patch=None, exit_patch=None)

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

Parameters:

  • 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.

  • exit_patch – an optional patch that will be triggered when switching away from this scene.

class SceneGroup(name, subscenes)

Construct a SceneGroup object. This can be used to group multiple scenes under a common name and program number.

Parameters:

  • name – a string describing the subscene.

  • subscenes – a list of Scene objects or patches.

# define one scene (song) with 3 subscenes (parts)
SceneGroup("Example Song", [
    Scene("Intro", intro_patch),
    Scene("Verse", verse_patch),
    Scene("Chorus", chorus_patch),
])