Tether Midi Mediator

Turns incoming MIDI (from your plugged-in device, or virtual device) into outgoing Tether messages in a standard form on plugs with standard names.

Running

Download a release for your OS, and run it!

Available MIDI input ports will be detected automatically.

Tether MIDI Messages

This Agent translates MIDI into standardised Tether Messages on standard plugs.

• ControlChange (knob/slider) input
  • Published on the plug "controlChange"
  • Keys are
    • channel: MIDI channel
    • control: knob/slider number/ID
    • value: absolute value 0-127
• Note On input
  • Published on the plug "notesOn"
  • Keys are
    • channel: MIDI channel
    • note: MIDI note number
    • velocity: volume/pressure 0-127
• Note Of input
  • Published on the plug "notesOff"
  • Keys are
    • channel: MIDI channel
    • note: MIDI note number
    • velocity: volume/pressure 0-127 (typically 0)

In addition, the "untranslated" MIDI message, as parsed by the underyling midi-msg library, is published on a plug "raw".

Absolute vs Relative mode

When it comes to Control Change messages, some MIDI controllers send absolute values from 0-127 depending on the knob position. This is the "standard" way.

Other controllers, particularly those with "endless" knobs (no stop points), send values meant to be interpreted as relative increase/decrease values. Tether Midi Mediator automatically handles this situation when in Relative mode (either select this in the GUI or pass --midi.relative flag from command line). The behaviour in relative mode is:

• Values in the lower half of the range (0-63) are interpreted as increment speeds
• Values in the upper half of the range (64-127) are interpreted as decrement speeds
• Any "previously known" value for the same channel+controller is recalled and the increment/decrement is applied; the range is also clamped if necessary
• The "controlChange" plug will publish only the absolute values; the "raw" plug will contain the original values sent by the controller

Relative-mode is not standardised for MIDI devices. The above mechanism has been tested with an Akai APC Key25 Mk2. Submit an Issue if you think alternative algorithms should be possible.

CLI options

You can change various settings using the command line. Append --help for more details.

For example:

• --headless: run without a GUI - great for server / console-based use
• --tether.disable: don't try to connect to MQTT Broker at all
• Numbers following params, eg. ./tether-midi-mediator 0 1 will only use MIDI input ports 0 and 1

TODO

• Handle "relative mode" knob controller values, e.g. Akai APC Key25
• Display incoming MIDI messages AND outgoing Tether messages
• Make it possible to list ports, optionally specify inputs
• Convert, and possibly visualise, MIDI note numbers -> actual notes
• Convert the other way, i.e. Tether Messages -> Midi Output