Return to midicat.1 CVS log

Up to [local] / src / usr.bin / aucat

Annotation of src/usr.bin/aucat/midicat.1, Revision 1.2

1.2     ! ratchov     1: .\"    $OpenBSD: midicat.1,v 1.1 2009/07/25 08:44:27 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.2     ! ratchov    17: .Dd $Mdocdate: July 25 2009 $
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
                     25: .Op Fl l
                     26: .Op Fl f Ar device
                     27: .Op Fl i Ar file
                     28: .Op Fl o Ar file
                     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
                     42: .It Fl f Ar device
                     43: The
                     44: .Xr midi 4
                     45: device or
                     46: .Nm
                     47: socket to use for MIDI input/output.
1.2     ! ratchov    48: In server mode, devices are subscribed to the MIDI thru box.
1.1       ratchov    49: .It Fl i Ar file
1.2     ! ratchov    50: Send contents of this file to the device.
1.1       ratchov    51: If the option argument is
                     52: .Sq -
                     53: then standard input will be used.
                     54: .It Fl l
                     55: Listen for incoming connections on Unix domain sockets.
                     56: This allows clients to use
                     57: .Nm
                     58: instead of the regular
                     59: .Xr midi 4
                     60: device as a software MIDI thru box.
                     61: .It Fl o Ar file
                     62: Store received data from the device into this file.
                     63: If the option argument is
                     64: .Sq -
                     65: then standard output will be used.
                     66: .It Fl U Ar unit
                     67: Use the given unit number when creating a software MIDI thru box.
                     68: Only one
                     69: .Nm
                     70: process can expose a unit number at a given time.
                     71: The default is 0.
                     72: .El
                     73: .Pp
                     74: If
                     75: .Nm
                     76: is sent
                     77: .Dv SIGHUP ,
                     78: .Dv SIGINT
                     79: or
                     80: .Dv SIGTERM ,
                     81: then processing terminates.
                     82: If sent
                     83: .Dv SIGUSR1
                     84: or
                     85: .Dv SIGUSR2 ,
                     86: it increases or decreases debug level, respectively.
                     87: .Sh SERVER MODE
                     88: .Nm
                     89: can be used in server mode
                     90: .Pq Fl l
                     91: to create MIDI thru boxes.
                     92: A MIDI thru box allows multiple receivers
                     93: to receive data from a single source.
                     94: Additionaly,
                     95: .Nm
                     96: software thru boxes allow multiple sources to be connected
                     97: to them; in this case MIDI byte-streams are merged,
                     98: preserving MIDI message integrity.
                     99: This feature is provided to allow multiple applications
                    100: acting as sources to keep their connection open while
                    101: idling; it does not replace a fully featured MIDI merger.
                    102: .Pp
                    103: It is generally not desirable to have multiple instances of
                    104: .Nm
                    105: running in server mode, so it is good practice to start it thus:
                    106: .Bd -literal -offset indent
                    107: $ pgrep -x midicat || midicat -l
                    108: .Ed
                    109: .Pp
                    110: Generally MIDI applications are real-time.
                    111: To reduce jitter, especially on busy machines, the
                    112: .Xr renice 8
                    113: command can be used to give a higher priority to the
                    114: .Nm
                    115: process.
                    116: Superuser privileges are required.
                    117: For example:
                    118: .Bd -literal -offset indent
                    119: $ midicat -l
                    120: $ sudo renice -n -20 -p `pgrep -x midicat`
                    121: .Ed
                    122: .Sh ENVIRONMENT
                    123: .Bl -tag -width "MIDICAT_DEBUGXXX" -compact
                    124: .It Ev MIDICAT_DEBUG
                    125: The debug level:
                    126: may be a value between 0 and 4.
                    127: .El
                    128: .Sh SEE ALSO
                    129: .Xr aucat 1 ,
                    130: .Xr midi 4 ,
                    131: .Xr sndio 7