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