Annotation of src/usr.bin/aucat/midicat.1, Revision 1.13
1.13 ! jmc 1: .\" $OpenBSD: midicat.1,v 1.12 2010/07/06 01:12:45 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.13 ! jmc 17: .Dd $Mdocdate: July 6 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.13 ! jmc 65: .It Fl q Ar port
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
1.13 ! jmc 105: was used as the last argument.
1.12 ratchov 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.
1.13 ! jmc 111: Any user will still be able to connect to it,
! 112: but for privacy reasons only one user may have connections to
1.12 ratchov 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.