CMF Format
| Format type | Music |
|---|---|
| Notation type | MIDI |
| Instruments | OPL |
| Max channel count | 16 |
| Max track count | 1 |
| Tags? | Title, Artist, Remarks |
| Games | Jill 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 |
|---|---|---|---|
| Bass drum | Modulator Carrier |
13 - Channel 7 Modulator 16 - Channel 7 Carrier | |
| Snare drum | Modulator | 17 - Channel 8 Carrier | |
| Tom tom | Modulator | 15 - Channel 9 Modulator | |
| Top cymbal | Modulator | 18 - Channel 9 Carrier | |
| 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.
