A bridge between MIDI and OpenSoundControl
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

MidiOSC : (C) 2017 Jonny Stutters : jstutters@jeremah.co.uk : jeremah.co.uk

MidiOSC is a small program to bridge the worlds of MIDI and OSC by providing bidirectional conversion of MIDI to OSC. Released under the GPLv2 license.

Building MidiOSC

MidiOSC is not currently distributed as a binary for any platform so you will need to build it from source. MidiOSC is known to build successfully on OSX 10.5-10.11 and Ubuntu 9.10.

Dependencies

MidiOSC depends on the liblo OSC library (liblo.sourceforge.net). Liblo is available through the packaging system of many Linux distributions and is known to compile on OSX. Before attempting to compile MidiOSC you should ensure that the liblo library and headers are in the appropriate location for your system (/usr/lib and /usr/include usually)

Due to complexities with MacOS' installation methods, the scons configuration runs pkg-config to ensure correct paths. This, as well as liblo itself, can be installed via homebrew:

# install homebrew
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" < /dev/null 2> /dev/null

# install liblo and pkg-config
brew install pkg-config
brew install liblo

# if not already installed, build scons
brew install scons

Compiling

Unpack the MidiOSC sourcecode the in a terminal change to the newly created directory. Run the command "scons". If compilation is successful you should see "scons: done building targets." in the output.

Installation

MidiOSC does not need to be installed, for easy access you may prefer to move the midiosc binary to somewhere in your systems path (e.g. /usr/local/bin).

Using MidiOSC

Starting up

Start MidiOSC by typing "midiosc" (assuming the MidiOSC binary is somewhere in your path). You will be asked to select the MIDI ports that you want to open for input and output (for multiple ports enter a space separated list). After the ports have been selected MidiOSC will begin to listen for MIDI and OSC input. The IP addresses and ports can be changed when starting MidiOSC, enter "midiosc --help" for more details. By default MidiOSC sends to localhost:8000 and listens on port 7001.

Example

An example Python program is included with MidiOSC, see example.py.

MIDI input

When MidiOSC receives MIDI input it will generate an OSC message with the address: /midi/[Device name]/[Channel]

Note that:

  • the channel will be omitted from global MIDI messages (e.g. timing pulses)
  • any spaces in the device name will be replaced by underscores

The OSC message will have the a string argument indicating the type of MIDI message (e.g. note on, control change) and a number of integer arguments appropriate to the type of MIDI message (e.g. note number and velocity for a note on message). See the tables below to see the message type strings used and the number of integer arguments that will be generated.

MIDI output

To generate a MIDI message, send MidiOSC an OSC message. MidiOSC expects input of the same type of OSC messages that it sends. At the moment MidiOSC is not strict about input parameters, users should ensure that they provide appropriate types of data (e.g. a note on message should have two integer arguments in addition to the message type argument. MidiOSC does not currently support output of sysex MMC messages.

Supported message types

Normal messages

Message type        MIDI byte   Arguments

note_off            0x80        2
note_on             0x90        2
key_pressure        0xa0        2
controller_change   0xb0        2
program_change      0xc0        2
channel_pressure    0xd0        2
pitch_bend          0xe0        2
song_position       0xf2        2
song_select         0xf3        2
tune_request        0xf6        2
timing_tick         0xf8        0
start_song          0xfa        0
continue_song       0xfb        0
stop_song           0xfc        0

Sysex messages (input only)

Message type        MIDI byte

mmc_stop            0x01
mmc_play            0x02
mmc_fast_forward    0x04
mmc_rewind          0x05
mmc_record          0x06
mmc_pause           0x09

Need help?

If you find any problems with MidiOSC please drop me an email to the address at the top of this file and I'll see what I can do to sort it out or create an issue on GitHub.

Contributions

Fixes and improvements to MidiOSC are gratefully received. Please offer patches for consideration via GitHub.

Thanks

MidiOSC was made possible by:

A big thanks to the developers who made contributions: