MIDICAT(1)

NAME
midicat - MIDI server and manipulation tool

SYNOPSIS
midicat [-dl] [-a flag] [-i file] [-L addr] [-o file] [-q port] [-s name] [-U unit]

DESCRIPTION
The midicat utility can merge any number of MIDI inputs and broadcast the result to any number of MIDI outputs, similarly to a hardware MIDI thru box. MIDI streams are typically MIDI ports or plain files containing raw MIDI data.

The midicat utility can also act as a MIDI server in which case MIDI streams correspond to client connections. The server capability allows any MIDI-capable application to send MIDI messages to MIDI hardware or to another application in a uniform way.

The options are as follows:

-a flag
    Control whether midicat opens MIDI ports connected to the thru box only when needed or keeps them open all the time. If the flag is on then MIDI ports are kept open all the time, ensuring no other program can steal any of them. If the flag is off, then they are automatically closed, allowing other programs to have direct access to MIDI ports, or the corresponding hardware to be disconnected. The default is on.

-d  Increase log verbosity. midicat logs on stderr until it daemonizes.

-i file
    Read data to send from this file. If the option argument is ‘-’ then standard input will be used.

-L addr
    Specify a local network address to listen on in server mode. midicat will listen on TCP port 11041+n, where n is the unit number specified with -U. Without this option, midicat listens on the UNIX-domain socket only, and is not reachable from any network. If the option argument is ‘-’ then midicat will accept connections from any address.

-l  Detach and become a daemon.

-o file
    Write received data into this file. If the option argument is ‘-’ then standard output will be used.

-q port
    Send and receive data from this sndio(7) MIDI port.

-s name
    Expose a MIDI thru box to which MIDI programs can connect. Preceding streams (-ioq) are subscribed to this thru box. The given name corresponds to the “option” part of the sndio(7) device name string.

-U unit
    Unit number to use when running in server mode. Each midicat server instance has a unique unit number, used in sndio(7) device names. The default is 0.

If files (-io) are specified but no ports (-q) are specified, the default sndio(7) port is used. If no streams (-ioq) are specified, server mode is assumed and a thru box is created as if -s default was used as the last argument.

Generally MIDI applications are real-time. To reduce jitter, especially on busy machines, the server can be started by the super-user, in which case it will run with higher priority. Any user will still be able to connect to it, but for privacy reasons only one user may have connections to it at a given time.

If midicat is sent SIGHUP, SIGINT or SIGTERM, then processing terminates.

EXAMPLES
The following dumps MIDI data received from the default port:

    $ midicat -o - | hexdump -e '1/1 "%x"'

The following sends raw MIDI data to the rmidi:5 port:

    $ midicat -i sysexfile -q rmidi:5

The following connects rmidi:5 and rmidi:6 ports:

    $ midicat -q rmidi:5 -q rmidi:6

The following creates a MIDI thru box and daemonizes, allowing MIDI programs to send data to each other instead of using hardware MIDI ports:

    $ midicat -l

The following creates a MIDI thru box and subscribes the rmidi:5 port, allowing multiple MIDI programs to use the port simultaneously:

    $ midicat -q rmidi:5 -s default

SEE ALSO
aucat(1), midi(4), sndio(7)

BUGS
The ability to merge multiple inputs is provided to allow multiple applications producing MIDI data to keep their connection open while idling; it does not replace a fully featured MIDI merger.