Annotation of src/usr.bin/aucat/midicat.1, Revision 1.16
1.16 ! ratchov 1: .\" $OpenBSD: midicat.1,v 1.15 2011/04/28 06:19:57 ratchov 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.16 ! ratchov 17: .Dd $Mdocdate: April 28 2011 $
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
1.15 ratchov 27: .Op Fl L Ar addr
1.1 ratchov 28: .Op Fl o Ar file
1.12 ratchov 29: .Op Fl q Ar port
30: .Op Fl s Ar name
1.1 ratchov 31: .Op Fl U Ar unit
32: .Sh DESCRIPTION
33: The
34: .Nm
1.12 ratchov 35: utility can merge any number of MIDI inputs and broadcast the result
36: to any number of MIDI outputs, similarly to a hardware MIDI thru box.
37: MIDI streams are typically MIDI ports or plain files containing raw MIDI
38: data.
39: .Pp
40: The
41: .Nm
42: utility can also act as a MIDI server in which case MIDI streams
43: correspond to client connections.
44: The server capability
45: allows any MIDI-capable application to send MIDI messages to
46: MIDI hardware or to another application in a uniform way.
1.1 ratchov 47: .Pp
48: The options are as follows:
49: .Bl -tag -width Ds
1.5 sobrado 50: .It Fl d
1.12 ratchov 51: Increase log verbosity.
1.5 sobrado 52: .Nm
1.14 okan 53: logs on
54: .Em stderr
55: until it daemonizes.
1.1 ratchov 56: .It Fl i Ar file
1.12 ratchov 57: Read data to send from this file.
1.1 ratchov 58: If the option argument is
59: .Sq -
60: then standard input will be used.
1.15 ratchov 61: .It Fl L Ar addr
62: Specify a local network address to listen on in server mode.
63: .Nm
64: will listen on TCP port 11041+n, where n is the unit number
65: specified with
66: .Fl U .
67: Without this option,
68: .Nm
69: listens on the
70: .Ux Ns -domain
71: socket only, and is not reachable from any network.
1.16 ! ratchov 72: If the option argument is
! 73: .Sq -
! 74: then
! 75: .Nm
! 76: will accept connections from any address.
1.1 ratchov 77: .It Fl l
1.12 ratchov 78: Detach and become a daemon.
1.1 ratchov 79: .It Fl o Ar file
1.12 ratchov 80: Write received data into this file.
1.1 ratchov 81: If the option argument is
82: .Sq -
83: then standard output will be used.
1.13 jmc 84: .It Fl q Ar port
1.12 ratchov 85: Send and receive data from this
86: .Xr sndio 7
87: MIDI port.
88: .It Fl s Ar name
89: Expose a MIDI thru box to which MIDI programs
90: can connect.
91: Preceding streams
92: .Pq Fl ioq
93: are subscribed to this thru box.
94: The given
95: .Ar name
96: corresponds to the
97: .Dq option
98: part of the
1.9 ratchov 99: .Xr sndio 7
1.12 ratchov 100: device name string.
1.1 ratchov 101: .It Fl U Ar unit
1.12 ratchov 102: Unit number to use when running in server mode.
103: Each
1.1 ratchov 104: .Nm
1.14 okan 105: server instance has a unique unit number,
1.12 ratchov 106: used in
107: .Xr sndio 7
108: device names.
1.1 ratchov 109: The default is 0.
110: .El
111: .Pp
1.12 ratchov 112: If files
113: .Pq Fl io
114: are specified but no ports
115: .Pq Fl q
116: are specified, the default
117: .Xr sndio 7
118: port is used.
119: If no streams
120: .Pq Fl ioq
121: are specified, server mode is assumed and a thru box is created
122: as if
123: .Fl s Ar default
1.13 jmc 124: was used as the last argument.
1.12 ratchov 125: .Pp
126: Generally MIDI applications are real-time.
127: To reduce jitter, especially on busy machines,
128: the server can be started by the super-user,
129: in which case it will run with higher priority.
1.13 jmc 130: Any user will still be able to connect to it,
131: but for privacy reasons only one user may have connections to
1.12 ratchov 132: it at a given time.
133: .Pp
1.1 ratchov 134: If
135: .Nm
136: is sent
137: .Dv SIGHUP ,
138: .Dv SIGINT
139: or
140: .Dv SIGTERM ,
141: then processing terminates.
1.12 ratchov 142: .Sh EXAMPLES
143: The following dumps MIDI data received from the default port:
144: .Bd -literal -offset indent
145: $ midicat -o - | hexdump -e '1/1 "%x"'
146: .Ed
1.1 ratchov 147: .Pp
1.12 ratchov 148: The following sends raw MIDI data to the
149: .Pa rmidi:5
150: port:
151: .Bd -literal -offset indent
152: $ midicat -i sysexfile -q rmidi:5
153: .Ed
1.10 ratchov 154: .Pp
1.12 ratchov 155: The following connects
156: .Pa rmidi:5
157: and
158: .Pa rmidi:6
159: ports:
1.1 ratchov 160: .Bd -literal -offset indent
1.12 ratchov 161: $ midicat -q rmidi:5 -q rmidi:6
1.1 ratchov 162: .Ed
163: .Pp
1.12 ratchov 164: The following creates a MIDI thru box and daemonizes,
165: allowing MIDI programs to send data to each other instead of
166: using hardware MIDI ports:
1.1 ratchov 167: .Bd -literal -offset indent
168: $ midicat -l
1.12 ratchov 169: .Ed
170: .Pp
171: The following creates a MIDI thru box and subscribes the
172: .Pa rmidi:5
173: port, allowing multiple MIDI programs to use the port
174: simultaneously:
175: .Bd -literal -offset indent
176: $ midicat -q rmidi:5 -s default
1.1 ratchov 177: .Ed
178: .Sh SEE ALSO
179: .Xr aucat 1 ,
180: .Xr midi 4 ,
181: .Xr sndio 7
1.12 ratchov 182: .Sh BUGS
183: The ability to merge multiple inputs is provided to allow multiple
184: applications producing MIDI data to keep their connection open while
185: idling; it does not replace a fully featured MIDI merger.