Using rtpmidi from the Command Line

Did you know you can use rptmidi directly from the command line in a terminal?  When used this way, the GUI (graphical user interface) is not used, and Bonjour is skipped as well.  Instead, each invocation of the rtpmidi program creates a new Session that can be a Session Listener or Session Initiator.  Working at this level you can connect if you know the hostname or IP-Address of each computer, as well as the port the RTP-MIDI session is listening on.

Command line mode can also come in handy if you are developing a “headless” embedded computer application like the Zynthian Raspberry Pi Synthesizer.
Read on for detailed examples and explanations.

Call another computer

Using the call command, your rtpmidi session becomes a Session Initiator.  For example:

$ rtpmidi call -u 5012

This command would create a new Session connecting to a host with IP-Address with a Session listening on port 4391.  On the local host, the Session would be serving on UDP port 5012.
You can combine this with the -p argument to also connect to a MIDI device with the client:port pair given.  For instance, if you had a MIDI keyboard known as MIDI client 24, you could create a new Session for it to connect to a remote computer directly from the command line.

$ rtpmidi call -u 5012 -p 24:0

When used in this way, rtpmidi 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 for an Incoming Connection

You can also launch a session of rtpmidi as a Session Listener.  Used in this manner, the program will listen for exactly ONE incoming request for a Session.   You must assign a UDP port for the session, and the remote computer must know this UDP port to call.  Since Bonjour is not involved, there is no automatic service discovery of the Session created this way.

$ rtpmidi listen -u 5012 -p 24:0

As before, you can use the -p option to directly connect the Session to a local MIDI device using its client number and port.
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.

Discovering the client number of your MIDI devices

On Linux, the aconnect command is used to create connections between the MIDI devices on your computer.  For instance, to create a connection from client with number 24 (and only one port) to another client numbered 33, you would type the following:

$ aconnect 24:0 33:0

The numbers used to refer to clients and ports is part of the low-level MIDI implementation on Linux.  You can also use the connect command to examine the state of the MIDI system and to see details about what is connected.
The -i option says: show me information about clients that accept input.
The -o option says: show me information about clients that produce output.
The -l option says:  list the devices.
The example below combines these options and shows the result on a system with a MIDI keyboard attached, and also a Virtual Keyboard program (vkeybd) running.  From here, you can determine the client and port numbers of the real and virtual MIDI devices in your system.

$ aconnect -i -o -l
client 0: 'System' [type=kernel]
    0 'Timer '
    1 'Announce '
client 14: 'Midi Through' [type=kernel]
    0 'Midi Through Port-0'
client 16: 'Launchkey 25' [type==kernel,card=0]
    0 'Launchkey 25 MIDI 1'
    1 'Launchkey 25 MIDI 2'
client 128: 'Virtual Keyboard' [type=user]
    0 'Virtual Keyboard'


Linux was designed with the command line as the fundamental way of interacting with the system.  McLaren Labs rtpmidi embraces this philosophy and provides command line access to individual Session creation.  This makes rtpmidi a tool that can be used in a number of different contexts.  Perhaps you can use it as a component in a script you are developing.  The command line interface makes scripting possible.

1 thought on “Using rtpmidi from the Command Line”

  1. Hey,
    bought the software (RTPmidi) yesterday. Works fine. I’m trying to use it in the command line but -probably by sheer ignorance on my part – can’t succeed. “rtpmidi call -u 5012” launches the gui but when I follow the instructions on this page it doesn’t seem to recognize any command.
    Could you help?
    Thanks in advance.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.