rtpmidi(1)

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

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.

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.

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.

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.

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.

The program opens the GTK interface.

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

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

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.

Suppress using the RTP-MIDI Journal. This option suppresses generation on the sending side, and suppresses recovery on the receiving side.

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.

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.

Listen to ALSA Midi System events, and log them if enabled.

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.

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

"D" - Version 2.0 enhances some timing calculations and inserts the correct delays between MIDI notes in the same packet. This option disables the insertion of the delays and reverts to previous behavior where all notes received in the same packet are emitted at the same time.

"E" - Version 2.0 adds "latency adjustment" feature. This flag disables latency adjustment and plays packets immediately. Note, this flag would also disable scheduling in "the future" from Senders that can do that.

"F" - addresses the translation of a "noteOn,vel=0" message. From Version 2.0.1 on the default behavior is to send such a message "as-is". This is more in keeping with the Apple implementation. The legacy "F" flag, when set, translates a "noteOn,vel=0" into a "noteOff,vel=0" prior to sending. (RFC 6295 section A.6.2 specifies that the way such a message is recorded in the Journal is as a "noteOff,vel=0". This is true no matter what the setting of the legacy F flag.)

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

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

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.

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.

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.

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

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.

2021-12-30 0.8