Annotation of src/usr.bin/aucat/midicat.1, Revision 1.11
1.11 ! jmc 1: .\" $OpenBSD: midicat.1,v 1.10 2010/04/22 17:43:30 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.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.9 ratchov 28: .Op Fl q Ar device
1.1 ratchov 29: .Op Fl U Ar unit
30: .Sh DESCRIPTION
31: The
32: .Nm
33: utility is used to manipulate MIDI data.
34: It can send and receive MIDI data from MIDI ports,
35: or it can create software MIDI thru boxes,
36: allowing any MIDI-capable application to
37: send MIDI messages to MIDI hardware
38: or to another application in a uniform way.
39: .Pp
40: The options are as follows:
41: .Bl -tag -width Ds
1.5 sobrado 42: .It Fl d
43: Do not daemonize.
44: If this option is specified,
45: .Nm
46: will run in the foreground and log to
47: .Em stderr .
1.1 ratchov 48: .It Fl i Ar file
1.2 ratchov 49: Send contents of this file to the device.
1.1 ratchov 50: If the option argument is
51: .Sq -
52: then standard input will be used.
53: .It Fl l
1.6 ratchov 54: Listen for incoming connections on
55: .Ux Ns -domain
56: sockets.
1.1 ratchov 57: This allows clients to use
58: .Nm
59: instead of the regular
60: .Xr midi 4
61: device as a software MIDI thru box.
62: .It Fl o Ar file
63: Store received data from the device into this file.
64: If the option argument is
65: .Sq -
66: then standard output will be used.
1.9 ratchov 67: .It Fl q Ar device
68: The
69: .Xr sndio 7
70: MIDI device to use for MIDI input/output.
71: In server mode, devices are subscribed to the MIDI thru box.
1.1 ratchov 72: .It Fl U Ar unit
73: Use the given unit number when creating a software MIDI thru box.
74: Only one
75: .Nm
76: process can expose a unit number at a given time.
77: The default is 0.
78: .El
79: .Pp
80: If
81: .Nm
82: is sent
83: .Dv SIGHUP ,
84: .Dv SIGINT
85: or
86: .Dv SIGTERM ,
87: then processing terminates.
88: .Sh SERVER MODE
89: .Nm
90: can be used in server mode
91: .Pq Fl l
92: to create MIDI thru boxes.
93: A MIDI thru box allows multiple receivers
94: to receive data from a single source.
95: Additionaly,
96: .Nm
97: software thru boxes allow multiple sources to be connected
98: to them; in this case MIDI byte-streams are merged,
99: preserving MIDI message integrity.
100: This feature is provided to allow multiple applications
101: acting as sources to keep their connection open while
102: idling; it does not replace a fully featured MIDI merger.
103: .Pp
1.10 ratchov 104: A
105: .Nm
106: process may be started by the super-user,
107: in which case any user will be able to connect to it.
1.11 ! jmc 108: For privacy reasons, only one user may have connections to
1.10 ratchov 109: it at a given time.
110: .Pp
111: Alternatively, each user may start its own
112: .Nm
113: process.
1.1 ratchov 114: It is generally not desirable to have multiple instances of
115: .Nm
116: running in server mode, so it is good practice to start it thus:
117: .Bd -literal -offset indent
118: $ pgrep -x midicat || midicat -l
119: .Ed
120: .Pp
121: Generally MIDI applications are real-time.
122: To reduce jitter, especially on busy machines, the
123: .Xr renice 8
124: command can be used to give a higher priority to the
125: .Nm
126: process.
127: Superuser privileges are required.
128: For example:
129: .Bd -literal -offset indent
130: $ midicat -l
131: $ sudo renice -n -20 -p `pgrep -x midicat`
132: .Ed
133: .Sh SEE ALSO
134: .Xr aucat 1 ,
135: .Xr midi 4 ,
136: .Xr sndio 7