convert the input song into another format, saving it as file. Use --list-formats to see the available output formats.

list all the events in the song, in text form.

list all the instruments used in the song, in text form.

list any metadata/tags in the file.

use a different instrument bank for subsequent conversions with --convert.

play the song.

change the channel assignment for a given track. Use --list-instruments to see the current channel assignment for a song.

Generally speaking, only one note can be played on each channel at a time. MIDI is the only exception to this, but MIDI can still only support one instrument on each channel at a time.

index is the zero-based track number to modify, and target is the new type and channel to assign. A target of m0 means to use MIDI channel 0. Channel types are:

This option can be specified multiple times and the change only applies to actions specified after it on the command line.

repeat the instrument bank until there are count instruments available. This is useful when replacing instruments, but there are not enough of them in the newly loaded bank.

Set the title to use for the next file written with --convert. The title is silently ignored for formats that do not support metadata.

Set the artist to use for the next file written with --convert. The artist is silently ignored for formats that do not support metadata, or have no place to store the artist name.

Set a comment to use for the next file written with --convert. The comment is silently ignored for formats that do not support metadata, or have no place to store a comment.

change the playback speed of the song. Events occur after a number of "ticks" on a clock, and the tempo controls how fast this clock runs. The faster this clock, the faster it ticks and so the faster events play, even though they remain the same number of ticks apart.

A tick is the finest grain of timing in a song. It is not possible to play events after half a tick, events can only be played after a whole number of ticks. For this reason there are usually many ticks for each musical beat, to allow for notes to be played before or after the beat, and to allow notes to be shorter in length than a whole beat.

convert the song to PCM and save it as a .wav file with the given name. This uses the same rendering process as --play.

show a list of supported file formats, along with the value to pass to --type, --convert and --newinst.

open the file as the given --type, even if it doesn't look like it's in that format.

force OPL2 mode (11 channels) when writing FM songs with --convert. This drops events that enable OPL3 mode.

force OPL3 mode (18 channels) when writing FM songs with --convert. This duplicates certain events so they apply to both register sets, and drops events that disable OPL3 mode. This may fail if the file format does not support OPL3 chips.

instrument bank to use for playing MIDI events with --play or rendering with --wav. Without this option, MIDI notes will be silent.

Any file supported (see --list-types) can be used as a MIDI bank. The file should have 128 instruments or some notes may be silent, if they are played with a MIDI patch that is not supplied.

Both OPL and PCM instruments are supported (separately or at the same time).

don't use pitchbends with --convert. This can make the output notes a bit cleaner if the song doesn't use any pitchbends.

print output suitable for parsing by a script.

manually specify the file type. The type is normally autodetected, but it needs to be specified for a few formats which lack signatures to identify them by. See --list-types.

list all the note on/off and other events in the Kiloblaster theme song.

convert the Duke Nukem II song hesbacka.imf into a CMF file saved as out.cmf. Because both IMF and CMF formats use Ad Lib/FM instruments, the instruments are converted as-is, with no replacement instrument bank required. Duke Nukem II however, plays its IMF songs at a different speed to the normal format, so the imf-idsoftware-duke2 file type must be manually specified to get the correct tempo.

convert the DOSBox Ad Lib capture capture.dro into a MIDI file called out.mid, using the instruments loaded from gm.mid.

Replacing the instruments is required here, because MIDI files cannot use Ad Lib instruments. The first instrument encountered in capture.dro is replaced with the first instrument used in gm.mid (which may not necessarily be MIDI instrument #1/piano.)

The OPL chip only has nine melodic channels per register set, numbered from 0 to 8 inclusive. However the channel is specified in a 4-bit field, allowing values from 0 to 15. There are no registers for channels 9 through 15, but it's still possible for a game to try to write to these registers. Doing so has no effect, and typically is a bug in the game's music player. Since the OPL chip ignores these events, the library also ignores them, but it displays this warning message to inform you that some data has been discarded.

Note that although the OPL3 has 18 channels, they are arranged in two separate sets of nine channels, so this error can still appear even for OPL3 songs. It does not mean that there is OPL3 data that is being discarded. Since the OPL3 has two register sets, it is possible to write to 32 different channels, even though only 18 of them are valid. The only valid channels for an OPL3 chip are 0 to 8 inclusive in register set A, and 0 to 8 inclusive in register set B (18 channels total). Channels 9 through 15 can be written to in both register sets, all of which are invalid and will generate this warning. This is why the error will always show a channel number between 9 and 15, whether in OPL2 or OPL3 mode.

Like the Invalid OPL channel error, this one indicates the song actually tried to play a note on one of the non-existent channels. If you see this error it might be worth investigating, as there could be a hidden part to the song that has never been heard. This error appears for every attempt to play a note on a channel that is not present, so the more messages are seen, the more notes are going unheard.