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 (namedin_nandout_n, respectively, wherenis 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)¶
- runrun(scenes=..., control=None, pre=None, post=None)¶
- 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 - Sceneobjects,- SceneGroupobjects 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 - Sceneobjects 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),
])