aplaymidi

aplaymidi [options] file ...

-h, --help
    Displays a help message and exits.

-V, --version
    Prints the version number and exits.

-l, --list
    Lists all available ALSA sequencer ports on the system.

-p client:port, --port=client:port
    Specifies the ALSA sequencer port(s) to send MIDI data to. Can be a client number, client name, or client:port combination. Multiple ports can be separated by commas.

-d name, --device=name
    Specifies a raw MIDI device name for direct output, bypassing the sequencer. Example: hw:1,0,0.

-i name, --input-port=name
    Connects to a MIDI input port. Useful for setting up a MIDI 'thru' box where input events are immediately played back.

-q, --queue
    Uses an ALSA sequencer queue for playback, which can provide more robust timing, especially for complex MIDI files.

-s pos, --start=pos
    Starts playback from a specific position in the MIDI file. Position can be specified in beats, seconds, or measures:beats.

-e pos, --end=pos
    Ends playback at a specific position in the MIDI file, similar to --start.

-t val, --tempo=val
    Adjusts the playback tempo. val is a ratio, where 1.0 is normal tempo. E.g., 0.5 for half speed, 2.0 for double speed.

-o file, --output-file=file
    Instead of playing, writes the MIDI events to the specified output MIDI file. Useful for MIDI file manipulation or conversion.

-v, --verbose
    Enables verbose output, displaying detailed information about the MIDI events as they are processed.

-c chan, --channel=chan
    Plays only the specified MIDI channel(s). Channels are 1-16. Can be a single channel or a comma-separated list.

-r, --raw
    Enables raw MIDI output mode, bypassing the ALSA sequencer. Requires a specific raw MIDI device to be specified with --device.

-L, --loop
    Enables continuous looping playback of the MIDI file(s).

-P, --progress
    Displays a simple progress bar during playback, indicating progress through the MIDI file.

-C, --continue
    Continues playback even if errors (e.g., unrecognized events) are encountered in the MIDI file.

-f, --fingerprinting
    Prints a fingerprint (MD5 sum) of the MIDI events, useful for identifying or comparing MIDI files structurally.

The aplaymidi command is a utility from the ALSA (Advanced Linux Sound Architecture) project, designed for playing standard MIDI files on Linux systems. It leverages the ALSA sequencer, which provides a powerful and flexible interface for managing MIDI events and connecting applications to MIDI devices or software synthesizers. Users can specify one or more MIDI files to play, and the command will send the MIDI events contained within these files to the selected ALSA sequencer port. This allows for playback through physical MIDI interfaces connected to external synthesizers, or to software synthesizers (like FluidSynth or TiMidity++) that expose ALSA sequencer ports. aplaymidi supports various options for controlling playback, including selecting output ports, adjusting tempo, looping, specifying start/end points, and providing verbose output for debugging.

For aplaymidi to function, the ALSA sequencer must be running and accessible. If no ALSA MIDI ports are listed with -l, ensure that MIDI devices are properly configured and necessary kernel modules (e.g., snd_seq_oss for legacy devices, or specific drivers for USB MIDI interfaces) are loaded. Playback to software synthesizers requires the synthesizer to be running and exposing an ALSA sequencer port.

Using realtime options (e.g., specific looping modes, buffer/fragment sizes for low-latency, not listed here) might require elevated user privileges or specific user/group configurations for optimal performance and avoiding XRuns (underruns/overruns).

ALSA's sequencer allows complex routing of MIDI data. You can connect aplaymidi's output to various destinations using the --port option, including physical MIDI interfaces (e.g., Midi Through:0), software synthesizers (e.g., TiMidity:0, FluidSynth:0), or other applications that listen on ALSA sequencer ports. Use aplaymidi -l to discover available ports and their client/port numbers or names.

aplaymidi primarily supports Standard MIDI Files (SMF), which typically have .mid or .midi extensions. It can handle both Type 0 (single track) and Type 1 (multi-track) MIDI files, processing their events sequentially and sending them to the chosen output port(s).

aplaymidi is an integral part of the ALSA (Advanced Linux Sound Architecture) utilities, which replaced the older OSS (Open Sound System) as the default sound system on Linux kernels since version 2.6. ALSA provides a robust and modular framework for audio and MIDI capabilities. aplaymidi specifically emerged as the standard command-line tool for playing MIDI files through ALSA's advanced sequencer infrastructure, allowing users to interact directly with ALSA's powerful MIDI routing and timing capabilities. Its development has mirrored the evolution of ALSA itself, aiming to provide low-latency and flexible MIDI playback on Linux.

aplay(1), arecord(1), aconnect(1), amidi(1), pmidi(1), alsamixer(1)