Return to midicat.1 CVS log

Up to [local] / src / usr.bin / aucat

Simplify and improve the way options are parsed and remove ~300 lines
of code that becomes unused. Few command line arguments changes are
required though:

  - stream definitions (-ios) now must follow devices definitions they
    are attached to (-fMn)

  - the -n option is now a special "loopback" device and is thus used
    like -f, eg it must precede streams

  - in midicat, midi thru boxes are not created automatically anymore,
    the new "-M" option must be used for that

  - channel numbers (-Cc options) correspond always to channel numbers
    of the hardware.

  - the -u option isn't needed anymore

  - increase the log verbosity so user errors are logged
    without using -d

tested by many, help from jmc

.\"	$OpenBSD: midicat.1,v 1.18 2011/10/12 07:20:04 ratchov 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: October 12 2011 $
.Dt MIDICAT 1
.Os
.Sh NAME
.Nm midicat
.Nd MIDI server and manipulation tool
.Sh SYNOPSIS
.Nm midicat
.Op Fl dlM
.Op Fl a Ar flag
.Op Fl i Ar file
.Op Fl L Ar addr
.Op Fl o Ar file
.Op Fl q Ar port
.Op Fl s Ar name
.Op Fl U Ar unit
.Sh DESCRIPTION
The
.Nm
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.
.Pp
The
.Nm
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.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl a Ar flag
Control whether
.Nm
opens MIDI ports connected to the thru box only when needed
or keeps them open all the time.
If the flag is
.Va on
then MIDI ports are kept open all the time, ensuring no other program can
steal any of them.
If the flag is
.Va 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
.Va on .
.It Fl d
Increase log verbosity.
.Nm
logs on
.Em stderr
until it daemonizes.
.It Fl i Ar file
Read data to send from this file.
If the option argument is
.Sq -
then standard input will be used.
.It Fl L Ar addr
Specify a local network address to listen on in server mode.
.Nm
will listen on TCP port 11041+n, where n is the unit number
specified with
.Fl U .
Without this option,
.Nm
listens on the
.Ux Ns -domain
socket only, and is not reachable from any network.
If the option argument is
.Sq -
then
.Nm
will accept connections from any address.
.It Fl M
Create a MIDI thru box.
It merges any number of MIDI inputs and broadcasts the result
to any number of MIDI outputs, similarly to a hardware MIDI thru box.
Following MIDI ports
.Pq Fl q
and MIDI files
.Pq Fl io
will be subscribed to this thru box.
If sub-devices are exposed
.Pq Fl s
they behave like software MIDI ports,
allowing any MIDI-capable application to send MIDI messages to
MIDI hardware or to another application in a uniform way.
.It Fl l
Detach and become a daemon.
.It Fl s Ar name
Expose a MIDI thru box to which MIDI programs
can connect.
The given
.Ar name
corresponds to the
.Dq option
part of the
.Xr sndio 7
device name string.
.It Fl o Ar file
Write received data into this file.
If the option argument is
.Sq -
then standard output will be used.
.It Fl q Ar port
Send and receive data from this
.Xr sndio 7
MIDI port.
.It Fl U Ar unit
Unit number to use when running in server mode.
Each
.Nm
server instance has a unique unit number,
used in
.Xr sndio 7
device names.
The default is 0.
The unit number must be set before any server-specific
options are used
.Pq Fl Ls .
.El
.Pp
If files
.Pq Fl io
are specified but no ports
.Pq Fl q
are specified, the default
.Xr sndio 7
port is used.
If no streams
.Pq Fl ioq
are specified, server mode is assumed and a thru box is created
as if
.Fl s Ar default
was used as the last argument.
.Pp
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.
.Pp
If
.Nm
is sent
.Dv SIGHUP ,
.Dv SIGINT
or
.Dv SIGTERM ,
then processing terminates.
.Sh EXAMPLES
The following dumps MIDI data received from the default port:
.Bd -literal -offset indent
$ midicat -o - | hexdump -e '1/1 "%x"'
.Ed
.Pp
The following sends raw MIDI data to the
.Pa rmidi:5
port:
.Bd -literal -offset indent
$ midicat -i sysexfile -q rmidi:5
.Ed
.Pp
The following connects
.Pa rmidi:5
and
.Pa rmidi:6
ports:
.Bd -literal -offset indent
$ midicat -q rmidi:5 -q rmidi:6
.Ed
.Pp
The following creates a MIDI thru box and daemonizes,
allowing MIDI programs to send data to each other instead of
using hardware MIDI ports:
.Bd -literal -offset indent
$ midicat -l
.Ed
.Pp
The following creates a MIDI thru box and subscribes the
.Pa rmidi:5
port, allowing multiple MIDI programs to use the port
simultaneously:
.Bd -literal -offset indent
$ midicat -q rmidi:5
.Ed
.Sh SEE ALSO
.Xr aucat 1 ,
.Xr midi 4 ,
.Xr sndio 7
.Sh 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.