CMF Format

From ModdingWiki
Jump to: navigation, search
CMF Format
Format typeMusic
Notation typeMIDI
InstrumentsOPL
Max channel count16
Max track count1
Max pattern count1
Max order count0
Tags?Title, Artist, Remarks
GamesJill of the Jungle, Kiloblaster, Scud Atak, Solar Winds, Traffic Department 2192, Math Rescue, Word Rescue, Xargon

The Creative Music Format (CMF) was created by Creative Labs for use with their SoundBlaster series of sound cards. It is a cut-down version of the MIDI format (only one track) but unlike MIDI it allows custom instruments to be stored in the file itself (and unlike the Module formats that preceeded it, the instruments were not sampled but were synthesised using the Adlib/SoundBlaster OPL chips.)

Contents

File format

The file begins with a header:

Data type Name Description
BYTE[4] cSignature "CTMF" (not NULL-terminated)
UINT8 iVersionMinor Minor version number (normally 0x01)
UINT8 iVersionMajor Major version number (normally 0x01)
UINT16LE iOffsetInstruments Offset of the instrument block, from the start of the file
UINT16LE iOffsetMusic Offset of the music block, from the start of the file
UINT16LE iTicksPerQuarter Clock ticks per quarter note (one beat)
UINT16LE iTicksPerSecond Clock ticks per second
UINT16LE iOffsetTitle Offset of the song title string, zero if no title
UINT16LE iOffsetComposer Offset of the composer's name, zero if not listed
UINT16LE iOffsetRemarks Offset of the "remarks" string, zero if no remarks
UINT8[16] iChannelInUse Channel in use table (0x00 == channel not used, 0x01 == channel used in song)

The rest of the header depends on the version:

Version 1.0

Data type Name Description
UINT8 iInstrumentCount Number of instruments used

Version 1.1

Data type Name Description
UINT16LE iInstrumentCount Number of instruments used
UINT16LE iTempo Basic tempo (?)

The song title, composer and remarks (if present) should follow this header and the instrument block should follow that (although there is no requirement for them to be located here, as long as the offsets in the header point to the correct location.) These three strings are NULL-terminated ASCII.

It is worth noting that the header stores both a tempo value and a "ticks per quarter note" value, however the only field that seems to be used for timing during playback is the "ticks per second" field. The tempo field doesn't even exist in version 1.0 files.

It is also worth noting that between v1.0 and v1.1, the number of possible instruments expanded from a maximum of 256 (UINT8) to 65536 (UINT16.) However the MIDI data itself is only capable of addressing up to 128 instruments, so any extras cannot be used. Perhaps there was originally an intention to make these available through instrument banks like MIDI does.

Instrument block

The instrument block contains all the instruments used in the song. The first instrument is referred to in the song data as instrument zero (MIDI patch #0.) The following table lists the fields used to define one instrument - it is repeated iInstrumentCount times.

Data type Name OPL base register Description
UINT8 iModChar 0x20 Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
UINT8 iCarChar 0x23 Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
UINT8 iModScale 0x40 Modulator key scaling/output level
UINT8 iCarScale 0x43 Carrier key scaling/output level
UINT8 iModAttack 0x60 Modulator attack/decay level
UINT8 iCarAttack 0x63 Carrier attack/decay level
UINT8 iModSustain 0x80 Modulator sustain/release level
UINT8 iCarSustain 0x83 Carrier sustain/release level
UINT8 iModWaveSel 0xE0 Modulator wave select
UINT8 iCarWaveSel 0xE3 Carrier wave select
UINT8 iFeedback 0xC0 Feedback/connection
BYTE[5] Padding to bring instrument definition up to 16 bytes

There are 16 default instruments, repeated into the 128 available MIDI instruments (so instrument 0, 16, 32, etc. all refer to this first default instrument. See #Default instruments below) The instrument block then overrides these defaults. Word Rescue is notable for having CMFs that rely on these default instruments being present and correct.

Percussive instruments

Since each CMF instrument contains both OPL modulator and OPL carrier settings, when an instrument is selected in a CMF file, both the modulator and carrier settings are loaded into the OPL chip for that channel.

When the CMF is in percussive mode however (see #Controller 0x67: Rhythm mode below), most of the percussive instruments only occupy either a modulator or a carrier (i.e. half an instrument.) This means that loading these instruments must be treated slightly differently, as a whole instrument is supplied but only half of it will be loaded into the OPL chip, and not necessarily the expected half.

When percussive mode is active and an instrument change event (MIDI event 0xC0) is received on a percussive channel (12-16 inclusive), the instruments should be loaded as follows:

CMF channel Instrument Instrument source OPL cell
12
Bass drum Modulator
Carrier
13 - Channel 7 Modulator
16 - Channel 7 Carrier
13
Snare drum Modulator 17 - Channel 8 Carrier
14
Tom tom Modulator 15 - Channel 9 Modulator
15
Top cymbal Modulator 18 - Channel 9 Carrier
16
Hi-hat Modulator 14 - Channel 8 Modulator

Despite some documentation suggesting that certain instruments cannot have their pitch set, the Creative Labs SBFMDRV will play all percussive instruments at the requested pitch. Note however that as only one pitch can be set per channel, playing both a snare and hi-hat, or both a tom tom and top cymbal, at the same time, will cause a conflict, potentially changing the pitch of an already-playing note. The Creative Labs SBFMDRV simply writes the pitch as each note is played, changing the pitch of any currently playing note on the shared channel.

Be aware that some songs (e.g. Kiloblaster's song_2) play two different percussive instruments simultaneously, when those two instruments share the same OPL channel (e.g. hi-hat and snare drum.) The notes are actually played at different pitches, which introduces a conflict, as only one note frequency is available for the channel and it must be shared by both instruments. In this case the order of events is important, as the pitch of the last event at that instant is the one that gets set for the channel. Normally with MIDI, if notes are played at the same instant in time it does not matter which order they are issued in, however in this case the song is quite different if the order is not maintained.

Essentially SBFMDRV writes the pitch to the OPL channel as the events are encountered, so whichever note is played last is the frequency the channel will be set to.

Song data

The song data itself is in standard MIDI format - identical to the data stored in a MIDI MTrk block (but without the "MTrk" header of course.) For details on this, see the MIDI data description.

One difference worth noting is that the official Creative Labs CMF player does not support pitch bends (code 0xE0) and those events are simply ignored. Simple sysex data appears to be ignored also, however its use in a CMF file can cause problems with other players.

MIDI controllers

In addition to the standard MIDI controllers (which are actually rarely used in CMF files), the following controllers have special meaning in a CMF file. Each controller has one data byte (the "controller value", 0-127), and the meaning of this byte will of course depend on which controller was selected.

Controller Purpose
0x63 Non-standard extension: AM+VIB depth control (see below)
0x66 Set marker byte (used as a status flag readable by a music player)
0x67 Switch OPL between melody and rhythm mode (see below)
0x68 Transpose up by given number of 1/128 semitones
0x69 Transpose down by given number of 1/128 semitones
Controller 0x63: Depth control

MIDI controller 0x63 is a nonstandard extension to allow the OPL's AM+VIB depth control to be adjusted (normal CMF playback has both the AM and VIB depth control fixed in the on state.) When this controller is set to zero, the depth control is switched off (i.e. amplitude depth is 1 dB, vibrato depth is 7 cents.) Setting the controller to a value of one increases the vibrato to a depth of 14 cents (OPL port 0xBD has bit 6 set), and setting the control to a value of two increases the amplitude depth to 4.8 dB (OPL port 0xBD has bit 7 set). Setting the control to a value of three increases both depth controllers, which is the CMF default setting (OPL port 0xBD has bits 6 and 7 set.)

Since this setting is global and affects the entire OPL chip, it does not matter which channel the controller change is issued on.

Controller 0x66: Song markers

Controller 0x66 is used to set a marker byte in the song. This can be used to notify the music player that a certain point in a song has been reached, or to trigger some kind of action in time with the music.

Controller 0x67: Rhythm mode

MIDI controller 0x67 is used to switch between "melody mode" and OPL "rhythm mode." In melody mode, nine-channel FM music is possible. In rhythm-mode, six-channel FM music is possible, with an additional five channels used for percussion (allowing 11 sounds to be played simultaneously.) In this mode, the last five MIDI channels are reserved for the percussive instruments as shown below.

Since this setting is global and affects the entire OPL chip, it does not matter which channel the controller change is issued on.

Hex channel MIDI channel Use in melody mode Use in rhythm mode
0x00 1 Normal instrument Normal instrument
0x01 2 Normal instrument Normal instrument
0x02 3 Normal instrument Normal instrument
0x03 4 Normal instrument Normal instrument
0x04 5 Normal instrument Normal instrument
0x05 6 Normal instrument Normal instrument
0x06 7 Normal instrument Normal instrument
0x07 8 Normal instrument Normal instrument
0x08 9 Normal instrument Normal instrument
0x09 10 Normal instrument Normal instrument
0x0A 11 Normal instrument Normal instrument
0x0B 12 Normal instrument Bass drum
0x0C 13 Normal instrument Snare drum
0x0D 14 Normal instrument Tom-tom
0x0E 15 Normal instrument Top cymbal
0x0F 16 Normal instrument Hi-hat cymbal

See #CMF/MIDI vs Adlib channels below for more details.

Controller 0x68: Transpose up

This controller transposes all following notes on the channel up by the given number of 1/128 semitones. Since the controller value must be between 0 and 127, it will allow a song to be transposed up anywhere between zero and almost a full semitone. The value is absolute, so a controller requesting a transpose up by 127 followed by a transpose up by 64, will initially be transposed up by almost a full semitone (127) but will then be transposed back by a half semitone (to 64).

A value of zero resets back to "not transposed."

Controller 0x69: Transpose down

Identical to controller 0x68 (Transpose up) only of course in the opposite direction, and again only affecting the channel the controller is issued on.

Notes

Keyon/off handling

Some songs don't always send keyoffs after a keyon, or they send them out of order (e.g. note 1 on, delay, note 2 on, note 1 off, delay, note 2 off.) If you don't check this you'll end up switching a note off too early (in the above example the "note 1 off" should *not* switch off "note 2" that was switched on just before it.) song_9.cmf from the first episode of Xargon is an excellent example of this, right at the start of the song.

The best way of handling this when playing through an OPL chip seems to be to remember the last note played on a channel, and upon receiving a keyoff, only process it if the keyoff is for the note currently playing on the channel (otherwise it can be discarded.) If a keyon is received and a note is already being played on a channel, the old note should be switched off just before playing the new note.

Default instruments

Although no documentation exists about this, it seems that the Creative Labs player sets the 128 available instruments based on 16 defaults looped/repeated to fill the 128 slots. They do not appear to be based on any MIDI instrument specification. Any instruments included in the CMF file then override these defaults. Some songs (e.g. the Word Rescue background music) rely on these default instruments and don't play properly if only their custom instruments are set.

There appear to be a different set of default instruments used for the percussion channels when rhythm mode is active. More investigation needs to be done to determine what these are and if they are related to the 16 default melody instruments.

! Post a set of OPL settings here (perhaps in IBK Format) that provides these default parameters.

! Confirm whether it's possible to set more than 16 custom instruments, without them looping and overwriting the earlier ones.

CMF/MIDI vs Adlib channels

MIDI (and consequently CMF) supports up to 16 channels. The OPL2 synth on the Adlib only supports a maximum of nine channels in normal mode, or six channels plus five percussion instruments in rhythm mode.

This means that any CMF player must correctly map up to 16 MIDI channels to only nine OPL channels. Many songs from games work correctly with a 1:1 mapping (i.e. the game music doesn't go beyond MIDI channel 9), however there are some songs that use channels beyond this (e.g. Word Rescue again, which, given the Voyetra credit, has probably been minimally converted from MIDI.)

At the time of writing, there are no known songs that use more than nine MIDI channels simultaneously, however Word Rescue's E1L1 song appears to sound more than nine notes simultaneously across a smaller number of channels, so if all these notes should be heard, the extended OPL3 channels probably need to be used. Xargon song9 also sounds multiple notes simultaneously in a single channel. Either of these will result in lost notes unless the available channels are cleverly managed.

As an aside, it would be interesting to test this with Creative's driver to see how it behaves.

Note velocity

The velocity values are loaded more or less directly into the OPL chip. This means unlike MIDI, the velocity is not a linear scale from 0 to 127, but logarithmic. A value of 1 is almost silent, and rapidly increase in volume so that values 2 and 3 are much louder. At the other end of the scale, 127 is full volume, but 126 and 125 are barely any quieter.

Tools

  • CMF2MID - convert CMF files into MIDI (Link 1)
  • AdPlug/AdPlay - Plugins for various audio players (plus a command line player) that mostly supports CMF files
  • Malvineous' Adlib plugin - Plugin for XMMS and Audacious that plays most CMF files more accurately than AdPlug

Similar formats

  • The CMF song data is stored in the same format as used by MIDI files
  • The SBI Format (SoundBlaster Instrument) is the same as used in the CMF instrument block, with a header on the front.
  • The IBK Format (Instrument Bank) is a group of SBI instruments, similar to the whole CMF instrument block.