File	Date	Author	Commit
ArchLinux	2010-07-14	Christian Torff	[be9289] Client updates
doc	2011-03-20	Christian Torff	[011cda] documentation update
src	2011-03-20	Christian Torff	[f3b9e2] fix: missing ports when probing
.gitignore	2009-04-16	Christian Torff	[54fdce] cmakelist updates
CMakeLists.txt	2010-05-30	Christian Torff	[4f2720] minor doc and build updates
COPYING	2008-02-27	Christian Torff	[df1e2e] Imported project.
README	2011-03-20	Christian Torff	[011cda] documentation update
TODO	2010-05-30	Christian Torff	[4e843c] new paths, minor fixes and cleanups
vimproject	2010-07-14	Christian Torff	[be9289] Client updates

Read Me

<?xml version="1.0" encoding="utf-8" ?>



RRttMMiiddiiRRoouutteerr

RtMidiRouter is a tool for routing and manipulating MIDI messages.
FFeeaattuurreess

* realtime MIDI support via _R_t_M_i_d_i
* network controllable with OSC (_l_i_b_l_o)
* command line client for easy scripting
* unlimited layers to connect MIDI ports to
* configurable key ranges, transpose values, channels, etc
* sending arbitrary MIDI messages

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.
DDooccuummeennttaattiioonn
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: _h_t_t_p_:_/_/
_r_t_m_i_d_i_r_o_u_t_e_r_._s_o_u_r_c_e_f_o_r_g_e_._n_e_t
Additionally the follwoing commands will help you on the command line:

  rtmidirouterd --help
  rtmidirouter --help

Contents

* _1_ _ _ _D_o_w_n_l_o_a_d
* _2_ _ _ _B_u_i_l_d_ _a_n_d_ _i_n_s_t_a_l_l
* _3_ _ _ _U_s_a_g_e

  o _3_._1_ _ _ _r_t_m_i_d_i_r_o_u_t_e_r_d
  o _3_._2_ _ _ _r_t_m_i_d_i_r_o_u_t_e_r

* _4_ _ _ _O_S_C_ _I_n_t_e_r_f_a_c_e

  o _4_._1_ _ _ _S_e_n_d_i_n_g_ _O_S_C_ _m_e_s_s_a_g_e_s
  o _4_._2_ _ _ _C_o_m_m_a_n_d_ _r_e_f_e_r_e_n_c_e

* _5_ _ _ _H_i_s_t_o_r_y
* _6_ _ _ _L_i_c_e_n_s_e



_11_ _ _ _DD_oo_ww_nn_ll_oo_aa_dd

Stable releases are available in the download section on sourceforge:

     _h_t_t_p_s_:_/_/_s_o_u_r_c_e_f_o_r_g_e_._n_e_t_/_p_r_o_j_e_c_t_/_s_h_o_w_f_i_l_e_s_._p_h_p_?_g_r_o_u_p___i_d_=_2_1_8_7_6_8

The latest development version is available via git. You can view the file in
your browser:

     _h_t_t_p_:_/_/_r_t_m_i_d_i_r_o_u_t_e_r_._g_i_t_._s_o_u_r_c_e_f_o_r_g_e_._n_e_t_/_g_i_t_/
     _g_i_t_w_e_b_._c_g_i_?_p_=_r_t_m_i_d_i_r_o_u_t_e_r_/_r_t_m_i_d_i_r_o_u_t_e_r_;_a_=_s_u_m_m_a_r_y

or clone the entire repository:

  git clone git://rtmidirouter.git.sourceforge.net/gitroot/rtmidirouter/
  rtmidirouter



_22_ _ _ _BB_uu_ii_ll_dd_ _aa_nn_dd_ _ii_nn_ss_tt_aa_ll_ll

Requirements for buidling RtMidiRouter are:

* _l_i_b_l_o
* _c_m_a_k_e

Extract the archive, build, and install:

  tar xvjf rtmidirouter-<VERSION>.tar.bz2
  cd rtmidirouter
  cmake .
  make
  sudo make install



_33_ _ _ _UU_ss_aa_gg_ee

This sections is a short guide for the basic usage of RTMidiRouter.
RtMidiRouter actually consists of 2 executables:

* rtmidrouterd - which is the server and
* rtmidirouter - which is a client you can use (but do not need to) to control
  the server. The server is controllable with any OSC client (see section
  _S_e_n_d_i_n_g_ _O_S_C_ _m_e_s_s_a_g_e_s).


_33_.._11_ _ _ _rr_tt_mm_ii_dd_ii_rr_oo_uu_tt_ee_rr_dd

rtmidirouterd is a server and the main part of the application. It does the
real work, creates the layers and handles all MIDI messages. It is configurable
at runtime over an OSC interface. Type rtmidirouterd --help to list all
available _o_p_t_i_o_n_s.
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.

Port 7770 is the default port rtmidirouterd is listening on. 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 Commands
can be found in Section _C_o_m_m_a_n_d_ _r_e_f_e_r_e_n_c_e. Or you can use the rtmidrouter
client (see below).

_33_.._22_ _ _ _rr_tt_mm_ii_dd_ii_rr_oo_uu_tt_ee_rr

rtmidirouter (without the "d") ist an example client for the rtmidirouterd
server (type rtmidirouter --help for online _h_e_l_p). It wraps the OSC stuff into
handy command line options. This also enables 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 1 MIDI input ports available.
    Input Port #0: USB MIDI Interface:0

  There are 3 MIDI output ports available.
    Output Port #0: USB MIDI Interface:0
    Output Port #1: LinuxSampler:0
    Output Port #2: ZynAddSubFX:0

As you can see there are one input port and 3 output ports available. Next we
will create a new layer called leadSynth. Then we connect the USB MIDI
Interface:0 as input source and the ZynAddSubFX:0 as output port to the layer:

  rtmidirouter --add-layer leadSynth
  rtmidirouter --layer leadSynth --connect-in-port "USB MIDI Interface:0"
  rtmidirouter --layer leadSynth --connect-out-port "ZynAddSubFX:0"

To check if everything went fine you can use the info command:

  rtmidirouter --layer leadSynth --info

The output in the first terminal (where the rtmidirouterd server is running)
should look like this:

  Layer leadSynth configuration:
  in port       USB MIDI Interface:0
  out port      ZynAddSubFX:0
  in channel    0
  out channel   0
  bypass        1
  range         0 - 127
  transpose     0

Lets create two more layers:

  rtmidirouter --add-layer trumpet
  rtmidirouter --layer trumpet --connect-in-port "USB MIDI Interface:0"
  rtmidirouter --layer trumpet --connect-out-port "LinuxSampler:0"
  rtmidirouter --layer trumpet --out-channel 1
  rtmidirouter --layer trumpet --lo-key 60 --hi-key 84

  rtmidirouter --add-layer trombone
  rtmidirouter --layer trombone --connect-in-port "USB MIDI Interface:0"
  rtmidirouter --layer trombone --connect-out-port "LinuxSampler:0"
  rtmidirouter --layer trombone --out-channel 2
  rtmidirouter --layer trombone --lo-key 60 --hi-key 84
  rtmidirouter --layer trombone --transpose=-12


_[_1_] The concept is mostly inspired by iptables, the frontend for the linux
    kernel firewall netfilter.



_44_ _ _ _OO_SS_CC_ _II_nn_tt_ee_rr_ff_aa_cc_ee

Open Sound Control (_O_S_C) is a network protocol for music software and devices.
The RtMidiRouter Server (rtmidirouterd) is configurable at runtime over an OSC
interface.
The client (rtmidirouter) provides a command line interface for sending OSC
Messages to the server. So there is no need to talk to the server via OSC
directly.

_44_.._11_ _ _ _SS_ee_nn_dd_ii_nn_gg_ _OO_SS_CC_ _mm_ee_ss_ss_aa_gg_ee_ss

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 _s_i_m_p_l_e_O_S_C.
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/connect", ["piano",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.

_44_.._22_ _ _ _CC_oo_mm_mm_aa_nn_dd_ _rr_ee_ff_ee_rr_ee_nn_cc_ee

The following OSC paths are available:
//qquuiitt

     Parameters: None
     Shutdown RTMidirouter.

//pprroobbee

     Parameters: None
     Display available MIDI input and output ports.

//iinnffoo

     Parameters: None
     Display information for all layers.

//ppaanniicc

     Parameters: None
     Send control change command "all notes off" to all layers.

//rreesseett

     Parameters: None
     Send control change command "reset all controllers" to all layers.

//aadddd__llaayyeerr

     Parameters: s - Layer name.
     Create a new layer.

//rreemmoovvee__llaayyeerr

     Parameters: s - Layer to remove.
     Remove layer.

//rreemmoovvee__aallll__llaayyeerrss

     Parameters: None
     Remove all layer.

//llaayyeerr//iinnffoo

     Parameters: s - Layer name
     Display information for selected Layer.

//llaayyeerr//ccoonnnneecctt__iinn__ppoorrtt

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

//llaayyeerr//ccoonnnneecctt__oouutt__ppoorrtt

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

//llaayyeerr//ccoonnnneecctt__iinn__ppoorrtt

     Parameters: s - Layer name
     Disconnect MIDI input port.

//llaayyeerr//ccoonnnneecctt__oouutt__ppoorrtt

     Parameters: s - Layer name
     Disconnect MIDI output port.

//llaayyeerr//iinn__cchhaannnneell

     Parameters: si - Layer name and channel number [0..15]
     Set MIDI channel i as input channel.

//llaayyeerr//oouutt__cchhaannnneell

     Parameters: si - Layer name and channel number [0..15]
     Set MIDI channel i as output channel.

//llaayyeerr//lloo__kkeeyy

     Parameters: si - Layer name and key number [0..127]
     Set low key to i. (Range from i to hi_key)

//llaayyeerr//hhii__kkeeyy

     Parameters: si - Layer name and key number [0..127]
     Set high key to i. (Range from lo_ley to i)

//llaayyeerr//ttrraannssppoossee

     Parameters: si - Layer name and transpose value [-127..127]
     Transpose all outgoing key by i
     Hint: to use a negative transpose value you mmuusstt use an equal sign,
     e.g.:

       rtmidirouter --layer layername --transpose=-12
       rtmidirouter -l layername -t=-12

     The following command will not work:

       rtmidirouter --layer layername --transpose -12
       rtmidirouter -l layername -t -12


//llaayyeerr//sseenndd__mmeessssaaggee

     Parameters: sii[i] - Layer name and midi message,
     Send 2 or 3 bytes.

//llaayyeerr//ppaanniicc

     Parameters: s[i] - Layer name and optional channel
     Send panic on selected or all channels.

//llaayyeerr//vvoolluummee

     Parameters: si - Layer name and volume [0..127]
     Set channel volume.



_55_ _ _ _HH_ii_ss_tt_oo_rr_yy

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.



_66_ _ _ _LL_ii_cc_ee_nn_ss_ee

Copyright (C) 2008-2011 - 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 (_F_D_L), Version 1.3 or any later
version published by the Free Software Foundation; with no Invariant Sections.
-------------------------------------------------------------------------------
_ _G_e_t_ _R_t_M_i_d_i_R_o_u_t_e_r_ _a_t_ _S_o_u_r_c_e_F_o_r_g_e_._n_e_t_._ _F_a_s_t_,_ _s_e_c_u_r_e_ _a_n_d_ _F_r_e_e_ _O_p_e_n_ _S_o_u_r_c_e
_s_o_f_t_w_a_r_e_ _d_o_w_n_l_o_a_d_s_ 
Generated on: 2011-03-20.