Generated on: 2009-04-16.
Contents
RtMidiRouter is a small but powerful command line tool which allows you to route, manipulate and create MIDI messages. For reliable realtime performance RtMidiRouter is based on RtMidi. It is controllable via command line and network (OSC).
RtMidiRouter is currently in beta phase. There are no binary packages available for now and it has been tested and successfully compiled on Linux only.
This file contains the complete documentation for RTmidiRouter. It is available in different formats but always with the same content. The source tarball contains a README (plain text) and a HTML Version doc/RTMidiRouter.html. The most current version is always available on the project website: http://rtmidirouter.sourceforge.net
Additionally rtmidirouter --help and rtmidirouterd --help will help you on the command line.
Stable releases are available in the download section on sourceforge:
https://sourceforge.net/project/showfiles.php?group_id=218768
The latest development version is available via git. You can view the file in your browser:
http://rtmidirouter.git.sourceforge.net/git/gitweb.cgi?p=rtmidirouter
or clone the entire repository:
git clone git://rtmidirouter.git.sourceforge.net/gitroot/rtmidirouter
Requirements:
Extract archive and type:
cd rtmidirouter cmake . make sudo make install
This sections is a short guide for the basic usage of RTMidiRouter.
RtMidirouter actually consists of 2 executables:
rtmidirouterd is the main part of the application. It does the real work, creates the layers and handles all MIDI messages. Type rtmidirouterd --help to list all available options.
To start the server open a new terminal session and type rtmidirouterd:
$ rtmidirouterd RtMidiRouter Copyright (C) 2008 Christian Torff This program comes with ABSOLUTELY NO WARRANTY This is free software, and you are welcome to redistribute it under certain conditions; See COPYING for details. Listening on Port 7770.
The default port rtmidirouterd is listening on is 7770. You can change the port with the --port option. For example:
$ rtmidirouterd --port 7000
To control the server you need an OSC client. A list of available OSC Command can be found in Section Commands. Or you can use the rtmidrouter client (seebelow).
The client is a small helper tool (type rtmidirouter --help for online help). It wraps the OSC stuff into handy command line options. This also allows you to put these commands into shell scripts [1]
Open another terminal session and type rtmidirouter --probe. The client will send a probe request on the default port. In the server terminal session you will see the result which may look like the following:
There are 2 MIDI input ports available. Input Port #0: USB MIDI Interface Input Port #1: Viewer Port 0 There are 2 MIDI output ports available. Output Port #0: USB MIDI Interface Output Port #1: Viewer Port 0
As you can see there are 2 input ports and 2 output ports available. This information is important for you to know (as you surely don't want to connect randomly to some ports). Next we will create a new layer called "leadSynth". Then we connect the "USB MIDI Interface" as input source and the "Viewer Port 0" as output port to the layer:
$ rtmidirouter --add-layer leadSynth Layer "leadSynth" created. $ rtmidirouter --layer leadSynth --connect-in-port 0 $ rtmidirouter --layer leadSynth --connect-out-port 1
To check if everything went fine you can use the "info" command:
$ rtmidirouter --layer leadSynth --info Layer leadSynth configuration: in port USB MIDI Interface out port Viewer Port 0 in channel 0 out channel 0 bypass 1 range 0 - 127 transpose 0
| [1] | The concept is mostly inspired by iptables, the user frontend for the linux kernel firewall |
The following OSC paths are available:
/quit
Parameters: None
Shutdown RTMidirouter.
/probe
Parameters: None
Display available MIDI input and output ports.
/info
Parameters: None
Display information for all layers.
/panic
Parameters: None
Send control change command "all notes off" to all layers.
/reset
Parameters: None
Send control change command "reset all controllers" to all layers.
/add_layer
Parameters: s - Layer name.
Create a new layer.
/remove_layer
Parameters: s - Layer to remove.
Remove layer.
/remove_all_layers
Parameters: None
Remove all layer.
/layer/info
Parameters: s - Layer name
Display information for selected Layer.
/layer/connect_in_port
Parameters: si or ss - Layer name and Port ID or Port name
Connect MIDI input port. The port descriptor can either be a string (s) or an ID (i).
/layer/connect_out_port
Parameters: si or ss - Layer name and Port ID or Port name
Connect MIDI output port. The port descriptor can either be a string (s) or an ID (i).
/layer/connect_in_port
Parameters: s - Layer name
Disconnect MIDI input port.
/layer/connect_out_port
Parameters: s - Layer name
Disconnect MIDI output port.
/layer/in_channel
Parameters: si - Layer name and channel number [0..15]
Set MIDI channel i as input channel.
/layer/out_channel
Parameters: si - Layer name and channel number [0..15]
Set MIDI channel i as output channel.
/layer/lo_key
Parameters: si - Layer name and key number [0..127]
Set low key to i. (Range from i to hi_key)
/layer/hi_key
Parameters: si - Layer name and key number [0..127]
Set high key to i. (Range from lo_ley to i)
/layer/transpose
Parameters: si - Layer name and transpose value [-127..127]
Transpose all outgoing key by i
/layer/send_message
Parameters: sii[i] - Layer name and midi message,
Send 2 or 3 bytes.
/layer/panic
Parameters: s[i] - Layer name and optional channel
Send panic on selected or all channels.
/layer/volume
Parameters: si - Layer name and volume [0..127]
Set channel volume.
If you do not want to use rtmidirouter to control the server you need some other osc client. For this example I will use the python module simpleOSC.
First make shure RtMidiRouter is running or start it now:
$ rtmidirouterd
This will start RtMidiRouter on the default port 7770. Now you can open another console and start python or create a new file where you put your commands in:
>>> import osc
>>> osc.init()
>>> osc.sendMsg("/probe", [], "127.0.0.1", 7770)
>>> osc.sendMsg("/add_layer", ["piano"], "127.0.0.1", 7770)
>>> osc.sendMsg("/layer/piano/connect", [0,2], "127.0.0.1", 7770)
....
>>> osc.sendMsg("/quit", [], "127.0.0.1", 7770)
In the example above the available MIDI ports are displayed (probe). With add_layer a new layer is created and connected to input port 0 and output port 2. Now you should be able to send MIDI from input port 0 to output port 2.
16.04.2009
Release 0.3! Finally, after +1 year it is time to release all the improvements since v0.2. The application has changed dramatically into a more robust and flexible client server model. Beside, some new OSC commands are available (panic, reset, send_message). Documentation has been updated for the new features.
10.03.2008
Release 0.2 is out! Shell support is now available and beside some new commands (like send_message) some changes in the command syntax were made. (Layer id now within path). Ports can now be connected by name or id.
29.02.2008
Release 0.1 is the first official release. Only OSC support implemented.
Copyright (C) 2008-2009 - Christian Torff
RtMidiRouter is licensed under the GPLv3. That means this is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
RTMidiRouter is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
Documentation:
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License (FDL), Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections.
Generated on: 2009-04-16.