KLM Format
|
This article is partially complete. This means that all known information is here, but there is still more information that needs to be discovered and/or reverse engineered. If you know some of the missing information, you can help the ModdingWiki by adding this info yourself. |
| Format type | Music |
|---|---|
| Notation type | Custom |
| Instruments | OPL |
| Max channel count | 9 |
| Max track count | 1 |
| Max pattern count | Unknown |
| Max order count | Unknown |
| Tags? | Unknown |
| Games |
The KLM Format is used by Wacky Wheels to store Adlib music tracks. It is probably named after Mark Klem, the Wacky Wheels composer.
File format
The file is structured as follows.
| Data type | Description |
|---|---|
| UINT16LE tempo | Playback speed in ticks per second |
| UINT8 unknown | Unknown |
| UINT16LE offNotes | Offset of song data |
| BYTE[] inst | Instrument data |
| BYTE[] notes | Song data |
Instrument block
The instrument block contains all the instruments used in the song. Each instrument is 11 bytes long, and is stored one after the other, in the following structure.
| Data type | OPL base register | Description |
|---|---|---|
| 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 iModChar | 0x20 | Modulator characteristic (Mult, KSR, EG, VIB and AM flags) |
| UINT8 iCarChar | 0x23 | Carrier characteristic (Mult, KSR, EG, VIB and AM flags) |
| UINT8 iModWaveSel | 0xE0 | Modulator wave select |
| UINT8 iCarWaveSel | 0xE3 | Carrier wave select |
| UINT8 iFeedback | 0xC0 | Feedback/connection |
Song data follows the instrument data.
Song data
The song data appears to be a custom event-style structure, superficially similar to MIDI. Each command byte is followed by a variable number of data bytes whose purpose depends on the command. The lower four bits are used for the channel (so command bytes of 0x30 and 0x31 perform the same command on the first and second channels, respectively.)
Many songs are stored with 128 ticks per quarter note, however some do differ. The correct value for this does not appear to be stored in the file, however this is not required for playback, only to neatly arrange notes on a graphical musical staff.
| Command byte | # of data bytes | Description |
|---|---|---|
| 0x00 | 0 | Note off |
| 0x10 | 0/2 | Note on with frequency |
| 0x20 | 1 | Volume |
| 0x30 | 1 | Set instrument |
| 0x40 | 0 | Note on |
| 0xFD | 1 | Delay |
| 0xFE | 2 | Long delay |
| 0xFF | 0 | End of song |
0x00: Note off
Turn the note on the current channel off (this sets the keyon bit to 0, on OPL base reg 0xB0).
0x10: Note on with frequency
Plays a note at the given frequency.
For channels 0-5 inclusive (i.e. command bytes 0x10 to 0x15), the first data byte is written to OPL base register 0xA0, and the second data byte is written to OPL base register 0xB0. As an example, if the command byte was 0x12 (set frequency on channel 2) then the two data bytes are written to register 0xA2 and 0xB2.
For channels 6-10 inclusive, there are no data bytes. Instead, these activate the OPL rhythm-mode percussion channels without setting a frequency:
| Command byte | OPL 0xBD bit | Instrument |
|---|---|---|
| 0x16 | 5 | Bass drum |
| 0x17 | 4 | Snare drum |
| 0x18 | 3 | Tom tom |
| 0x19 | 2 | Top cymbal |
| 0x1A | 1 | Hi-hat |
0x20: Volume
This command sets the velocity of subsequent notes on the channel. As with MIDI, the single data value ranges between 0 (silence) and 127 (full volume). Wacky Wheels uses this value to write the appropriate output level to the OPL chip, using the following formula:
- value = (127 - databyte) / 2
Thus a data byte of 0x58 results in the value 0x13 being written to the OPL chip. The value is written to the carrier operator on OPL base reg 0x40 (so channel 0 will actually write to reg 0x43.)
0x30: Set instrument
This command causes the instrument settings to be copied into the corresponding OPL registers for the channel. A data byte of 0x00 selects the first instrument in the instrument block.
0x40: Note on
Turn the note on the current channel on, at the last set frequency (this sets the keyon bit to 1, on OPL base reg 0xB0).
0xFD: Delay
This command causes a delay. The single data byte indicates how many ticks to wait for. Combined with the ticks-per-second tempo field in the header, the actual delay time can be calculated. With a data byte of 0x10 (delay for 16 ticks) and a tempo of 0x138 (312 ticks per second) the delay should be 16 ÷ 312 = 0.0512 seconds (51.2ms).
0xFE: Long delay
This command is the same as 0xFD except it is followed by a UINT16LE delay value rather than UINT8.
0xFF: End of song
This command has no delay bytes and signifies the end of the song data.
Tools
- Camoto can just about load KLM files (some instruments are a bit off)
Credits
This file format was reverse engineered by Malvineous. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)