Fast Tracker 2 Extended Module: Difference between revisions

Revision as of 16:53, 7 October 2022

Extension: xm

A 32-channel module format, used by Fast Tracker 2. The .XM extension stands for eXtended Module.

File Format

All words, double words, etc are little endian.

Header
- 17 bytes: 'Extended Module: '
- 20 bytes: Module name, terminated (padded) with spaces.
- Byte: 0x1A.
- 20 bytes: Tracker name, terminated (padded) with spaces. Usually 'FastTracker v2.00 '.
- 16-bit Word: File format version. Current version is 0x104.
- 32-bit LongWord: Header size, calculated from this offset, not from the beginning of the file. Usually 276.
- 16-bit Word: Song length in pattern order table.
- 16-bit Word: Restart position.
- 16-bit Word: Number of channels. Valid values are 2, 4, 6, 8, ..., 32.
- 16-bit Word: Number of patterns. Valid range: 0..256
- 16-bit Word: Number of instruments. Valid range: 0..128
- 16-bit Word: Flags:
  - bit 0: 0 - Amiga slides, 1 - Linear slides
- 16-bit Word: Initial speed.
- 16-bit Word: Initial BPM.
- 256 bytes: Pattern order.
- Header size minus 276 bytes: Optional extra header data.
Patterns
- Each pattern contains:
  - Pattern header:
    - 32-bit LongWord: Pattern header length. Usually 9.
    - Byte: Packing type. Always 0.
    - 16-bit Word: Number of rows in pattern. Valid range: 1..256
    - 16-bit Word: Packed pattern data size.
    - Pattern header length minus 9 bytes: Optional extra data.
  - Pattern data:
    - For each cell:
      - Read a single byte, this is called Mask.
      - if ((Mask & 0x80) == 0) then
        set note to Mask (range: 1..97; 1 is 'C-0', 96 is 'B-7', 97 is 'key off')
        
        set Mask to 0x1E
      - endif
      - if ((Mask & 0x01) != 0) then
        read next byte for note (range: 1..97; 1 is 'C-0', 96 is 'B-7', 97 is 'key off')
      - else
        no note in this cell
      - endif
      - if ((Mask & 0x02) != 0) then
        read next byte for instrument (range: 1..128)
      - else
        no instrument in this cell
      - endif
      - if ((Mask & 0x04) != 0) then
        read next byte for volume (range: 0..255, includes volume column effects)
      - else
        no volume in this cell
      - endif
      - if ((Mask & 0x08) != 0) then
        read next byte for effect type
      - else
        effect type is 0 for this cell
      - endif
      - if ((Mask & 0x10) != 0) then
        read next byte for effect param
      - else
        effect param is 0 for this cell
      - endif
Instruments
- For each instrument:
  - Instrument header:
    - 32-bit LongWord: Instrument header size (includes the optional extended header, described below, but doesn't include the sample headers).
    - 22 bytes: Instrument name.
    - Byte: Instrument type.
    - 16-bit Word: Number of samples in instrument.
  - if Number_of_samples_in_instrument > 0 then
    - Extended header:
      - 32-bit LongWord: sample header size.
      - 96 bytes: Sample number for each note.
      - 12*2*2 bytes: Volume envelope.
      - 12*2*2 bytes: Panning envelope.
      - Byte: Number of volume envelope points.
      - Byte: Number of panning envelope points.
      - Byte: Volume envelope sustain point.
      - Byte: Volume envelope loop start.
      - Byte: Volume envelope loop end.
      - Byte: Panning envelope sustain point.
      - Byte: Panning envelope loop start.
      - Byte: Panning envelope loop end.
      - Byte: Volume type.
      - Byte: Panning type.
      - Byte: Vibrato type.
      - Byte: Vibrato sweep.
      - Byte: Vibrato depth.
      - Byte: Vibrato rate.
      - 16-bit Word: Volume fadeout.
      - 16-bit Word: Reserved.
    - Sample headers for each sample of the instrument. Each sample header:
      - 32-bit LongWord: Sample length in bytes.
      - 32-bit LongWord: Loop start (in bytes, not in samples).
      - 32-bit LongWord: Loop length (in bytes, not in samples).
      - Byte: Volume.
      - Byte: Finetune (signed byte -16..+15).
      - Byte: Flags.
      - Byte: Panning.
      - Byte: Relative note number (signed byte).
      - Byte: Reserved.
      - 22 bytes: Sample name.
    - TODO: instrument sample data

Playback notes

TODO

Effects

Effects marked with (*) have 'memory'. This means that if their parameter is 0, they use the last nonzero parameter used for the same effect in this channel.

0xy

Arpeggio.

1xy (*)

Slide up.

2xy (*)

Slide down.

3xy (*)

Slide to note.

4xy (*)

Vibrato.

5xy (*)

Slide to note + volume slide. 300 + Axy.

6xy (*)

Vibrato + volume slide. 400 + Axy.

7xy (*)

Tremolo.

8xy

Set panning position.

9xy

Set sample offset.

Axy (*)

Volume slide.

Bxy

Jump to order.

Cxy

Set volume.

Dxy

Pattern break to row.

Exy - Miscellaneous effects

E0x

Set filter. Not implemented in Fast Tracker 2.

E1x (*)

Fine slide up.

E2x (*)

Fine slide down.

E3x

Set glissando control.

E4x

Set vibrato waveform.

E5x

Set finetune.

E6x

Loop pattern.

E7x

Set tremolo waveform.

E8x

Unused?!

E9x

Retrig note.

This effect retrigs the sample on every x-th tick. It doesn't use the counter, which is used by Rxy. Instead it uses the normal tick counter, which is reset on every row. Thus, it is more similar to the protracker version of the retrig effect, while Rxy is more similar to the Scream Tracker (and Impulse Tracker) version of retrig. Please note that similar does not mean 100% compatible :)

Notes:

If the parameter x is 0, this effect retrigs the sample only once - on tick 0.
If the parameter x is not 0, this effect retrigs on every x-th tick, except on tick 0.
Although this effect does not use the Rxy counter and never increments it, it resets it whenever a retrig occurs, *except* on tick 0.
This effect also does not touch the Rxy effect memory.

EAx (*)

Fine volume slide up.

EBx (*)

Fine volume slide down.

ECx

Note cut after x ticks.

EDx

Note delay for x ticks.

EEx

Pattern delay for x rows.

EFx

Funk it! Not implemented in Fast Tracker 2.

Fxy

Set speed.

Gxy

Set global volume.

Hxy (*)

Global volume slide.

Kxy

Key off. Same as note number 97.

Lxy

Set envelope position.

Pxy (*)

Panning slide.

Rxy (*)

Multi retrig note. Retrigger note every y ticks with volume modifier x. If y is 0, use the last nonzero retrig speed value used in a Rxy effect in the channel.

This effect uses a counter, that is increased on each tick. When the counter reaches the retrig value 'y' (or becomes greater, which could happen if the retrig value is decreased), the sample is retriggered, the note volume is modified according to the volume modifier 'x' and the counter is reset back to 0. The counter is reset (without retriggering the sample) also in the following cases:

before the start of playing the song
'when a row with an instrument number (doesn't matter if there's a note in the note column) is encountered in the channel
after the E9x effect, but only if it wasn't E90 and has retriggered the sample

Values for x:

0: Use the last nonzero volume modifier used in a Rxy effect in the channel. Wrongly documented as: "None"
1: -1
2: -2
3: -4
4: -8
5: -16
6: *2/3
7: *1/2
8: Documentation says "Unused", but actually works as leave the volume unchanged, unlike the 0.
9: +1
A: +2
B: +4
C: +8
D: +16
E: *3/2
F: *2

Txy

Tremor.

X1x (*)

Extra fine slide up.

X2x (*)

Extra fine slide down.

Volume column effects

Encoding

The volume column effect is encoded as a single byte in the pattern data. The meaning of all the possible byte values are:

Value	Meaning
0x00	Do nothing
0x01..0x0f	Invalid value
0x10..0x50	Set volume to Value-0x10
0x51..0x5f	Invalid value
0x60..0x6f	Volume slide down
0x70..0x7f	Volume slide up
0x80..0x8f	Fine volume slide down
0x90..0x9f	Fine volume slide up
0xa0..0xaf	Set vibrato speed
0xb0..0xbf	Vibrato
0xc0..0xcf	Set panning
0xd0..0xdf	Panning slide left
0xe0..0xef	Panning slide right
0xf0..0xff	Tone portamento

00..40