rtpmidi - set up an RTP-MIDI session for ALSA
rtpmidi (
call host:port |
listen |
multicall
host:port |
multilisten) [
-v srefa
]
[
-u udpport
] [
-I interface
]
[
-4] [
-J] [
-S sloss
]
[
-R rloss
] [
-A]
[
-M usememlock
] [
-l ABC
]
[
-f client:port
] [
-t client:port
]
[
-p client:port
] [
-F favorite
]
[
-B bonjname
] [
-C seqclientname
]
[
-P seqportname
]
The first word immediately following the
rtpmidi command, and before the
options, is the mode command. The program works in one of five distinct modes.
- call host:port
-
This mode creates exactly one MIDI session, and calls the named host on the
given port. The session is maintained until the remote host says BYE, or
until the local host says BYE (with a ^C). The program exits after the
session is closed.
- listen
-
This mode creates exactly one MIDI session at a time. The program listens
for an incoming INVITATION from a remote RTP-MIDI host and accepts it.
After the session ends, the program listens, awaiting another INVITATION.
At most, one session is active at a time.
- multicall host:port
-
This mode creates a session to call the named host on the given port. In
addition, it listens for INVITATION messages and creates a new session for
each participant in the RTP-MIDI network. The program will loop
indefinitely, creating new sessions. A ^C causes the program to send BYE
messages to all participants, and then the program will exit.
- multilisten
-
The program listens for INVITATION messages and creates a new session for
each participant in the RTP-MIDI network. The program will loop
indefinitely, creating new sessions for each INVITATION. A ^C causes the
program to send BYE messages to each participant, and then the program
will exit.
- gui
-
The program opens the GTK interface.
- -v srefa
- Print verbose messages. Each verbosity option character following the flag
selects specific information to log.
"s" - log sent RTP Midi packets
"r" - log received RTP Midi packets
"e" - log ALSA events
"f" - log Favorites handling
"a" - log received Addresses and Ports
- -u udpport
- By default, the RTP packets are sent to and from port 5004. Use this
option to select a different UDP port. (Note: when specifiying port 5004,
for example, the RTP custom of using ports 5004/5005 is observed.)
- -I interface
- By default, Avahi (Bonjour) advertises the MIDI service over all network
interfaces. Use this option if you have multiple network interfaces
(ethernet and/or WiFi) and you need to restrict Avahi client advertising
to just one interface. A value of "-1" indicates all interfaces,
and an integer value identifies a particular interface.
- -4
- Restrict to IPV4 only. Initiate and accept connections using IPV4. The
default is to use both IPV6 and IPV4. This option also instructs Avahi
(Bonjour) to ignore IPV6 addresses.
- -J
- Suppress using the RTP-MIDI Journal. This option suppresses generation on
the sending side, and suppresses recovery on the receiving side.
- -S sloss
- Simulate loss on the sending side by dropping "sloss" percent of
the sent packets. (The parameter "sloss" must be in the range
0..100.) Packets are fully formed and protected by the journal structure,
and then they are dropped.
- -R rloss
- Simulate loss on the receiving side by dropping "rloss" percent
of the received packets. (The parameter "sloss" must be in the
range 0..100.) Packets are received into the receive buffer, and then are
simply not evaluated further.
- -A
- Listen to ALSA Midi System events, and log them if enabled.
- -M usememlock
- To memlock pages use "-M 1", to disable use "-M 0".
Default is to use memlock on all pages.
Note: using this option may require using sudo, or raising the memlock limit
for the current user in /etc/security/limits.conf and restarting the
system.
- -l ABC
- Fall back to a "legacy" behavior. Each option character
following the flag selects a specific behavior.
"A" - suppress double noteOn sequences. The original
algorithm implemented by rtpmidi only emitted noteOn events if the previous
state of the note was OFF and the new note had velocity!=0. This algorithm
suppressed double noteOn in a heavy handed way. Some applications (like
lighting control) send double noteOn sequences. The newer behavior allows
this. Use this flag if you want the old behavior.
"B" - suppress sending SND_SEQ_EVENT_SENSING and
SND_SEQ_EVENT_CLOCK event types received from the ALSA Midi Sequencer. The
original codec filtered these events to reduce the event stream, later
versions enabled them. Select the filtering of these events with this
option.
"C" - Version 1.0 introduced automatic participant
termination (session timeout) if the peer does not answer when setting up a
session, or if the peer stops responding after a session has been active. This
option disables the automatic termination feature.
- -f client:port
- Connect FROM the specified ALSA Sequencer client and port. This option is
essentially the same as issuing the following command after rtpmidi has
launched.
- aconnect client:port rtpmidi:0
- -t client:port
- Connect TO the specified ALSA Sequencer client and port. This option is
essentially the same as issuing the following command after rtpmidi has
launched.
- aconnect rtpmidi:0 client:port
- -p client:port
- Connect TO and FROM the specified ALSA Sequencer client and port. Using
this option is essentially the same as issuing the commands
- aconnect client:port rtpmidi:0
- aconnect rtpmidi:0 client:port
- immediately after starting rtpmidi.
- -F favorite
- This option applies only to 'gui', 'multilisten' and 'multicall' mode. A
favorite is a remote device that is trusted for which a session
should be automatically launched when it is detected in the Bonjour list.
This option is especially useful with iDevices, which cannot initiate
sessions on their own. Using this option makes rtpmidi automatically
connect to the iDevice when if it shows up on the network. The
favorite name should be the Bonjour name of the remote device.
This option can be repeated to add multiple devices to the favorites
registry.
The favorite argument takes a limited form of wildcarding. If the
favorite name starts with a '*', then any device name whose suffix
matches the rest of the favorite past the '*' will be matched. If the
favorite name ends with a '*', then the prefix of the device needs
to match. A solitary '*' as a favorite name will match any device.
Caveats: use of this option can be tricky. iDevices often have names with
Unicode characters that look like simple ASCII characters. For instance,
an iDevice might have a left-single-quotation-mark which is easily
mistaken for an ASCII apostrophe. Read the logs to see the names of
devices under consideration.
- -B bonjname
- This option applies only to cmd-line mode. It sets both the advertised
Bonjour name of the session as well as the name of the session sent to the
remote host.
- -C seqclientname
- Sets the ALSA Sequencer Client name. By default, the ALSA Sequencer Client
name created by rtpmidi is simply 'rtpmidi'. When running multiple
instances of rtpmidi from the command line to launch multiple sessions, it
can become difficult to determine which ALSA sequencer client ID
corresponds to which instance. Use this to assign your own names.
With this option, you can use 'aconnect' to create connections to rtpmidi by
name instead of number.
- aconnect 26:0 seqclientname:0
- -P seqportname
- Sets the ALSA Sequencer Port name. By default, the ALSA Sequencer Port
name created by rtpmidi is simply 'rtpmidi'. It's probably best to
differentiate your instances by setting separate client names, but some
programs use the port name directly. Use this to assign your own name.
The rtpmidi program can send its logging output to syslog. (In Ubuntu18 this is
in file /var/log/syslog and it is automatically rotated.) This is a special
option type that follows all of the other options after a
"double-dash".
rtpmidi listen -- -GSLogSyslog YES
- 1. Session Listener
-
rtpmidi listen -p 20:0
will start an RTP-MIDI session waiting for connections from an external
computer. The ALSA Sequencer endpoint created by rtpmidi will be connected to
ALSA client "20" on port "0". For example, if client
"20" is a synthesizer, this will allow another computer to play the
synthesizer.
- 2. Session Listener from Multiple Hosts
-
rtpmidi multilisten -p 20:0
will start an RTP-MIDI session waiting for connections from any number of
external computers. The received MIDI data from all of the hosts will be
merged and sent to ALSA client "20" on port "0". MIDI data
received from ALSA client "20" on port "0" will be sent to
all remote hosts.
- 3. Session Initiator
-
rtpmidi call grannysmith:5004 -v sr
will call a computer named "grannysmith" on port 5004 attempting to
connect to an RTP-MIDI session there. The verbosity is set to log both sent
and received RTP-MIDI packets. The ALSA endpoint created for the session will
not be automatically connected to anything.
- 4. Session Initiator with Listener from Multiple Hosts
-
rtpmidi multicall grannysmith:5004 -p 20:0
will call a computer named "grannysmith" on port 5004 attempting to
connect to an RTP-MIDI session there. The session will also listen for
connections from any number of external computers. The received MIDI data from
all of the hosts will be merged and set to ALSA client "20" on port
"0".
- 5. Multiple Sessions in Parallel
-
rtpmidi listen -u 5004 -B my5004 -C rtp5004 &
rtpmidi listen -u 5006 -B my5006 -C rtp5006 &
Launch two separate sessions: one listening on UDP port 5004 and another on port
5006. The Bonjour name of the first will be "my5004" and its ALSA
sequencer client name will be "rtp5004". The names of the second
instance will be set similarly. The output of "aconnect -i -o -l"
will show two instances of rtpmidi with the client names "rtp5004"
and "rtp5006"
- 6. Automatically Connect to a Favorite
-
rtpmidi gui -F '*iPhone' -p 20:0
This option does not apply to 'listen' or 'call' mode.
Whenever a Bonjour name that ends in "iPhone" arrives on the network,
try to connect to it. Route the MIDI events to and from ALSA "20:0".
aconnect(1), aseqdump(1)
None known.
Each instance of
rtpmidi creates a session capable of transmitting and
receiving a 16-channel MIDI stream on a pair of UDP ports.
rtpmidi is by McLaren Labs.