CMF Format

From ModdingWiki
Jump to: navigation, search
CMF Format
Format typeMusic
Notation typeMIDI
InstrumentsOPL
Max channel count16
Max track count1
Max pattern countUnknown
Max order countUnknown
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

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

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.

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

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.

Frequency of percussion instruments

When playing a CMF in percussive mode, the instruments sharing a channel will obviously also share the same frequency number registers - so adjusting the frequency of the Snare for example, will also affect the frequency of the Hihat. There is some documentation floating around that says channels 15 and 16 (the Cymbal and the Hihat) should not be allowed to change frequency, instead relying on whatever their channel counterparts, the Tom and the Snare, last used. Unfortunately in some songs (Kiloblaster song_2.cmf for example) this doesn't sound right, and the Hihat unexpectedly changes frequency at the beginning of the song. It seems to be much more reliable to allow all the percussion instruments to set their own frequency when played.

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 channels simultaneously, or which sound multiple notes simultaneously in a single channel - either of which would result in lost notes unless clever programming was combined with more than one OPL synth.

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

Having said that, the AdPlug CMF player seems to take care of this mapping and appears to allow multiple notes to play simultaneously. This results in many songs sounding quite different to their in-game (and Creative's) player. This appears to be another case (like note velocity), of the songs supporting features that it would seem were never meant to be heard...

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.