mididings - Extra Module Reference

Units

These units offer some more advanced/specific functionality than what's provided in the core mididings module. Unless otherwise noted, they are defined in the mididings.extra module.

Note that some of these units are implemented in Python using Process(), and are thus not safe to use with the jack-rt backend.

Harmonize(tonic, scale, interval, non_harmonic='below')

A diatonic harmonizer.

Add a third above each note, based on the C# harmonic minor scale:
Harmonize('c#', 'minor_harmonic', ['unison', 'third'])

FloatingKeySplit(threshold_lower, threshold_upper, patch_lower, patch_upper, hold_time=1.0, margin_lower=12, margin_upper=12)

Creates a floating split point that moves dynamically depending on what you are playing, allowing a region of the keyboard to be shared between two split zones.

Split the keyboard somewhere between C2 and C3:
FloatingKeySplit('c2', 'c3', Channel(1), Channel(2))

VoiceFilter(voice='highest', time=0.1, retrigger=False)

Filters individual voices from a chord.

voice must be 'highest', 'lowest', or an index (positive or negative, the same way Python lists are indexed, with 0 being the lowest voice).
When a key is already held, and then becomes active for this voice because another key was pressed/released, the note will only be played if retrigger is True, or if the time since the key-press is less than the number of seconds specified by the time parameter.

VoiceSplit([patch, ...], fallback='highest', time=0.1, retrigger=False)

Creates multiple VoiceFilter() units to route each voice to a different instrument.

Regardless of the number of voices specified, the lowest and highest note played will always be routed to the first and last patch in the list, respectively. When the number of notes played is less than the number of voices specified, "surplus" voices will fall back to the highest or lowest note played, as specified by the fallback parameter.

Route up to three voices to different channels:
VoiceSplit([Channel(1), Channel(2), Channel(3)])

LimitPolyphony(max_polyphony, remove_oldest=True)

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.

MakeMonophonic()

Makes the MIDI signal "monophonic", i.e. only one note can be played at any given time. When one note is released while another is still held (but silent), the previous one will be retriggered.

SuppressPC()

Filters out program changes if the same program had previously been selected on the same port/channel.

PedalToNoteoff(ctrl=64, sostenuto=False)

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.

LatchNotes(polyphonic=False, reset=None)

Makes notes latching, so they will keep playing when the key is released.

If polyphonic is False, pressing a key will automatically turn off any previous notes. If polyphonic is True, each note can be stopped individually by pressing the corresponding key again. reset can be a note name/number that when pressed stops all currently playing notes.

KeyColorFilter(color)

Filters notes by key color ('black' or 'white').

Panic(bypass=True)

Generates all-notes-off messages (CC #123) on all channels. If bypass is True, these messages will be sent directly on all output ports, without going through the rest of the patch.

SendOSC(target, path, ...)

Defined in mididings.extra.osc. Requires pyliblo.

Sends an OSC message. Parameters are the same as for liblo.send(). Additionally, instead of a specific value, each data argument can also be a Python function that takes a single MidiEvent parameter, and returns the value to be sent.

SendDBUS(service, path, interface, method, ...)

Defined in mididings.extra.dbus. Requires dbus-python.

Sends a DBUS message. Instead of a specific value, each data argument can also be a Python function that takes a single MidiEvent parameter, and returns the value to be sent.

Change FFADO output volume using a MIDI controller:
CtrlFilter(42) >> SendDBUS(
    'org.ffado.Control',
    '/org/ffado/Control/DeviceManager/%s/Mixer/OUT0Gain' % DEVICEID,
    'org.ffado.Control.Element.Continuous',
    'setValue',
    lambda ev: ev.value * (2**17)
)

Hooks

MemorizeScene(memo_file)

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.

OSCInterface(port=56418, notify_ports=[56419])

Defined in mididings.extra.osc. Requires pyliblo.

Allows controlling mididings via OSC. These messages are currently understood:

AutoRestart(modules=True, filenames=[])

Defined in mididings.extra.inotify. Requires pyinotify ≥ 0.8.

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.

Miscellaneous

livedings

livedings is a graphical frontend for mididings that allows you to monitor and trigger scene changes. It runs as a separate application that uses OSC to communicate with mididings. To use it, enable the OSCInterface hook in your mididings script:

from mididings.extra.osc import OSCInterface

hook(OSCInterface())
...

Then run livedings:

$ livedings

By default, livedings uses the standard Tk theme. Specify the -T option to switch to a custom theme with higher contrast and larger fonts. See 'livedings --help' for more options.

The buttons at the bottom of the screen can be used to switch to the previous/next scene, previous/next subscene, and to send all-notes-off messages (panic) on all output ports. It's also possible to use the arrow keys to switch scenes (up/down) and subscenes (left/right).

gm

The mididings.extra.gm module contains constants for program and controller numbers defined in the General MIDI standard.

Programs:
ACOUSTIC_GRAND_PIANO
BRIGHT_ACOUSTIC_PIANO
ELECTRIC_GRAND_PIANO
HONKY_TONK_PIANO
ELECTRIC_PIANO_1
ELECTRIC_PIANO_2
HARPSICHORD
CLAVINET
CELESTA
GLOCKENSPIEL
MUSIC_BOX
VIBRAPHONE
MARIMBA
XYLOPHONE
TUBULAR_BELLS
DULCIMER
DRAWBAR_ORGAN
PERCUSSIVE_ORGAN
ROCK_ORGAN
CHURCH_ORGAN
REED_ORGAN
ACCORDION
HARMONICA
TANGO_ACCORDION
ACOUSTIC_GUITAR_NYLON
ACOUSTIC_GUITAR_STEEL
ELECTRIC_GUITAR_JAZZ
ELECTRIC_GUITAR_CLEAN
ELECTRIC_GUITAR_MUTED
OVERDRIVEN_GUITAR
DISTORTION_GUITAR
GUITAR_HARMONICS
ACOUSTIC_BASS
ELECTRIC_BASS_FINGER
ELECTRIC_BASS_PICK
FRETLESS_BASS
SLAP_BASS_1
SLAP_BASS_2
SYNTH_BASS_1
SYNTH_BASS_2
VIOLIN
VIOLA
CELLO
CONTRABASS
TREMOLO_STRINGS
PIZZICATO_STRINGS
ORCHESTRAL_HARP
TIMPANI
STRING_ENSEMBLE_1
STRING_ENSEMBLE_2
SYNTH_STRINGS_1
SYNTH_STRINGS_2
CHOIR_AAHS
VOICE_OOHS
SYNTH_VOICE
ORCHESTRA_HIT
TRUMPET
TROMBONE
TUBA
MUTED_TRUMPET
FRENCH_HORN
BRASS_SECTION
SYNTHBRASS_1
SYNTHBRASS_2
SOPRANO_SAX
ALTO_SAX
TENOR_SAX
BARITONE_SAX
OBOE
ENGLISH_HORN
BASSOON
CLARINET
PICCOLO
FLUTE
RECORDER
PAN_FLUTE
BLOWN_BOTTLE
SHAKUHACHI
WHISTLE
OCARINA
LEAD_1_SQUARE
LEAD_2_SAWTOOTH
LEAD_3_CALLIOPE
LEAD_4_CHIFF
LEAD_5_CHARANG
LEAD_6_VOICE
LEAD_7_FIFTHS
LEAD_8_BASS_LEAD
PAD_1_NEW_AGE
PAD_2_WARM
PAD_3_POLYSYNTH
PAD_4_CHOIR
PAD_5_BOWED
PAD_6_METALLIC
PAD_7_HALO
PAD_8_SWEEP
FX_1_RAIN
FX_2_SOUNDTRACK
FX_3_CRYSTAL
FX_4_ATMOSPHERE
FX_5_BRIGHTNESS
FX_6_GOBLINS
FX_7_ECHOES
FX_8_SCI_FI
SITAR
BANJO
SHAMISEN
KOTO
KALIMBA
BAGPIPE
FIDDLE
SHANAI
TINKLE_BELL
AGOGO
STEEL_DRUMS
WOODBLOCK
TAIKO_DRUM
MELODIC_TOM
SYNTH_DRUM
REVERSE_CYMBAL
GUITAR_FRET_NOISE
BREATH_NOISE
SEASHORE
BIRD_TWEET
TELEPHONE_RING
HELICOPTER
APPLAUSE
GUNSHOT

Controllers:
CTRL_BANK_SELECT_MSB
CTRL_MODULATION
CTRL_DATA_ENTRY_MSB
CTRL_VOLUME
CTRL_PAN
CTRL_EXPRESSION
CTRL_BANK_SELECT_LSB
CTRL_DATA_ENTRY_LSB
CTRL_SUSTAIN
CTRL_PORTAMENTO
CTRL_SOSTENUTO
CTRL_SOFT_PEDAL
CTRL_LEGATO_PEDAL
CTRL_NRPN_LSB
CTRL_NRPN_MSB
CTRL_RPN_LSB
CTRL_RPN_MSB
CTRL_RESET_ALL_CONTROLLERS
CTRL_ALL_NOTES_OFF