mirror of https://github.com/ericonr/sndio.git
167 lines
4.1 KiB
Groff
167 lines
4.1 KiB
Groff
.\" $OpenBSD: midicat.1,v 1.13 2010/07/06 10:45:01 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: July 6 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 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 d
|
|
Increase log verbosity.
|
|
.Nm
|
|
logs on 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
|
|
Detach and become a daemon.
|
|
.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 s Ar name
|
|
Expose a MIDI thru box to which MIDI programs
|
|
can connect.
|
|
Preceding streams
|
|
.Pq Fl ioq
|
|
are subscribed to this thru box.
|
|
The given
|
|
.Ar name
|
|
corresponds to the
|
|
.Dq option
|
|
part of the
|
|
.Xr sndio 7
|
|
device name string.
|
|
.It Fl U Ar unit
|
|
Unit number to use when running in server mode.
|
|
Each
|
|
.Nm
|
|
server instance has an unique unit number,
|
|
used in
|
|
.Xr sndio 7
|
|
device names.
|
|
The default is 0.
|
|
.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 -s default
|
|
.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.
|