Name

amidicat — Hooks up standard input and standard output to the ALSA MIDI sequencer

Synopsis

amidicat [--help] [--version] [--list] [--name STRING] [--port CLIENT:PORT] [--addr CLIENT:PORT] [--hex] [--verbose] [--nowrite] [--noread] [--delay MILLISECONDS] [--wait SECONDS] [file...]

Arguments

All of the following arguments are optional:

--help

Displays a help screen, then exits. It is a quick summary of the documentation you are now reading.

--version

Displays version number, then exits. Currently version 1.2.

--list

Shows 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:

r

Device can be directly read from

w

Device can be directly written to

R

Device can be read from, either directly or via ALSA read subscription

W

Device can be written to, either directly or via ALSA write subscription

--name STRING

Sets 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:PORT

Makes 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.

--hex

Changes 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.

--verbose

Provides 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.

--nowrite

Disables 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.

--noread

Disables 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 MILLISECONDS

Inserts 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 SECONDS

After 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 - represents standard input. Filenames are processed left to right, so this can be used to insert other files before or after standard input. If no filenames are given on the command line, standard input is the default.

Description

aMIDIcat hooks up standard input and standard output to the ALSA MIDI sequencer. Like cat(1), this program will concatenate multiple input files together.

Examples

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.


See also

amidi(1), aconnect(1)