Annotation of src/usr.bin/aucat/midicat.1, Revision 1.15
1.15 ! ratchov 1: .\" $OpenBSD: midicat.1,v 1.14 2011/03/21 16:33:17 okan 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.15 ! ratchov 17: .Dd $Mdocdate: March 21 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.1 ratchov 72: .It Fl l
1.12 ratchov 73: Detach and become a daemon.
1.1 ratchov 74: .It Fl o Ar file
1.12 ratchov 75: Write received data into this file.
1.1 ratchov 76: If the option argument is
77: .Sq -
78: then standard output will be used.
1.13 jmc 79: .It Fl q Ar port
1.12 ratchov 80: Send and receive data from this
81: .Xr sndio 7
82: MIDI port.
83: .It Fl s Ar name
84: Expose a MIDI thru box to which MIDI programs
85: can connect.
86: Preceding streams
87: .Pq Fl ioq
88: are subscribed to this thru box.
89: The given
90: .Ar name
91: corresponds to the
92: .Dq option
93: part of the
1.9 ratchov 94: .Xr sndio 7
1.12 ratchov 95: device name string.
1.1 ratchov 96: .It Fl U Ar unit
1.12 ratchov 97: Unit number to use when running in server mode.
98: Each
1.1 ratchov 99: .Nm
1.14 okan 100: server instance has a unique unit number,
1.12 ratchov 101: used in
102: .Xr sndio 7
103: device names.
1.1 ratchov 104: The default is 0.
105: .El
106: .Pp
1.12 ratchov 107: If files
108: .Pq Fl io
109: are specified but no ports
110: .Pq Fl q
111: are specified, the default
112: .Xr sndio 7
113: port is used.
114: If no streams
115: .Pq Fl ioq
116: are specified, server mode is assumed and a thru box is created
117: as if
118: .Fl s Ar default
1.13 jmc 119: was used as the last argument.
1.12 ratchov 120: .Pp
121: Generally MIDI applications are real-time.
122: To reduce jitter, especially on busy machines,
123: the server can be started by the super-user,
124: in which case it will run with higher priority.
1.13 jmc 125: Any user will still be able to connect to it,
126: but for privacy reasons only one user may have connections to
1.12 ratchov 127: it at a given time.
128: .Pp
1.1 ratchov 129: If
130: .Nm
131: is sent
132: .Dv SIGHUP ,
133: .Dv SIGINT
134: or
135: .Dv SIGTERM ,
136: then processing terminates.
1.12 ratchov 137: .Sh EXAMPLES
138: The following dumps MIDI data received from the default port:
139: .Bd -literal -offset indent
140: $ midicat -o - | hexdump -e '1/1 "%x"'
141: .Ed
1.1 ratchov 142: .Pp
1.12 ratchov 143: The following sends raw MIDI data to the
144: .Pa rmidi:5
145: port:
146: .Bd -literal -offset indent
147: $ midicat -i sysexfile -q rmidi:5
148: .Ed
1.10 ratchov 149: .Pp
1.12 ratchov 150: The following connects
151: .Pa rmidi:5
152: and
153: .Pa rmidi:6
154: ports:
1.1 ratchov 155: .Bd -literal -offset indent
1.12 ratchov 156: $ midicat -q rmidi:5 -q rmidi:6
1.1 ratchov 157: .Ed
158: .Pp
1.12 ratchov 159: The following creates a MIDI thru box and daemonizes,
160: allowing MIDI programs to send data to each other instead of
161: using hardware MIDI ports:
1.1 ratchov 162: .Bd -literal -offset indent
163: $ midicat -l
1.12 ratchov 164: .Ed
165: .Pp
166: The following creates a MIDI thru box and subscribes the
167: .Pa rmidi:5
168: port, allowing multiple MIDI programs to use the port
169: simultaneously:
170: .Bd -literal -offset indent
171: $ midicat -q rmidi:5 -s default
1.1 ratchov 172: .Ed
173: .Sh SEE ALSO
174: .Xr aucat 1 ,
175: .Xr midi 4 ,
176: .Xr sndio 7
1.12 ratchov 177: .Sh BUGS
178: The ability to merge multiple inputs is provided to allow multiple
179: applications producing MIDI data to keep their connection open while
180: idling; it does not replace a fully featured MIDI merger.