Annotation of src/usr.bin/aucat/midicat.1, Revision 1.12
1.12 ! ratchov 1: .\" $OpenBSD: midicat.1,v 1.11 2010/04/22 18:27:19 jmc Exp $
1.1 ratchov 2: .\"
3: .\" Copyright (c) 2006 Alexandre Ratchov <alex@caoua.org>
4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16: .\"
1.11 jmc 17: .Dd $Mdocdate: April 22 2010 $
1.1 ratchov 18: .Dt MIDICAT 1
19: .Os
20: .Sh NAME
21: .Nm midicat
22: .Nd MIDI server and manipulation tool
23: .Sh SYNOPSIS
24: .Nm midicat
1.4 ratchov 25: .Op Fl dl
1.1 ratchov 26: .Op Fl i Ar file
27: .Op Fl o Ar file
1.12 ! ratchov 28: .Op Fl q Ar port
! 29: .Op Fl s Ar name
1.1 ratchov 30: .Op Fl U Ar unit
31: .Sh DESCRIPTION
32: The
33: .Nm
1.12 ! ratchov 34: utility can merge any number of MIDI inputs and broadcast the result
! 35: to any number of MIDI outputs, similarly to a hardware MIDI thru box.
! 36: MIDI streams are typically MIDI ports or plain files containing raw MIDI
! 37: data.
! 38: .Pp
! 39: The
! 40: .Nm
! 41: utility can also act as a MIDI server in which case MIDI streams
! 42: correspond to client connections.
! 43: The server capability
! 44: allows any MIDI-capable application to send MIDI messages to
! 45: MIDI hardware or to another application in a uniform way.
1.1 ratchov 46: .Pp
47: The options are as follows:
48: .Bl -tag -width Ds
1.5 sobrado 49: .It Fl d
1.12 ! ratchov 50: Increase log verbosity.
1.5 sobrado 51: .Nm
1.12 ! ratchov 52: logs on stderr until it daemonizes.
1.1 ratchov 53: .It Fl i Ar file
1.12 ! ratchov 54: Read data to send from this file.
1.1 ratchov 55: If the option argument is
56: .Sq -
57: then standard input will be used.
58: .It Fl l
1.12 ! ratchov 59: Detach and become a daemon.
1.1 ratchov 60: .It Fl o Ar file
1.12 ! ratchov 61: Write received data into this file.
1.1 ratchov 62: If the option argument is
63: .Sq -
64: then standard output will be used.
1.9 ratchov 65: .It Fl q Ar device
1.12 ! ratchov 66: Send and receive data from this
! 67: .Xr sndio 7
! 68: MIDI port.
! 69: .It Fl s Ar name
! 70: Expose a MIDI thru box to which MIDI programs
! 71: can connect.
! 72: Preceding streams
! 73: .Pq Fl ioq
! 74: are subscribed to this thru box.
! 75: The given
! 76: .Ar name
! 77: corresponds to the
! 78: .Dq option
! 79: part of the
1.9 ratchov 80: .Xr sndio 7
1.12 ! ratchov 81: device name string.
1.1 ratchov 82: .It Fl U Ar unit
1.12 ! ratchov 83: Unit number to use when running in server mode.
! 84: Each
1.1 ratchov 85: .Nm
1.12 ! ratchov 86: server instance has an unique unit number,
! 87: used in
! 88: .Xr sndio 7
! 89: device names.
1.1 ratchov 90: The default is 0.
91: .El
92: .Pp
1.12 ! ratchov 93: If files
! 94: .Pq Fl io
! 95: are specified but no ports
! 96: .Pq Fl q
! 97: are specified, the default
! 98: .Xr sndio 7
! 99: port is used.
! 100: If no streams
! 101: .Pq Fl ioq
! 102: are specified, server mode is assumed and a thru box is created
! 103: as if
! 104: .Fl s Ar default
! 105: was used as last argument.
! 106: .Pp
! 107: Generally MIDI applications are real-time.
! 108: To reduce jitter, especially on busy machines,
! 109: the server can be started by the super-user,
! 110: in which case it will run with higher priority.
! 111: Any user will still be able to connect to it, but
! 112: for privacy reasons, only one user may have connections to
! 113: it at a given time.
! 114: .Pp
1.1 ratchov 115: If
116: .Nm
117: is sent
118: .Dv SIGHUP ,
119: .Dv SIGINT
120: or
121: .Dv SIGTERM ,
122: then processing terminates.
1.12 ! ratchov 123: .Sh EXAMPLES
! 124: The following dumps MIDI data received from the default port:
! 125: .Bd -literal -offset indent
! 126: $ midicat -o - | hexdump -e '1/1 "%x"'
! 127: .Ed
1.1 ratchov 128: .Pp
1.12 ! ratchov 129: The following sends raw MIDI data to the
! 130: .Pa rmidi:5
! 131: port:
! 132: .Bd -literal -offset indent
! 133: $ midicat -i sysexfile -q rmidi:5
! 134: .Ed
1.10 ratchov 135: .Pp
1.12 ! ratchov 136: The following connects
! 137: .Pa rmidi:5
! 138: and
! 139: .Pa rmidi:6
! 140: ports:
1.1 ratchov 141: .Bd -literal -offset indent
1.12 ! ratchov 142: $ midicat -q rmidi:5 -q rmidi:6
1.1 ratchov 143: .Ed
144: .Pp
1.12 ! ratchov 145: The following creates a MIDI thru box and daemonizes,
! 146: allowing MIDI programs to send data to each other instead of
! 147: using hardware MIDI ports:
1.1 ratchov 148: .Bd -literal -offset indent
149: $ midicat -l
1.12 ! ratchov 150: .Ed
! 151: .Pp
! 152: The following creates a MIDI thru box and subscribes the
! 153: .Pa rmidi:5
! 154: port, allowing multiple MIDI programs to use the port
! 155: simultaneously:
! 156: .Bd -literal -offset indent
! 157: $ midicat -q rmidi:5 -s default
1.1 ratchov 158: .Ed
159: .Sh SEE ALSO
160: .Xr aucat 1 ,
161: .Xr midi 4 ,
162: .Xr sndio 7
1.12 ! ratchov 163: .Sh BUGS
! 164: The ability to merge multiple inputs is provided to allow multiple
! 165: applications producing MIDI data to keep their connection open while
! 166: idling; it does not replace a fully featured MIDI merger.