Karl Morton Music Format
| Format type | Music |
|---|---|
| Notation type | Tracked |
| Instruments | PCM |
| Max channel count | 32 (only 4 usable in-game) |
| Max track count | no limit |
| Max pattern count | n/a |
| Max order count | n/a |
| Tags? | Title, instrument names |
| Games |
The Karl Morton Music Format is the music format used by Karl Morton's sound engine used in the games Psycho Pinball, Micro Machines 2 and Back to Baghdad, although the latter only uses its sound effect file format, not the music format. This is not the official name of the format, but as no official tooling or documentation seems to be available for this format, a simple name was chosen based on the sound engine author's name.
In general, this format follows the semantics of the ProTracker MOD format. Knowledge of the MOD format and its features is assumed.
A somewhat unique feature of this format is that subsongs can re-use samples with different metadata. For example, one song in a file might use a specific sample with a default volume of 64, while another song might reference the same sample data but with a default volume of 48. This allows for greater flexibility when reusing those samples between songs.
File format
The format follows an IFF-like structure, but with no explicit file header (the file directly starts with the first chunk).
Chunk Header
| Data type | Name | Description |
|---|---|---|
| char[4] | ID | chunk ID ("SONG" or "SMPL") |
| UINT32LE | length | chunk length, including this header (so must be at least 8) |
The first chunk in the file must be a SONG chunk, apart from this the chunk order doesn't matter.
Typically, SONG and SMPL chunks are interleaved, each SONG being followed by the SMPLs it adds to the sample pool shared between SONGs. But this order should not be relied on.
SONG chunk
Each subsong is represented by its own SONG chunk.
| Data type | Name | Description |
|---|---|---|
| char[32] | song name | null-terminated song name |
| SAMPLE_REFERENCE[31] | sample map | maps song samples to those samples in the global sample pool |
| char[2] | unknown | always 0 (maybe just padding) |
| UINT32LE | number of channels | between 1 and 4 - file will be rejected if this is > 32. If it's more than 4 but less than 33 the extra channels will simply not be played. |
| UINT32LE | restart position | byte offset into music data |
| UINT32LE | size of music data | should be chunk size - 1108 |
| char[] | music data | format is explained below |
SAMPLE_REFERENCE maps samples from the SMPL chunk pool to instrument numbers in the pattern editor (the first SAMPLE_REFERENCE is instrument 1, and so on). It is defined as follows:
| Data type | Name | Description |
|---|---|---|
| char[32] | sample name | must reference one of the SMPL chunks |
| UINT8 | MOD finetune | 0...15 |
| UINT8 | default volume | 0...64 |
Music data is basically one gigantic pattern and stored in row-major order (like most module formats). The pattern is played in a strictly linear order, there are no jump commands or pattern loops. There is per-channel state that stores the last used note, instrument, command and parameter as well as a repeat counter.
To decode one pattern cell:
- If repeat counter > 0: Decrement repeat counter by 1 and reuse note, instrument, command and parameter from previous row. Continue with next channel.
- Read UINT8, let's name it NOTE.
- If (NOTE AND 0x80): Reuse note, instrument, command and parameter from previous row and set repeat counter to (NOTE AND 0x7F). Continue with next channel.
- If NOTE is between 1 and 36 (inclusively), it's a regular note (C-1 to B-3 in ProTracker), otherwise no note is present
- Read UINT8, let's name it INSTRUMENT.
- Set instrument number in this cell to INSTRUMENT AND 0x1F
- If (INSTRUMENT AND 0x80): Repeat previous command and parameter for this channel
- Otherwise, read the two UINT8s, the command and parameter bytes.
- Continue with next channel.
Command bytes and their translation to ProTracker MOD commands:
- 00: Cxx
- 01: EAx
- 02: EBx
- 03: E1x
- 04: E2x
- 05: E5x
- 06: 9xx
- 07: 3xx
- 08: 5xx
- 09: 4xx
- 0A: 6xx
- 0B: 0xx
- 0C: 1xx
- 0D: 2xx
- 0E: Axx
- 0F: E9x
- 10: Instant portamento (like 3FF but is always fully executed on first tick)
- 11: ECx
- 12: Fxx
- 13: 7xx
- 14: 000 (empty command)
Missing MOD effects are: 8, B, D, E3, E4, E5, E6, E7, E8, ED, EE, EF.
Most commands that translate to extended Exy commands can take values > 0x0F as parameters (finetune command ignores high nibble).
The player will jump to the restart position once the repeat counter of each channel has reached 0 and no bytes are left to be read.
If no tempo is specified on the first row of the pattern, the MOD defaults of tempo 125 and 6 ticks per row are assumed.
SMPL chunk
Every sample is described by its own SMPL chunk.
| Data type | Name | Description |
|---|---|---|
| char[32] | sample name | null-terminated, referenced by SONG chunks |
| UINT32LE | loop start | in bytes |
| UINT32LE | size of sample data | should be chunk size - 48 |
| char[] | sample data | in 8-bit signed mono PCM format |
Note that a SMPL can be shared between songs and use different finetune and volume values between songs.
A note on the string format
The last character of sample names must be a null-terminator (the engine uses a string comparison not limited to 32 characters when matching samples).
While it is not required by the engine, the following restrictions are proposed for newly created files to keep the life of developers easy that have to support dozens of files and may thus want to employ heuristics whether files are of a specific type:
It is suggested that all strings (i.e. instances of char[32]) do not use byte values 1 to 31 (so only printable ASCII/ANSI), and after the first null terminator, the rest of the string has to be padded with nulls as well.
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 |
|---|---|---|---|---|---|---|---|---|---|
| OpenMPT | Windows | Yes | No | No | Many | No | No | No | OpenMPT 1.30 or higher is required. |
| mod2mus | Any | No | Yes | No | No | MOD | No | No | Converts 1-4 channel ProTracker MOD files to MUS |
Credits
This file format was reverse-engineered by Saga. 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!)