Skip to content
Multi-protocol translation software (ArtNet, MIDI, OSC, ...)
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
backends
configs
.gitignore
.travis-ci.sh
.travis.yml
LICENSE.txt
Makefile
README.md
TODO
backend.c
backend.h
config.c
config.h
midimonster.c
midimonster.h
monster.cfg
plugin.c
plugin.h
portability.h

README.md

The MIDIMonster

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

Currently, the MIDIMonster supports the following protocols:

  • MIDI (Linux, via ALSA)
  • ArtNet
  • sACN / E1.31
  • OSC
  • evdev input devices (Linux)
  • Open Lighting Architecture (OLA)

The MIDIMonster allows the user to translate any channel on one protocol into channel(s) on any other (or the same) supported protocol, for example to:

Build Status Coverity Scan Build Status

Table of Contents

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.

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.

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].

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.

Example configuration files may be found in configs/.

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.

Building

This section will explain how to build the provided sources to be able to run midimonster.

Prerequisites

In order to build the MIDIMonster, you'll need some libraries that provide support for the protocols to translate.

  • libasound2-dev (for the MIDI backend)
  • libevdev-dev (for the evdev backend)
  • libola-dev (for the optional OLA backend)
  • pkg-config (as some projects and systems like to spread their files around)
  • A C compiler
  • GNUmake

Build

Just running make in the source directory should do the trick.

Some backends have been marked as optional as they require rather large additional software to be installed, for example the ola backend. To build these, run make full in the backends directory.

Development

The architecture is split into the midimonster core, handling mapping and resource management, and the backends, which are shared objects loaded at start time, which provide a protocol mapping to instances / channels.

The API and structures are more-or-less documented in midimonster.h, more detailed documentation may follow.

To build with clang sanitizers and even more warnings enabled, run make sanitize. This is useful to check for common errors and oversights.

For runtime leak analysis with valgrind, you can use make run.

You can’t perform that action at this time.