CMF Format
From ModdingWiki
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 | iVersionMajor | Major version number (normally 0x01) |
| UINT8 | iVersionMinor | Minor 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) |
| UINT16LE | iInstrumentCount | Number of instruments used |
| UINT16LE | iTempo | Basic tempo (?) |
The song title, composer and remarks should follow this header (if present) and the instrument block should follow that.
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.
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 | ||
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.
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 |
It is uncertain how many channels can be used in total, as there are 16 MIDI channels available, but the OPL chip is only capable of playing nine channels in melody-mode, and 11 channels in rhythm-mode.
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.
Tools
- CMF2MID - convert CMF files into MIDI (need link)
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.
Categories: Adlib | MIDI | File Formats | Music Files | Jill of the Jungle | Kiloblaster | Xargon
