MOD Format
| Format type | Music |
|---|---|
| Notation type | Tracked |
| Instruments | FM or samples |
| Max channel count | 4 - 8 |
| Max track count | 1 |
| Max pattern count | 128 |
| Max order count | 1 |
| Tags? | Instrument names |
| Games |
MOD is a name for a family of file formats typically used by a style of music player called a tracker. There have been many trackers and tracker style music libraries over the years, and as a result a number of variations of the format have developed.
Typically MOD files include sampled sounds, but some formats rely on an FM synthesizer instead, or as well.
Hopefully this page will outline the general principles of the MOD format. Follow the links for more specific details of actual MOD formats used by specific games.
Overview
The MOD format typically comprises 4 pieces of information.
- A header which contains global information such as a song title and overall volume, as well an the number of entries in each of the other sections.
- An instrument table, containing one or more instruments, sounds that should be used to play the music. Most often these are audio samples, but some MOD formats allow for FM synth instruments.
- A pattern table, which indicates the order in which patterns should be played.
- The patterns themselves. Short sections of the song, represented as notes and effects.
The patterns are played one at a time, using the order laid down in the pattern table.
Header section
| Data type | Name | Description |
|---|---|---|
| char[20] | Title | Song title, if not 20 characters long it will be null terminated. |
| char[22] | Sample 1 name | Name of the first sample, if not 22 characters long it will be null terminated. |
| UINT16BE | Sample 1 length | Length in 2-byte words of the first sample. |
| INT8 | Sample 1 finetune | |
| UINT8 | Sample 1 volume | |
| UINT16BE | Sample 1 repeat offset | Position in sample 1 to repeat from, when the note is held. In 2-byte words. |
| UINT16BE | Sample 1 repeat length | Length in 2-byte words of sample 1 repeat section. |
| char[22] | Sample 2 name | Name of the second sample... |
| etc | Typically there will be 15 or 31 samples in the file, depending on the specific format. | |
| UINT8 | Number of patterns | This is the number of patterns that need to be played, not necessarily the number of different patterns in the file. Some patterns may be played more than once. |
| UINT8 | Song end | What happens when the Number of patterns has been played. |
| UINT8[128] | Pattern table | The file contains at up to 128 different patterns, this table is the order in which patterns should be played. |
| FOURCC | File format tag | Code to indicate the specific tracker/MOD format. |
Pattern Table
The pattern table is fixed length, usually 128 bytes in length. Each byte indicates the number of a pattern to be played, and the total number of patterns to be played to complete the song is given in the Number of patterns byte. If a song contained a verse, chorus and bridge, (patterns 0, 1 and 2 respectively) then it might contain a pattern table
00 00 01 00 01 02 00 01 01 01
to play verse, verse, chorus, verse, chorus, bridge, verse, chorus, chorus, chorus.
The Song end byte indicates what happens when the number of patterns have been played. If this byte is greater than or equal to 127, the song will end. Otherwise it represents a position in the pattern table, where playing should continue, which allows the song to repeat, but it could have a non-repeating intro, played only the first time through.
Patterns
The patterns are stored sequentially. The best way to identify the number of patterns in the file is to find the largest pattern number used in the pattern table and add 1. Sample data will usually follow directly after the last pattern.
Each patterns contains 64 lines or steps. The MOD file will contain a number of different sound channels that play simultaneously, 4, 6 and 8-channel formats are common, and the specific format will indicate how many channels there should be. Each channel requires 4 bytes per step. So a 6 channel MOD file will require 4 * 6 * 64 bytes per pattern. Those 4 bytes in some order need to encode:
- The instrument (a sample number from 1 - 15 (or 1 - 31).
- The pitch of the note.
- An optional effect
The 4 bytes are broken into nibbles like so:
| Byte 1 High | Byte 1 Low | Byte 2 | Byte 3 High | Byte 3 Low | Byte 4 |
|---|---|---|---|---|---|
| wwww | XXXX | xxxxxxxx | yyyy | ZZZZ | uuuuvvvv |
wwwwyyyy is the sample number (which instrument)
XXXXxxxxxxxx is an indication of the note pitch (for sampled data this is usually a period value)
ZZZZuuuuvvvv is an optional effect
Effects (in these effects, a tick is 1/50th of a second) :
| ZZZZ | name | treat arguments as | description |
|---|---|---|---|
| 0 | Arpeggio | uuuu vvvv | Play the original note, then the note plus xxxx semitones, then the note plus yyyy semitones: each for 1/3 of the step time |
| 1 | Slide Up | uuuuvvvv | Increment the pitch (XXXXxxxxxxxx) by uuuuvvvv semitones every tick, so that the pitch increases during the step. |
| 2 | Slide Down | uuuuvvvv | Decremunt the pitch (XXXXxxxxxxxx) by uuuuvvvv semitones every tick, so that the pitch decreases during the step. |
| 3 | Tone Portamento | uuuuvvvv | Start the note at the same frequency as the previous note. Each tick, move the period uuuuvvvv closer to the XXXXxxxxxxxx period, until either it reaches XXXXxxxxxxxx or you get to the next step. |
| 4 | Vibrato | uuuu vvvv | Adjust the sample pitch up and down with an amplitude of +/- vvvv semitones at a rate of (uuuu * speed)/64 oscillations during the step. |
| 5 | Tone Portamento + Volume Slide | uuuu vvvv | Adjust the volume of the channel while an existing effect 3 (Tone Portamento) is occurring. if uuuu is nonzero, the volume is increased, if vvvv is nonzero, the volume is decreased. The volume is changed by the value each tick until there is a new effect. |
| 6 | Vibrato + Volume Slide | uuuu vvvv | Adjust the volume of the channel while an existing effect 4 (Vibrato) is occurring. If uuuu is nonzero, the volume is increased, if vvvv is nonzero, the volume is decreased. The volume is changed by the value each tick until there is a new effect. |
| 7 | Tremolo | uuuu vvvv | Adjust the sample volume up and down with an amplitude of vvvv * (speed - 1) such than (uuuu * speed)/64 oscillations occur during the step. |
| 8 | Set Panning Position | uuuuvvvv | Set the channel panning position using uuuuvvvv. 0 is all the way to the left, 255 is all the way to the right. |
| 9 | Set Sample Offset | uuuuvvvv | Start the sample from some point in the middle rather than the beginning. multiply uuuuvvvv by 256 to get the start position in bytes from the beginning of the sample. If no sample is specified by wwwwyyyy, then the most recently played sample is retriggered. |
| A | Volume Slide | uuuu vvvv | Change the volume of samples on this channel. If uuuu is nonzero, the volume is increased, if vvvv is nonzero, the volume is decreased. The volume is changed by the value each tick until there is a new effect. |
| B | Position Jump | uuuuvvvv | Jump to the start of a new pattern. uuuuvvvv gives a position in the Pattern Table to jump to. Note this is not a pattern number, but a position in the pattern table. |
| C | Set Volume | uuuuvvvv | Set the volume on this channel to uuuuvvvv. Legal volumes are in the range 0 to 64. This is true for all volume effects. |
| D | Pattern Break | uuuu vvvv | Jump straight to the start of the NEXT pattern in the pattern table. uuuu * 10 + vvvv is the step number in the pattern to start at. Note that there is a decimal 10 in that calculation, not 16. |
| E | Extended Effects | See extended effects table below | |
| F | Set Speed | uuuuvvvv | Set the speed of the playback. Often this effect will appear in one of the channels in the first step of the first pattern to be played, to set the song speed at the beginning. uuuuvvvv gives the number of ticks per step. During a song, this effect causes a speed change on the NEXT step. Valid speed values are from 1 to 31. A value larger than 31 should instead be interpreted as a value in beats per minute. 4 steps make up one beat in this scenario (therefore a single step equates to a sixteenth-note or a semiquaver). If no speed has been set in the first step, then the default speed is 6. |
Extended effects
| ZZZZ | uuuu | name | description |
|---|---|---|---|
| E | 0 | Set filter on/off | turn on a hardware filter if vvvv is non-zero, off otherwise. |
| E | 1 | Fineslide up | Functions like effect 1, but changes the pitch just once at the beginning of the step. |
| E | 2 | Fineslide down | Functions like effect 2, but changes the pitch just once at the beginning of the step. |
| E | 3 | Set glissando on/off | If vvvv is 1 turn on glissando, if 0 turn it off. While glissando is one, note slides occur at half a semitone at a time instead of 1 semitone. |
| E | 4 | Set vibrato waveform | Sets the waveform to be used for effect 4 vibrato. 0 is sine, 1 is a falling ramp, 2 is square, 3 is random, each retriggering when a new note is selected. 4 - 7 give the same waveforms, but without retriggering. |
| E | 5 | Set finetune value | When calculating the sample playback period for any given pitch, there is a finetune component. This effect overrides that finetune, to allow you to slightly detune a channel |
| E | 6 | Loop pattern | Specifies a looping section of a pattern. If vvvv is zero, this is the first step in the loop. If vvvv is nonzero it is the last step of the loop AND indicates how many times the loop should be played. |
| E | 7 | Set tremolo waveform | Sets the waveform to be used for effect 7 tremolo. The options are the same as for effect E4 above. |
| E | 8 | Rough panning | Sets the panning, not often implemented, less finesse than effect 8. 0 is all left, 15 is all right. |
| E | 9 | Retrigger sample | Retrigger the sample vvvv ticks into the step, and every vvvv ticks after that until the end of the step. |
| E | A | Fine volume slide up | Increase the volume of the channel by vvvv points just once. |
| E | B | Fine volume slide down | Decrease the volume of the channel by vvvv points just once. |
| E | C | Cut sample | Set the volume of the current sample to 0 AFTER vvvv ticks (Do not change the overall channel volume). |
| E | D | Delay sample | Delay the triggering of the sample until vvvv ticks in the step. |
| E | E | Delay pattern | Extend the length of the current step by vvvv steps. If the current speed was 6 ticks per step, then a value of 4 would cause this step to last 6 + 6 * 4 = 30 ticks. All notes and effects continue to play during this extension. |
| E | F | Invert loop | Play samples backward at a speed of vvvv. |
Sample data
After the patterns the file contains sample data. This is in 8-bit two's complement mono format. Each of the samples follows on from the previous, the file header will have indicated the length (in 16-bit words) of each of the samples.
Specific MOD formats
Remember that this is just a general form for MOD files, each specific format will have it's own details, and may differ in important ways.
KMD Format (Fury of the Furries)
External sources
mod.txt Link to a github copy of a file written many years ago by THUNDER (kurtt@sfu.ca) and revised and expanded by ByteRaver (erlandvo@hotmail.com)