The MIDIMonster

Named for its scary math, the MIDIMonster is a universal control and translation tool for multi-channel absolute-value-based control and/or bus protocols.

Currently, the MIDIMonster supports the following protocols:

| Protocol / Interface | Operating Systems | Notes | Backends | |-------------------------------|-----------------------|-------------------------------|---------------------------------------| | MIDI | Linux, Windows, OSX | Linux: via ALSA/JACK, OSX: via JACK | midi, winmidi, jack | | ArtNet | Linux, Windows, OSX | Version 4 | artnet | | Streaming ACN (sACN / E1.31) | Linux, Windows, OSX | | sacn | | OpenSoundControl (OSC) | Linux, Windows, OSX | | osc | | MQTT | Linux, Windows, OSX | Protocol versions 5 and 3.1.1 | mqtt | | RTP-MIDI | Linux, Windows, OSX | AppleMIDI sessions supported | rtpmidi | | OpenPixelControl | Linux, Windows, OSX | 8 Bit & 16 Bit modes | openpixelcontrol | | Input devices (Mouse, Keyboard, etc)| Linux, Windows | | evdev, wininput | | Open Lighting Architecture | Linux, OSX | | ola | | MA Lighting Web Remote | Linux, Windows, OSX | GrandMA2 and dot2 (incl. OnPC) | maweb | | JACK/LV2 Control Voltage (CV) | Linux, OSX | | jack | | VISCA | Linux, Windows, OSX | PTZ Camera control over TCP/UDP | visca | | Lua Scripting | Linux, Windows, OSX | | lua | | Python Scripting | Linux, OSX | | python | | Loopback | Linux, Windows, OSX | | loopback |

With these features, the MIDIMonster allows users to control any channel on any of these protocols, and translate any channel on one protocol into channel(s) on any other (or the same) supported protocol, for example to:

Translate MIDI Control Changes into MIDI Notes (Example configuration)
Translate MIDI Notes into ArtNet or sACN (Example configuration)
Translate OSC messages into MIDI (Example configuration)
Dynamically generate, route and modify events using the Lua programming language (Example configuration and Script) to create your own lighting controller or run effects on TouchOSC (Flying faders demo configuration and script)
Use an OSC app as a simple lighting controller via ArtNet or sACN
Visualize ArtNet data using OSC tools
Control lighting fixtures or DAWs using gamepad controllers, trackballs, etc (Example configuration)
Connect a device speaking RTP MIDI (for example, an iPad) to your computer or lighting console (Example configuration)
Play games, type, or control your mouse using MIDI controllers (Example configuration)

If you encounter a bug or suspect a problem with a protocol implementation, please open an Issue or get in touch with us via IRC on Hackint in #midimonster. We are happy to hear from you!

Usage
Configuration
Backend documentation
Installation
- Using the installer
- Building from source
Development

Usage

The MIDImonster takes as it's first argument the name of an optional configuration file to use (monster.cfg is used as default if none is specified). The configuration file syntax is explained in the next section.

The current MIDIMonster version can be queried by passing -v as command-line argument.

Configuration

Each protocol supported by MIDIMonster is implemented by a backend, which takes global protocol-specific options and provides instances, which can be configured further.

The configuration is stored in a file with a format very similar to the common INI file format. A section is started by a header in [] braces, followed by lines of the form option = value.

Lines starting with a semicolon are treated as comments and ignored. Inline comments are not currently supported.

Configuration files may be included recursively in other configuration files using the syntax [include <file>]. This will read the referenced configuration file as if it were inserted at that point.

Example configuration files may be found in configs/.

Backend and instance configuration

A configuration section may either be a backend configuration section, started by [backend <backend-name>], an instance configuration section, started by [<backend-name> <instance-name>] or a mapping section started by [map].

Backends document their global options in their backend documentation. Some backends may not require global configuration, in which case the configuration section for that particular backend can be omitted.

To make an instance available for mapping channels, it requires at least the [<backend-name> <instance-name>] configuration stanza. Most backends require additional configuration for their instances.

Backend and instance configuration options can also be overridden via command line arguments using the syntax -b <backend>.<option>=<value> for backend options and -i <instance>.<option>=<value> for instance options. These overrides are applied when the backend/instance is first mentioned in the configuration file.

Channel mapping

The [map] section consists of lines of channel-to-channel assignments, reading like

instance.channel-a < instance.channel-b
instance.channel-a > instance.channel-b
instance.channel-c <> instance.channel-d

The first line above maps any event originating from instance.channel-b to be output on instance.channel-a (right-to-left mapping).

The second line makes that mapping a bi-directional mapping, so both of those channels output eachothers events.

The last line is a shorter way to create a bi-directional mapping.

You can map input channels to as many outputs as you like. This will deliver incoming events for each mapped output. You can also map multiple input channels to one common output channel. This will forward all events on the mapped inputs to the output channel (experienced show-control technicians call this a "latest takes precedence" bus).

Multi-channel mapping

To make mapping large contiguous sets of channels easier, channel names may contain certain types of expressions specifying multiple channels at once.

Expressions of the form {<start>..<end>}, with start and end being positive integers, expand to a range of channels, with the expression replaced by the incrementing or decrementing value.

Expressions of the form {value1,value2,value3} (with any number of values separated by commas) are replaced with each of the specified values in sequence.

Multiple such expressions may be used in one channel specification, with the rightmost expression being evaluated first.

Both sides of a multi-channel assignment need to have the same number of channels, or one side must have exactly one channel.

Example multi-channel mapping:

instance-a.channel{1..5} > instance-b.{a,b,c,d,e}

Backend documentation

Every backend includes specific documentation, including the global and instance configuration options, channel specification syntax and any known problems or other special information. These documentation files are located in the backends/ directory.

Installation

This section will explain how to build and install the MIDIMonster. Development is mainly done on Linux, but builds for OSX and Windows are possible.

Binary builds for all supported systems are available for download on the Release page.

Using the installer

The easiest way to install MIDIMonster and its dependencies on a Linux system is the [installer script](install

Midimonster

Install / Use

README