XM_file_format.pdf

The Unofficial XM File Format Specification:

FastTracker II, ADPCM and Stripped

Module Subformats

Revision 2 – Jun 08, 2007

Introduction

This specification describes the structure of regular FastTracker II, ADPCM-compressed and Stripped XM files. It

is unofficial because uFMOD doesn’t hold the authorship or copyright of the XM file format. There are many

extensions to the original XM format available nowadays, e.g.: ADPCM-compressed XM, OggVorbis-copressed

XM, Stripped XM and others. Most XM files ain’t 100% compliant with the original standard because of accidental

or intentional modifications. So, it’s hardly possible to think about a universal XM standard any more. Since the

original specification is pretty much outdated and it doesn’t cover the already mentioned extensions, the uFMOD

development team desided to make this new document available to public domain.

The original FastTracker II file format was introdiced by Triton team in the early 90s. It is commonly referred as

the “e X tended M odule” (hence the file extension). The XM format is an extended version of the original MOD

format, featuring multisample instruments, volume and panning envelopes, portamento frequency tables, new

extended effect commands, basic pattern compression, among other improvements.

The ADPCM-compressed XM extension is a non-standard XM subformat introduced in ModPlug tracker and

player. It has the same XM file format structure, except that at least one of the samples is compressed in 4-bit

ADPCM format. An ADPCM-compressed sample is almost 2 times smaller than it’s uncompressed equivalent.

The drawback is the sound quality – significant distortion may arise when using ADPCM.

Another popular extension is OXM – OggVorbis-compressed XM. It preserves the original XM file structure,

except the instrument samples, which are compressed in OggVorbis stream format. There are at least 2 known

OXM subformats. None of them is covered in this document. You can use the Firelight Tech.’s FMOD library to

play OXM files.

The Stripped XM file format is another non-standard XM subformat. It was introduced in uFMOD in 2006. A

Stripped XM file is always smaller than a regular XM, because it uses a more compact set of headers. Supporting

Stripped XM file format is not harder than supporting the original XM file format. The original XM file format

becomes a subset of the Stripped one. So, a player supporting Stripped files will also support regular XM files.

The audio content of the XM file is unaffected while “stripping” it’s file structure. Currently only uFMOD supports

Stripped XM files.

Even more non-standard XM extensions exist. For example, some trackers introduce undocumented effect

commands used as triggers for software events, Text2Speech (TTS) metadata, watermarks and so on.

Unfortunately, very little or no documentation is provided for other people to support this new features or at least

ignore them safely while loading a modified XM file.

Once again, this document describes only the original FastTracker II file format, the ADPCM extension and the

Stripped subformat – all at once. As soon as uFMOD starts supporting any other XM extensions, they will appear

here as well. No effect commands are actually described in this document. If looking for effects, take a look at

Thunder’s MODFIL10.TXT.

The current version of this specification is maintained on the Web at:

http://ufmod.sourceforge.net/

General layout of the XM file

XM header

header of 1st pattern

data of 1st pattern

header of 2nd pattern

data of 2nd pattern

...

header of last pattern

data of last pattern

1st part of 1st instrument header

If number of samples > 0, then this data follows:

2nd part of 1st instrument header

1st sampleheader

2nd sampleheader follows (if any)

...

last sampleheader (if any)

If the sample size > 0 (1st sample header), then

sampledata of 1st sample follows

If the sample size > 0 (2nd sample header), then

sampledata of 2nd sample follows

...

If the sample size > 0 (last sample header), then

sampledata of last sample follows

1st part of 2nd instrument header

... same layout as 1st instrument

...

1st part of last instrument header

... same layout as 1st instrument

Additional information

Volume and Envelope Formulas

Periods and Frequencies

XM header

Offset Length Type Ref Example

0 17 char ID text

'Bellissima 99 (mix) '

37 1 byte 0x1A

38 20 char Tracker name

'FastTracker v2.00 '

58 2 word Version number

04 01

60 4 dword Header size

14 01 00 00

64 2 word Song length

3E 00 (1..256)

66 2 word Restart position

00 00

68 2 word Number of channels

20 00 (0..32/64)

70 2 word Number of patterns

37 00 (1..256)

72 2 word Number of instruments

12 00 (0..128)

74 2 word Flags

01 00

76 2 word Default tempo

05 00

78 2 word Default BPM

98 00

80 ? byte Pattern order table

00 01 02 03 ...

ID text

Should read 'Extended module: ' in a normal XM file. In a Stripped XM this field usually contains just nulls.

Some people clear or scramble this magic text in their XM files when embedding into an EXE to prevent

others from ripping the track. Don't rely on this string when checking an XM file for validity.

Module name

Should be an ASCII string padded with spaces. Might be zero padded or empty as well (all spaces or all

nulls). Some people store random data here. Don't rely on Module name being a valid ASCII string.

0x1A

The hex value 0x1A in a normal XM file or 0x00 in a Stripped on. Since most players check this field,

XMStrip clears it to prevent players not actually supporting the stripped format from incorrectly loading a

Stripped XM. Apparently the value 0x1A has a special “escape” meaning. For example, if you print the

contents of an XM file using the shell’s cat command, it will stop after dumping “Extended module: “ and the

module’s name. None of the following binary garbage will be printed. At least that’s the way it was

supposed to be if people respected the standards. Oh, well...

Tracker name

Should read 'FastTracker v2.00 ' or 'FastTracker II ' but some trackers (e.g. DigiTracker) use this field

for other purposes (DigiTracker stores the Composer's name here). Should contain nulls in a Stripped XM.

This field being trashed doesn't necessarily mean that the XM file is corrupt.

Version number

Hi-byte major and low-byte minor version numbers in a normal XM or 0x0000 in a Stripped XM. For

example, 0x0104 means v1.4. None of the extensions use this field for identifying themselves. So, v1.4

doesn’t mean it’s a standard XM file. It’s not meaningful at all.

Header size

Total size of the following header data till header of 1st pattern. Using this value is the only way to locate

the header of the 1st pattern. In a normal XM the minimal value is 20 + 256 = 0x00000114. This is so

because the pattern order table in a normal XM has a fixed size of 256 bytes. For example, if the pattern

order table consists of the following indexes:

0 1 4 1

a normal XM file whould pad those values with zeroes:

17 20 char Module name

'Extended module: '

00 01 04 01 00 00 00 00 00 00 00 00 00 00 00 00

00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

Instead of zeroes, some trackers store negative values. The actual pattern order table length is given in the

[Song length] field (see below). So, you can easyly identify the padding bytes. That’s why thouse bytes are

not stored in a Stripped XM file and the [Header size] could be lower than 0x00000114. The minimal value

is 20 + 1 (at least 1 pattern should exist, right?). In both normal and Stripped XM files [Header size] + 60 is

the exact offset where the 1st pattern header begins. The only difference is that no padding exists in a

Stripped XM. The same example pattern order in a Stripped XM whould be:

00 01 04 01

Using only 4 bytes instead of 256. However, the formula is exactly the same in both cases.

Additional data may exist between the pattern order table and the 1st pattern header (normally you whould

just skip this additional data). Some trackers store the composer's name here, metadata and so on.

There is no practical maximum header size (except the obvious 2 32 -1 value), because nothing limits the

amount of additional data. That’s why you should always use the [Header size] value + 60 to jump directly

to 1st pattern header.

Song length

This is really the pattern order table size in bytes, as mentioned above. Maximum value is 256. Minimum is

1, because a zero-lenght song doesn’t make much sense.

Restart position

Zero-based index to pattern order table where the track should continue at after the end of the table is

reached. Some trackers append an empty (silence) pattern at the end and set restart position to that

pattern to prevent looping. When restart position holds an invalid index (greater than [Song lenght]), zero

value should be used instead.

Number of channels

Number of mixing channels. Has nothing to do with mono/stereo. Defines the number of columns in pattern

packets. In the original FastTracker II specification the maximum value was 32. However, XM files

containing more than 32 channels do exist. uFMOD suggests 64 as a more realistic maximum value.

Number of patterns

Number of patterns stored in file. There should be at least 1 pattern if you expect to hear anything out of the

speakers. The maximum value is 256. Don’t confuse this with [Song length]!

Number of instruments

In the range from 0 to 128.

Flags

Only LSB (bit 0) used. It defines the frequency table:

0 = Amiga

1 = Linear

See below for additional info.

Default tempo & Default BPM

Initial playback speed and BPM (Beats Per Minute).

Pattern order table

Defines the exact order in which XM patterns should be played. The size of this table in bytes is the song

length. For example:

05 08 03 08 ...

Pattern #5 will be the first one to play, if it exists in the file. If it doesn’t exist, an empty pattern (aka dummy

pattern) should be used instead. After #5 finishes playback, #8 will be triggered (once again, if it exists).

Then, #3 will start playing. Then, #8 will be used once again and so on.

Plik z chomika:

Inne pliki z tego folderu:

Inne foldery tego chomika: