CMF Format
| Format type | Music |
|---|---|
| Notation type | MIDI |
| Instruments | OPL |
| Max channel count | 16 |
| Max track count | 1 |
| Max pattern count | 1 |
| Max order count | 0 |
| Tags? | Title, Artist, Remarks |
| Games |
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 preceded it, the instruments were not sampled but were synthesised using the Adlib/SoundBlaster OPL chips.)
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 (BPM?) |
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 assumed "basic tempo" means BPM (beats per minute) as this is the meaning of the "basic tempo" field in the earlier AdLib MIDI Format.
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.
Be aware that the title/composer/remarks fields are supposed to be zero if there is no metadata, but Highway Hunter sets them to invalid values (past EOF), so you may wish to check that these fields are within range and ignore them otherwise.
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 |
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.xr1 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.
Keyon/off timing
Some songs play a note-on, then immediately (with no delay) have a corresponding note-off. If this is played faithfully, then the note will not be heard, however the Creative Labs player still plays these notes. The correct solution is ! currently unknown - wait for one tick or use the emulator callback between events?. A good example of this is the first few notes in song_32.xr1. (Discussion)
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.
Format violations
These format violations may require special consideration in order for a player to correctly handle these files.
- dan.cmf from Jill of the Jungle should end with bytes FF 2F 00 (the 00 indicating no data bytes for the 2F 'end of song' event) but it instead ends with FF 2F FE, with FE being an invalid (truncated) MIDI number.
- Highway Hunter CMF files contain invalid offsets for the metadata fields, as they point past the end of the file.
Tools
The following tools are able to work with files in this format.
| Name | Platform | Play? | Create new? | Modify? | Convert/export to other? | Import from other? | Access hidden data? | Edit metadata? | Notes |
|---|---|---|---|---|---|---|---|---|---|
| AdPlug/AdPlay | DOS, Linux, Windows | Yes | No | No | No | No | No | No | Plugins for various audio players (plus a command line player) that mostly supports CMF files |
| CMF2MID | DOS | No | No | No | Yes; .mid | Yes; .cmf | No | No | Convert CMF files into MIDI |
| Camoto/libgamemusic | Linux, Windows | Yes | Yes | Yes | Yes; many | Yes; many | No | Yes | Most accurate CMF player (comparing against SBFMDRV), correctly handles a number of edge cases |
| OPL3 Bank Editor | Linux, Windows, macOS | No | No | No | Yes; many | No | No | No | Import instruments from CMF files to use them in banks |
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.