.\"	$OpenBSD: midicat.1,v 1.11 2010/04/22 18:27:19 jmc Exp $
.\"
.\" Copyright (c) 2006 Alexandre Ratchov <alex@caoua.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: April 22 2010 $
.Dt MIDICAT 1
.Os
.Sh NAME
.Nm midicat
.Nd MIDI server and manipulation tool
.Sh SYNOPSIS
.Nm midicat
.Op Fl dl
.Op Fl i Ar file
.Op Fl o Ar file
.Op Fl q Ar device
.Op Fl U Ar unit
.Sh DESCRIPTION
The
.Nm
utility is used to manipulate MIDI data.
It can send and receive MIDI data from MIDI ports,
or it can create software MIDI thru boxes,
allowing any MIDI-capable application to
send MIDI messages to MIDI hardware
or to another application in a uniform way.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl d
Do not daemonize.
If this option is specified,
.Nm
will run in the foreground and log to
.Em stderr .
.It Fl i Ar file
Send contents of this file to the device.
If the option argument is
.Sq -
then standard input will be used.
.It Fl l
Listen for incoming connections on
.Ux Ns -domain
sockets.
This allows clients to use
.Nm
instead of the regular
.Xr midi 4
device as a software MIDI thru box.
.It Fl o Ar file
Store received data from the device into this file.
If the option argument is
.Sq -
then standard output will be used.
.It Fl q Ar device
The
.Xr sndio 7
MIDI device to use for MIDI input/output.
In server mode, devices are subscribed to the MIDI thru box.
.It Fl U Ar unit
Use the given unit number when creating a software MIDI thru box.
Only one
.Nm
process can expose a unit number at a given time.
The default is 0.
.El
.Pp
If
.Nm
is sent
.Dv SIGHUP ,
.Dv SIGINT
or
.Dv SIGTERM ,
then processing terminates.
.Sh SERVER MODE
.Nm
can be used in server mode
.Pq Fl l
to create MIDI thru boxes.
A MIDI thru box allows multiple receivers
to receive data from a single source.
Additionaly,
.Nm
software thru boxes allow multiple sources to be connected
to them; in this case MIDI byte-streams are merged,
preserving MIDI message integrity.
This feature is provided to allow multiple applications
acting as sources to keep their connection open while
idling; it does not replace a fully featured MIDI merger.
.Pp
A
.Nm
process may be started by the super-user,
in which case any user will be able to connect to it.
For privacy reasons, only one user may have connections to
it at a given time.
.Pp
Alternatively, each user may start its own
.Nm
process.
It is generally not desirable to have multiple instances of
.Nm
running in server mode, so it is good practice to start it thus:
.Bd -literal -offset indent
$ pgrep -x midicat || midicat -l
.Ed
.Pp
Generally MIDI applications are real-time.
To reduce jitter, especially on busy machines, the
.Xr renice 8
command can be used to give a higher priority to the
.Nm
process.
Superuser privileges are required.
For example:
.Bd -literal -offset indent
$ midicat -l
$ sudo renice -n -20 -p `pgrep -x midicat`
.Ed
.Sh SEE ALSO
.Xr aucat 1 ,
.Xr midi 4 ,
.Xr sndio 7