# The MIDIMonster
[![Build Status](https://travis-ci.com/cbdevnet/midimonster.svg?branch=master)](https://travis-ci.com/cbdevnet/midimonster)
[![Coverity Scan Build Status](https://scan.coverity.com/projects/15168/badge.svg)](https://scan.coverity.com/projects/15168)
[![IRC Channel](https://static.midimonster.net/hackint-badge.svg)](https://webirc.hackint.org/#irc://irc.hackint.org/#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`](backends/midi.md), [`winmidi`](backends/winmidi.md), [`jack`](backends/jack.md) |
| ArtNet | Linux, Windows, OSX | Version 4 | [`artnet`](backends/artnet.md) |
| Streaming ACN (sACN / E1.31) | Linux, Windows, OSX | | [`sacn`](backends/sacn.md) |
| OpenSoundControl (OSC) | Linux, Windows, OSX | | [`osc`](backends/osc.md) |
| RTP-MIDI | Linux, Windows, OSX | AppleMIDI sessions supported | [`rtpmidi`](backends/rtpmidi.md) |
| OpenPixelControl | Linux, Windows, OSX | 8 Bit & 16 Bit modes | [`openpixelcontrol`](backends/openpixelcontrol.md) |
| Input devices (Mouse, Keyboard, etc)| Linux, Windows | | [`evdev`](backends/evdev.md), [`wininput`](backends/wininput.md) |
| Open Lighting Architecture | Linux, OSX | | [`ola`](backends/ola.md) |
| MA Lighting Web Remote | Linux, Windows, OSX | GrandMA2 and dot2 (incl. OnPC) | [`maweb`](backends/maweb.md) |
| JACK/LV2 Control Voltage (CV) | Linux, OSX | | [`jack`](backends/jack.md) |
| Lua Scripting | Linux, Windows, OSX | | [`lua`](backends/lua.md) |
| Python Scripting | Linux, OSX | | [`python`](backends/python.md) |
| Loopback | Linux, Windows, OSX | | [`loopback`](backends/loopback.md) |
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](configs/unifest-17.cfg))
* Translate MIDI Notes into ArtNet or sACN ([Example configuration](configs/launchctl-sacn.cfg))
* Translate OSC messages into MIDI ([Example configuration](configs/midi-osc.cfg))
* Dynamically generate, route and modify events using the Lua programming language ([Example configuration](configs/lua.cfg) and [Script](configs/demo.lua))
to create your own lighting controller or run effects on TouchOSC (Flying faders demo [configuration](configs/flying-faders.cfg) and [script](configs/flying-faders.lua))
* 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](configs/evdev.cfg))
* Connect a device speaking RTP MIDI (for example, an iPad) to your computer or lighting console ([Example configuration](configs/rtpmidi.cfg))
* Play games, type, or control your mouse using MIDI controllers ([Example configuration](configs/midi-mouse.cfg))
If you encounter a bug or suspect a problem with a protocol implementation, please
[open an Issue](https://github.com/cbdevnet/midimonster/issues) or get in touch with us via
IRC on [Hackint in `#midimonster`](https://webirc.hackint.org/#irc://irc.hackint.org/#midimonster).
We are happy to hear from you!
# Table of Contents
* [Usage](#usage)
* [Configuration](#configuration)
* [Backend documentation](#backend-documentation)
* [Installation](#installation)
+ [Using the installer](#using-the-installer)
+ [Building from source](#building-from-source)
- [Building for Linux/OSX](#building-for-linuxosx)
- [Building for Packaging](#building-for-packaging)
- [Building for Windows](#building-for-windows)
* [Development](#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 *instance*s, 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 ]`. This will read the referenced configuration file as
if it were inserted at that point.
Example configuration files may be found in [configs/](configs/).
### Backend and instance configuration
A configuration section may either be a *backend configuration* section, started by
`[backend ]`, an *instance configuration* section, started by
`[]` or a *mapping* section started by `[map]`.
Backends document their global options in their [backend documentation](#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
`[]` 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 .