rtpmidi(1)

rtpmidi(1)
rtpmidi(1) RTP MIDI Utilities for ALSA rtpmidi(1)

NAME

rtpmidi - set up an RTP-MIDI session for ALSA
 

SYNOPSIS

rtpmidi (call host:port | listen | multicall host:port | multilisten) [-v sref] [-u udpport] [-I interface] [-J] [-S sloss] [-R rloss] [-A] [-M usememlock] [-l AB] [-f client:port] [-t client:port] [-p client:port] [-F favorite] [-B bonjname] [-C seqclientname] [-P seqportname]
 

MODE

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.
 
 
 

OPTIONS

-v sref
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
 
-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.
 
-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.
 
-l AB
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.
 
-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.
 

SYSLOG

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
 
 

EXAMPLES

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 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.
 
3. Multiple Sessions
 
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"
 
4. 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".
 

SEE ALSO

aconnect(1), aseqdump(1)
 

BUGS

None known.
 

LIMITATIONS

Each instance of rtpmidi creates a single session capable of connecting to a single computer. Each instance of rtpmidi requires exclusive access to a pair of UDP ports.
 

AUTHOR

rtpmidi is by McLaren Labs.
 
2020-03-01 0.5.3