camoto/manpage/gamemus

From shikadi.net
Jump to: navigation, search

gamemus

Name

gamemus — read, write and convert game music files

Synopsis

gamemus [options...] song [actions...]

Description

Perform the specified actions on the given song file. The actions are performed in order (i.e. the first action specified on the command line is performed first.)

Actions

--convert=format:file, -c format:file

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

--list, -l

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

--list-instruments, -i

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

--metadata, -m

list any metadata/tags in the file.

--newinst=format:file, -n format:file

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

--play, -p

play the song.

--remap-tracks=index=target, -k index=target

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:

m0..m15

MIDI channels 0 to 15. MIDI normally uses numbers 1..16 with percussion on 10, but since this number is zero-based, the channels are 0..15 with percussion on channel 9.

p0..p255

PCM channel. Maximum value depends on the file format. For some file formats (e.g. .mod) this can affect the panning.

o0..o8

OPL/FM melodic channels 0 through 8.

Note that OPL percussion mode uses channels 6, 7 and 8, so it is not valid for a song to have events on these channels while percussive events are present. This may happen temporarily during a format conversion, but this state must be resolved by the time the song is written out to a file.

r0..r4

OPL/FM percussive/rhythm. 0 = hi-hat, 1 = top cymbal, 2 = tom tom, 3 = snare drum, 4 = bass drum.

-

Unused channel. This will drop all events (including tempo events!) from this channel.

*0..*255

Any device. Only used internally. Songs cannot be written to a file if they contain an 'any' track type. Only one note at a time can be played on each 'any' track.

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

--repeat-instruments=count, -r count

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.

--tag-title=text

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

--tag-artist=text

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.

--tag-comment=text

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.

--tempo=us_per_tick:ticks_per_beat,frames_per_tick,time_signature

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.

us_per_tick

The number of microseconds per tick. A value of 250000 is the default and will result in four ticks every second, or 240 ticks per minute.

If there is one tick per beat then this will be 240 BPM (beats per minute) and notes will only be able to be played at each beat. If instead there are two ticks per beat then this will be 120 BPM, and notes will be able to be played both on the beat and also exactly in the middle between beats.

ticks_per_beat

The number of ticks in each musical beat. If this value is 1, then only one note can be played per beat, and it will always be at least one beat in length, making every note a semibreve (whole note) or longer. A value of 2 will allow up to two notes to be played per beat, meaning the shortest note will be a minim (half note). 4 will allow for crotchets (quarter notes) and so on.

This value is typically only used to assist with placing notes into a musical staff, so many formats do not make use of this value as it does not affect the song speed. MIDI is one format that uses it.

frames_per_tick

The number of audio frames in each tick. This is only relevant for some tracker formats that offer retrigger effects, where a sample is played from the beginning repeatedly within the space of one tick to the next. This value indicates how many repeats will happen. A value of 2 means the retriggered note will play twice - once at the tick and again half way between ticks. The default value used by most trackers is 6, with the value usually being ignored by other formats.

time_signature

Two numbers separated by a slash, such as 3/4. This is only used to assist with placing notes on a musical staff, so MIDI is currently the only format that makes use of it.

--wav=filename, -w filename

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

Options

--list-types

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

--force, -f

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

--force-opl2, -2

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

--force-opl3, -3

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.

--midibank=filename, -b filename

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

--no-pitchbends, -n

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

--script, -s

print output suitable for parsing by a script.

--type=format, -t format

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.

Examples

gamemus song_5.kb1 --list

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

gamemus --type imf-idsoftware-duke2 hesbacka.imf -c cmf-creativelabs:out.cmf

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.

gamemus capture.dro -n gm.mid -c mid-type0:out.mid

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

Errors

decode-opl: Invalid OPL channel 15

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.

decode-opl: Bad OPL note-on register/channel 0xF

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.

Notes

Exit status is 0 on success, non-zero on failure (1 for bad parameters, 2 for critical errors such as being unable to open the the archive file, 3 for more information needed, 4 for non-critical errors such as being unable to insert one of many files, 5 for uncommon failures like running out of disk space.)

All the file formats supported by this utility are fully documented on the Game Modding Wiki.

Bugs and Questions

Report bugs at https://github.com/Malvineous/libgamemusic/issues

Ask questions about Camoto or modding in general at the RGB Classic Games modding forum

Copyright

Copyright (c) 2010-2012 Adam Nielsen.

License GPLv3+: GNU GPL version 3 or later

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.