amidicat — Hooks up standard input and standard output to the ALSA MIDI sequencer
amidicat [--help] [--version] [--list] [--name STRING] [--port CLIENT:PORT] [--addr CLIENT:PORT] [--hex] [--verbose] [--nowrite] [--noread] [--delay MILLISECONDS] [--wait SECONDS] [file...]
All of the following arguments are optional:
--helpDisplays a help screen, then exits. It is a quick summary of the documentation you are now reading.
--versionDisplays version number, then exits. Currently version 1.2.
--listShows a listing of all ALSA MIDI sequencer devices currently available for use, then exits.
Devices are displayed one per line, containing ALSA port number (CLIENT:PORT syntax), client name, port name, and flags. The flags are:
rDevice can be directly read from
wDevice can be directly written to
RDevice can be read from, either directly or via ALSA read subscription
WDevice can be written to, either directly or via ALSA write subscription
--name STRINGSets the client name of this program's ALSA connection. This might be helpful to identify the aMIDIcat port number, when using other applications.
The effects of setting this option can be observed
in the --list output. The default client name is “aMIDIcat”.
--port CLIENT:PORT, --addr CLIENT:PORTMakes a direct connection to the given ALSA port number, for reading and writing. If this option is not given, the default is to only set up a passive connection for use with the ALSA subscription mechanism.
The parameter is either a numeric CLIENT:PORT
(example: 128:0), or the client name or port name of
another program's ALSA connection (use the --list option to
see what is available). If the name contains spaces, remember to put it in quotes.
The --port and --addr options
are identical. For syntax compatibility
with other ALSA programs, you have the choice of using either, but only
one of these options may be given.
--hexChanges the syntax of input and output, to be human-readable hex digits, optionally separated by whitespace. This option applies to all input files. If this option is not given, the default is raw binary data.
Hex digits must be in the range 0 through 9,
A through F, or a
through f. Bytes are optionally separated by whitespace. If
whitespace is not given, every two hex digits represent a byte. An error happens
if input is not a hex digit or whitespace.
With this option, the MIDI output data will be grouped. Each MIDI event will be separated by a newline character, but each individual byte within the event will only be separated by a space. This makes it easy to observe the individual MIDI events.
--verboseProvides additional output, on standard error. This option is highly recommended.
Among other useful things, it displays this program's ALSA port number, once the connection to ALSA is made. So, if you start another ALSA program afterwards, with the intention of connecting to this program, you will know what port number to use.
--nowriteDisables writing data into ALSA from standard input. When this option is used, no input files may be given on the command line.
The intent of this option is to allow
a read-only connection to devices that do not give write permission. These devices
can be identified in the --list output, as they do not have
the w or W flags.
--noreadDisables reading data out of ALSA to standard output.
This option can not be combined with the --nowrite option.
The intent of this option is to allow
a write-only connection to devices that do not give read permission. These devices
can be identified in the --list output, as they do not have
the r or R flags.
--delay MILLISECONDSInserts a delay, in milliseconds, between each MIDI event written to ALSA from input.
This is useful for avoiding event loss due to ALSA queue congestion. Although this program tries to avoid overflowing ALSA's internal buffer, events will still be lost if they arrive too quickly. Unlike other MIDI programs, this program does not take any tempo or other timing information at all into account, and will write data into ALSA as quickly as it is read from input. So, when using this program, event overflow is highly likely, unless this option is used.
This option will slow down the processing of input. A value of 10 milliseconds
is usually sufficient to avoid event loss. When
using the --verbose option, total counts of events processed will be
output when this program exits, so
these counters can be used to verify that no events were lost.
--wait SECONDSAfter all input has finished being processed, continue running this program
for the given number of seconds, then exit. This option can not be combined
with the --nowrite option.
Unless this option is given, this program will exit immediately after completing all input. This includes processing all input files, and reaching EOF on standard input, if standard input is being used.
This option is useful for allowing some additional time for MIDI data to be received from ALSA. For example, this might be useful for sending MIDI commands to a synthesizer, and then waiting for any responses to come back.
Everything else on the command line is interpreted as the filename of an
input file. The special filename -
aMIDIcat hooks up standard input and standard output to the ALSA MIDI sequencer. Like cat(1), this program will concatenate multiple input files together.
All of these examples use the TiMidity software synthesizer. Change the --port "TiMidity" parameter to use anything else you have. If you are using a real hardware synthesizer, use caution when trying the examples that generate random data or play arbitrary files, as they could send unwanted SysEx commands.
Example 1. List all ALSA sequencer devices
amidicat -l
This will list all MIDI devices on your system that are visible to the ALSA sequencer. Here is sample output:
Port Client name Port name RW 0:0 System Timer Rw 0:1 System Announce R 14:0 Midi Through Midi Through Port-0 RW 15:0 OSS sequencer Receiver w 128:0 TiMidity TiMidity port 0 W 128:1 TiMidity TiMidity port 1 W 128:2 TiMidity TiMidity port 2 W 128:3 TiMidity TiMidity port 3 W 129:0 aMIDIcat aMIDIcat RW
Example 2. Play MIDI files very quickly
amidicat --port "TiMidity" --delay 10 *.mid
This will play all MIDI files in the current directory very quickly,
without regard for tempo. The .mid file format will not be
recognized, so headers and other information will play as garbage. This would
be more useful for files containing nothing but raw MIDI data, perhaps
SysEx commands that you wish to load into a hardware synth.
Example 3. A better "beep" command
echo "903C7F" | amidicat --port "TiMidity" --hex
This plays Middle C. It's easy to elaborate on this. If you have an application that makes many beeps, replacing the beeps with MIDI can make it more pleasant-sounding.
Example 4. Transport MIDI data over the network
nc -v -l -p 12345 | amidicat --port "TiMidity"
This command sets up a server listening on port 12345. Now, from somewhere else on the Internet, use nc to connect to port 12345 of this machine running amidicat, and start sending it MIDI data. It should play.
Example 5. Stress-test your softsynth by playing random data
cat /dev/urandom | amidicat --port "TiMidity" --delay 1
Turn down your speakers before trying this. The delay parameter
is necessary to avoid
flooding ALSA with a deluge of random data. Do not use this with a
real hardware synthesizer,
or you could damage your settings if, by bad luck, a random SysEx
command is formed!
Hit Control-C to stop the program, and you might get to hear a rather
interesting sound effect that was caused by playing random data.
Example 6. Panic button
perl -e 'use bytes;for($i=0;$i<16;$i++){print chr(176+$i).chr(120).chr(0);}' | amidicat --port "TiMidity"
This Perl one-liner sends MIDI "All Sound Off" commands to every channel. It should silence all audio currently being played. You will want to use this command after playing the stress-test above :)
Example 7. Another panic button
perl -e 'use bytes;for($i=0;$i<16;$i++){for($j=0;$j<128;$j++){print chr(128+$i).chr($j).chr(127);}}' | amidicat --port "TiMidity"
Another Perl one-liner, which sends all individual "Note Off" commands. It is slower than the above, but perhaps useful for an older synth that doesn't understand the "All Sound Off" command.