Karl Morton Music Format

From ModdingWiki
Jump to: navigation, search
Karl Morton Music Format
Format typeMusic
Notation typeTracked
InstrumentsPCM
Max channel count32 (only 4 usable in-game)
Max track countno limit
Max pattern countn/a
Max order countn/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 PlatformPlay? Create new? Modify? Convert/export to other? Import from other? Access hidden data? Edit metadata? Notes
OpenMPT WindowsYesNoNoManyNoNoNo At the time of writing, OpenMPT 1.30 (which adds support for this format) is not released yet.
mod2mus AnyNoYesNoNoMODNoNo 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!)