OpenMPT Wiki - User contributions [en]

Development: 228 Extensions

2025-09-05T17:09:41Z

CS127: /* Extended Pattern */ remove non-PC note info, since non-PC notes are now removed

This document is for OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). For older versions, check [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

The MPTM format is nearly identical to the IT format. The only difference is that OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings, and to specify that a file is in the MPTM format in the first place (otherwise it would be detected as IT).

This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions).

The chunk contains settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

Other MPTM features (e.g. fractional tempos) use [[Development:_OpenMPT_Format_Extensions|regular OpenMPT extensions]].

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format, '''even floating-point numbers'''):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit (single-precision) IEEE-754 floating-point number.
* <code>char</code>: a text character (text encoding may vary, so a single character is not necessarily one byte).
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned little-endian integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit width (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the least significant bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length ('''in bytes, not characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, "Windows codepage" refers to the user's selected ACP codepage in Windows (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to [[Wikipedia:Windows-1252|1252]], but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and a map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specify what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, unless the chunk has a "flag byte" (explained later) and its bit 0 is set.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether this chunk's descriptions (explained later) use a fixed 16-bit encoding (e.g. [[Wikipedia:Universal_Coded_Character_Set|UCS-2]]) instead of a fixed 8-bit encoding (e.g. [[Wikipedia:ISO/IEC_8859-1|ISO-8859-1]] / [[Wikipedia:Windows-1252|Windows-1252]]).
* Bit 7: whether this chunk's map contains descriptions for each entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, the string uses use a fixed 16-bit encoding (e.g. [[Wikipedia:Universal_Coded_Character_Set|UCS-2]]) instead of a fixed 8-bit encoding (e.g. [[Wikipedia:ISO/IEC_8859-1|ISO-8859-1]] / [[Wikipedia:Windows-1252|Windows-1252]]). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk. 
The current version of OpenMPT always writes this adaptive integer in two bytes, even if it only needs one. 
Additionally, this causes OpenMPT to be unable to write chunks with more than 16383 entries.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not). 
The current version of OpenMPT always writes this adaptive integer in eight bytes, even if it needs fewer bytes.
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''. Otherwise, they have to be stored in the same order that OpenMPT reads them.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, the string uses a fixed 16-bit encoding (e.g. [[Wikipedia:Universal_Coded_Character_Set|UCS-2]]) instead of a fixed 8-bit encoding (e.g. [[Wikipedia:ISO/IEC_8859-1|ISO-8859-1]] / [[Wikipedia:Windows-1252|Windows-1252]]). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to a 228 chunk with an ID of <code>mptm</code>, which contains all the settings for MPTM features (like custom tunings) in its entries. OpenMPT writes this chunk after the OpenMPT song extensions, and before the last four bytes of the file that specify its position.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the 8-bit Windows codepage.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code>, stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: Windows codepage.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk.

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code>.
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code>.

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>UTF8</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code>.

==== Tuning ====

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>.
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code>.

The chunk's version number is 67108868 (<code>0x04000004</code>).

These custom tuning chunks can also exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>UTF8</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name ('''in bytes, not characters''').
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the <code>mptm</code> chunk, is <code>1</code>.

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>uint8</code>
| Length of the tuning's name ('''in bytes, not characters''').
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection (or "pattern container" according to the source code) is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code>.
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code>.

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is not readable as a string, but instead, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code>.

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>data</code>
| (custom structure)
| The extended pattern data, which will be merged onto the IT pattern data when the file is read. 
Technically, it can be used for storing any pattern data, but OpenMPT uses it for storing only the Parameter Control notes of each pattern.
The data is stored in the same format as the [https://github.com/schismtracker/schismtracker/wiki/ITTECH.TXT#impulse-pattern-format IT pattern format], but without the first 8 bytes, and with a different format for mask bytes: 
* Bit 0: Include note (PC: <code>0xFC</code>, PCs: <code>0xFB</code>)
* Bit 1: Include plugin number
* Bit 2: Include high byte of controller ID
* Bit 3: Include low byte of controller ID
* Bit 4: Include high byte of parameter
* Bit 5: Include low byte of parameter
* Bit 6: Include extra data
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this entry, OpenMPT will read the order list from it, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code>.
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code>.

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>n</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code>.

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>u</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: Windows codepage.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|-
| <code>t</code>
| <code>uint32</code>
| Default tempo. This is a fixed-point number with 4 digits of fractional precision, i.e. divide the value by 10.000 to get the real tempo.
|-
| <code>s</code>
| <code>uint32</code>
| Default speed (ticks per row).
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code>.

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: Formats/IT

2025-07-11T01:27:14Z

CS127: /* ModPlug Tracker */ more precise upper limit, see https://modarchive.org/module.php?165622

General information concerning the IT file format. Any variable names in this document refer to the original variable names from [https://github.com/schismtracker/schismtracker/wiki/ITTECH.TXT ITTECH.TXT]. Variable names and hexadecimal numbers (in little-endian formats) are indicated by a <tt>monospace font</tt>.

Note: Impulse tracker is now open source! You can grab the [https://github.com/jthlim/impulse-tracker source code] at GitHub.

== Tracker IDs ==

The IT header contains a field, <tt>Cwt/v</tt>, which is used to identify the application that was used to create the file.
The following custom tracker IDs (read as little-endian hexadecimal numbers) are known to be found in the <tt>Cwt/v</tt> field:

* <tt>0xyy</tt> - Impulse Tracker x.yy - Many other trackers, like ModPlug Tracker, disguise as various versions of Impulse Tracker, so this is not a reliable way to tell if a file was really made with Impulse Tracker. See [[#Detecting other trackers|below]] for detecting such trackers.
* <tt>1xyy</tt> - Schism Tracker x.yy up to Schism Tracker v0.50, later versions encode a timestamp in the version number - see Schism Tracker’s <tt>[https://github.com/schismtracker/schismtracker/blob/master/schism/version.c version.c]</tt> or OpenMPT’s <tt>[https://source.openmpt.org/browse/openmpt/trunk/OpenMPT/soundlib/Load_it.cpp Load_it.cpp]</tt>.
* <tt>4xyy</tt> - pyIT x.yy
* <tt>5xyy</tt> - OpenMPT x.yy - lower two bytes of version number are stored in the "reserved" header field starting from OpenMPT 1.29.10.00 in compatible mode (otherwise OpenMPT song extensions are used as before).
* <tt>6xyy</tt> - BeRoTracker x.yy
* <tt>7xyz</tt> - ITMCK x.y.z (N.B. the user can override the value of the <tt>Cwt/v</tt> header by the <tt>-w</tt> command-line switch or the <tt>#TRACKER-VERSION</tt> command in the input file)
* <tt>7FFF</tt>, <tt>Cmwt = 0215</tt>: munch.py
* <tt>8xyy</tt> - Tralala x.yy; prealpha versions, built from svn, before the first release identify as version 0.00 (i.e. Cwt/v=8000)
* <tt>Cxyy</tt> - ChickDune ChipTune Tracker x.yy (currently non-public alpha version)
* <tt>DAEB</tt> - spc2it (after commit d3d1b524032f668be8ee20d25339e1c635fb9bcf)
* <tt>D1CE</tt> - [https://github.com/chr15m/itwriter itwriter] JavaScript library (user can change this default)

Are you a tracker developer and your tracker can save IT files? Please add your Tracker ID to this list!

Once we run out of tracker IDs, a more sophisticated approach will have to be found. For example, the ID <tt>0FFF</tt> could be reserved, and a pointer to extended tracker information could be placed in the <tt>reserved</tt> header field.

== Detecting other trackers ==

Some trackers disguise as Impulse Tracker 2, but there are ways to uncover this disguise:

=== BeRoTracker ===

Earlier versions of BeRoTracker, which did not use the tracker ID described above, can be identified by the four byte <tt>MODU</tt> magic which can be found after the Edit History / MIDI Macro / ModPlug extension block. <tt>Cwt/v</tt> is <tt>0217</tt> and <tt>Cmwt</tt> is <tt>0214</tt> or <tt>0200</tt> (overlaps with ModPlug Tracker). The edit history flag is set and there are always 0 entries in the edit history.

=== CheeseTracker ===

* <tt>Cwt/v</tt> and <tt>Cmwt</tt> are both <tt>0214</tt>
* Instrument mode flag is always set. The only other flags that can be optionally set are: Stereo Mode, Linear Slides, Old Effects, Compatible Gxx.
* The only <tt>special</tt> flag ever set is the song message flag (even though row highlights are always written).
* <tt>reserved</tt> is <tt>0</tt>
* All sample and instrument filenames read <tt>XXXXXXXX.YYY</tt> (obviously this should not be used as a stand-alone detection criterion, as files re-saved with other trackers will still use these filenames).

=== ChibiTracker ===

<tt>Cwt/v</tt> and <tt>Cmwt</tt> are both <tt>0214</tt>, <tt>reserved</tt> reads <tt>CHBI</tt>.

Further interesting criteria: Sample data is stored directly after header. All sample and instrument filenames read <tt>-DEPRECATED-</tt> (obviously this should not be used as a stand-alone detection criterion, as files re-saved with other trackers will still use these filenames). ChibiTracker also uses a line feed character (<tt>0A</tt> or <tt>\n</tt>) instead of a carriage return (<tt>0D</tt> or <tt>\r</tt>) in the song message.

=== ModPlug Tracker ===

* '''ModPlug Tracker 1.0 pre-alpha 4 (and possibly earlier) - 1.0 alpha 4''': <tt>Cwt/v</tt> is <tt>0202</tt>, <tt>Cmwt</tt> is <tt>0200</tt>, <tt>reserved</tt> is <tt>0</tt>, row highlights are both 0. These attributes alone are not enough to fingerprint these ModPlug Tracker versions, but luckily it also stores the remaining data in a very peculiar order: patterns first, then instrument headers, and then interleaves sample headers and their corresponding sample data. These versions also do not optimize empty 64-row patterns with a 0 parapointer, so they can be identified by checking if the first pattern parapointer is not 0 and less than the first sample parapointer.
* '''ModPlug Tracker 1.0 alpha 5''': <tt>Cwt/v</tt> is <tt>0214</tt>, <tt>Cmwt</tt> is <tt>0200</tt>, <tt>reserved</tt> is <tt>0</tt>. Pattern highlights and edit history flags are not set. Instruments are 560 bytes apart.
* '''ModPlug Tracker 1.0 alpha 6 / beta 1 / beta 2''': <tt>Cwt/v</tt> is <tt>0214</tt>, <tt>Cmwt</tt> is <tt>0200</tt>, <tt>reserved</tt> is <tt>0</tt>. Pattern highlights and edit history flags are set. Instruments are 560 bytes apart up to and including beta 1, in beta 2 they are 557 bytes apart.
* '''ModPlug Tracker 1.0 beta 3.2 - 1.09 build 66 (possibly up to build 77)''': <tt>Cwt/v</tt> is <tt>0214</tt>, <tt>Cmwt</tt> is <tt>0202</tt>, <tt>reserved</tt> is <tt>0</tt>. Instruments are 557 bytes apart.
* Newer versions of '''ModPlug Tracker''', '''OpenMPT 1.17 in compatible mode''': <tt>Cwt/v</tt> is <tt>0217</tt>, <tt>Cmwt</tt> is <tt>0200</tt>, <tt>reserved</tt> is <tt>0</tt>. If there are any instruments in the file, the instrument <tt>TrkVers</tt> field is <tt>0211</tt> for ModPlug Tracker and <tt>0220</tt> for OpenMPT. ModPlug Tracker writes <tt>FF</tt> for unused channels in the panning map, OpenMPT never does this. When an IT file uses all 64 channels (so the panning map cannot be used for distinction), the presence of ModPlug extensions (channel names, plugin chunks, etc.) can help telling MPT 1.16 and OpenMPT 1.17 compatibility export apart. The latter also does not save a final "---" order list item, while MPT 1.16 does.

=== OpenMPT ===

* OpenMPT 1.17.02.20 to OpenMPT 1.17.02.25 wrote the value <tt>0300</tt> in both the <tt>Cwt/v</tt> and <tt>Cmwt</tt> fields.
* OpenMPT 1.17.02.26 to OpenMPT 1.18 wrote the value <tt>0888</tt> in both the <tt>Cwt/v</tt> and <tt>Cmwt</tt> fields.
* Later versions of OpenMPT use the tracker ID provided above. In that case, the <tt>reserved</tt> field reads <tt>OMPT</tt> if the file was saved in normal mode, and is <tt>0</tt> (or the lower two bytes of version information starting from OpenMPT 1.29.10.00) if it was saved in compatible mode.

=== OpenSPC conversions ===

OpenSPC is a tool to convert SNES music from the SPC format to the IT format. If all the following conditions are true, you can be fairly sure that a module was written with OpenSPC:
* <tt>Cwt/v</tt> is <tt>0214</tt>.
* <tt>Cmwt</tt> is <tt>0200</tt>.
* <tt>Flags</tt> is <tt>09</tt> (Linear Slides, Stereo Playback).
* <tt>Special</tt> is <tt>0</tt>.
* Both pattern highlight values are <tt>00</tt>.
* No instruments are used.
* <tt>PatNum</tt> + 1 == <tt>OrdNum</tt>.
* Global volume is 128 decimal.
* Master volume is 100 decimal.
* Initial Speed is 1.
* Pan Separation is 128 decimal.
* Pitch wheel depth is 0.
* There is no song message, i.e. message length and offset are 0.
* <tt>reserved</tt> is 0.

Earlier versions of spc2it (before commit d3d1b524032f668be8ee20d25339e1c635fb9bcf) will be mis-identified as OpenSPC, as the tool closely follows the way its predecessor writes out IT files.

=== Unknown XM to IT conversion tool ===

There is a currently unknown XM to IT conversion tool which can be identified easily by the fact that it writes unsigned samples (which was the default only until Impulse Tracker 2.01). However, only sample slots with actual sample data should be considered for this test, as re-saving such a file in Impulse Tracker will not reset the unsigned flag for empty slots. If the following conditions are true, you can be fairly sure that a module was written with the unknown converter:
* <tt>Cwt/v</tt> is <tt>0204</tt>.
* <tt>Cmwt</tt> is <tt>0200</tt>.
* <tt>Flags</tt>: Stereo Playback, Instrument Mode, Old Effects are always set, Linear Slides are optional.
* <tt>Special</tt> is <tt>0</tt>.
* Both pattern highlight values are <tt>0</tt>.
* Global volume is 128 decimal.
* Master volume is 48 decimal.
* Pan Separation is 128 decimal.
* Pitch wheel depth is 0.
* There is no song message, i.e. message length and offset are 0.
* <tt>reserved</tt> is 0.
* Song title is no longer than 20 characters.
* All channels are panned centre (32) or muted, and their volume is 64 decimal.

To be extra sure, you can check all of these properties, but just checking <tt>Cwt/v</tt>, <tt>Cmwt</tt> and unsigned sample data is probably enough.

=== UNMO3 ===

UNMO3 is a tool to convert an MO3-compressed module file back into its original format.

In IT files created with UNMO3, the following are always true:

* <tt>Cwt/v</tt> and <tt>Cmwt</tt> are <tt>0214</tt>
* <tt>reserved</tt> is <tt>0</tt>
* <tt>pwd</tt> is 0
* Both row highlights are 0
* Flags: Use MIDI Pitch Controller (bit 6) and Request embedded MIDI configuration (bit 7) are never set

This partially overlaps with Impulse Tracker 2.14 and CheeseTracker fingerprints, however:
* CheeseTracker should write non-zero row highlights, even when resaving an UNMO3-ed file.
* It is highly unlikely that Impulse Tracker 2.14 writes a <tt>reserved</tt> value of <tt>0</tt>. If it writes zero row highlights, the row highlight <tt>special</tt> flag is set.
* Impulse Tracker 2.14 never writes an empty edit history (see below).
* CheeseTracker always uses instrument mode.

Some older versions of UNMO3 write out IT files that are malformed in some way or another, but it is easy to detect and work around. Some UNMO3-ed IT files are floating around in the wild, so it may be worthwile to implement those work-arounds:

==== Special flags prior UNMO3 2.4.0.2 ====

* UNMO3 2.4 (released in 2008) and older sets the <tt>special</tt> flag bits 1 (edit history) and 2 (row highlights) whenever bit 3 (MIDI macros) is set as well.
* UNMO3 2.4.0.1 (January 2011) always sets the <tt>special</tt> flag bit 1 (edit history), but the behaviour for bit 2 (row highlights) remains as in previous versions.
* UNMO3 2.4.0.2 (July 2011) never sets the row highlights flag.

==== Sample mode prior to UNMO3 2.4.0.1 ====

UNMO3 2.4 and older reserves space for the instrument parapointers (as many as there are samples) even when the IT file is in sample mode. This can be detected by the fact that 4 * <tt>SmpNum</tt> zero bytes follow after the pattern parapointers. These bytes need to be skipped in order to be able to read MIDI macros and ModPlug plugin settings which may potentially follow.

UNMO3 2.4.0.1 fixes this problem.

==== Edit History prior to UNMO3 2.4.0.1 ====

As mentioned above, UNMO3 older than version 2.4.0.1 may or may not set the edit history flag, but they always write two edit history length bytes (zeroes) in the file anyway. Keep this in mind, as MIDI Macros and ModPlug plugin settings will not load properly if you don’t.

* '''Edit history flag is set''': Nothing needs to be done. We can still use this for identifying UNMO3-saved IT files, because Impulse Tracker never writes an edit history of length 0.
* '''Edit history flag is not set''': This is the troublesome case due to MIDI macros and plugin settings. However, a reliable way to detect such malformed IT files would be to try to read the edit history length if all of the above detection criteria for UNMO3 are fulfilled. For those old UNMO3 versions, you should read two zero bytes. If that is the case, it means that the first MIDI macro would be empty (if MIDI macros are embedded) or the first plugin chunk ID starts with two zero bytes (impossible). Since UNMO3 writes out default values for the nine global MIDI macros, the first MIDI macro would have to start with “FF” (MIDI Start) and not be empty, so it is clear that the two zero bytes belong to the (empty) edit history.

Later version of UNMO3 set the correct header flag for the edit history and write the two zero length bytes.

== Special Header Flags ==

The following "Special" flags are not documented:

* Bit 1 (<tt>02</tt>): If set, edit history information (see [[#Edit History|below]]) is present.
* Bit 2 (<tt>04</tt>): If set, the row highlights (at offset <tt>1E</tt> - <tt>1F</tt>) should be read. If not set, they should be ignored.

== Edit History ==

It is little known that Impulse Tracker 2.08 and later keep track of when an IT file is opened and how long it is left open.
The edit history can be found directly after the IT header and before the possibly present MIDI macro configuration.

A 16-Bit integer <tt>num</tt> tells how many edit history blocks are present. Every block is 8 bytes long, so the 16-bit integer is followed by <tt>8 * num</tt> bytes of edit history information.

Each history block consists of a 16-Bit FAT date, a 16-Bit FAT time and a 32-Bit DOS timer, which contains the time how long the file was open in the editor, in 1/18.2th seconds.
Information on how to decode the FAT date and time stamps can be found on the [https://msdn.microsoft.com/en-us/library/windows/desktop/ms724247%28v=vs.85%29.aspx MSDN].

Note: Many programs don’t write an edit history, but they set the edit history flag in the header and write the two zero bytes for the history length. Many of them also ignore the edit history flag when loading files and always read the two <tt>num</tt> num bytes (ignoring the special flag), so if you want to write out an IT file that does not have an edit history and do not mind about the two extra bytes, the safest (most compatible) way is to set the edit history flag and write two zero bytes for <tt>num</tt>.

Also note that none of this is really relevant if you are sure that you never write out the MIDI macro configuration or ModPlug extensions, since these are the only two things that could normally follow the edit history. So if you have no MIDI macros and no ModPlug extensions, it is always safe to not set the special flag and not write the two extra bytes.

== Edit Timer ==

Before the addition of the full Edit History, a simple Edit Timer was stored in the <tt>reserved</tt> field of the file header. Starting from Impulse Tracker 2.07, this field contains the total edit time as a 32-Bit DOS timer (same resolution as in the Edit History). Starting from Impulse Tracker 2.08, the timer is encrypted. To decrypt:

editTime = editTime XOR 'ITRK'
editTime = editTime RoR 7
editTime = -editTime
editTime = editTime RoL 4
editTime = editTime XOR 'JTHL'

== Proposed way to store compressed stereo samples ==

Since Impulse Tracker itself does not support stereo samples, a common way of how to decode compressed stereo samples had to be found - After all, it is possible to just treat them as one continuous stream (not stopping the encoding / decoding process after the end of the left channel), or to treat them as two separate, consecutive streams. XMPlay was probably the only player that could handle compressed stereo samples even before there was a single implementation for saving compressed stereo samples. GreaseMonkey has decided to follow [https://www.un4seen.com/forum/?topic=12448.msg86479#msg86479 XMPlay's way] of decoding compressed stereo samples by treating them as two streams of the same length, so OpenMPT follows this example. If you intend to add IT sample compression support in your application, you should do the same to ensure compatibility across as many applications as possible.

== OpenMPT Hacks ==

For a list of all the file format hacks that ModPlug Tracker / OpenMPT added to the IT format over the years, see the [[Development: OpenMPT Format Extensions|OpenMPT Format Extensions]] article.

[[Category:Development|Formats/IT]]
[[Category:IT Format|Format Specification]]

Development: Formats/IT

2025-07-11T01:21:50Z

CS127: /* ModPlug Tracker */

General information concerning the IT file format. Any variable names in this document refer to the original variable names from [https://github.com/schismtracker/schismtracker/wiki/ITTECH.TXT ITTECH.TXT]. Variable names and hexadecimal numbers (in little-endian formats) are indicated by a <tt>monospace font</tt>.

Note: Impulse tracker is now open source! You can grab the [https://github.com/jthlim/impulse-tracker source code] at GitHub.

== Tracker IDs ==

The IT header contains a field, <tt>Cwt/v</tt>, which is used to identify the application that was used to create the file.
The following custom tracker IDs (read as little-endian hexadecimal numbers) are known to be found in the <tt>Cwt/v</tt> field:

* <tt>0xyy</tt> - Impulse Tracker x.yy - Many other trackers, like ModPlug Tracker, disguise as various versions of Impulse Tracker, so this is not a reliable way to tell if a file was really made with Impulse Tracker. See [[#Detecting other trackers|below]] for detecting such trackers.
* <tt>1xyy</tt> - Schism Tracker x.yy up to Schism Tracker v0.50, later versions encode a timestamp in the version number - see Schism Tracker’s <tt>[https://github.com/schismtracker/schismtracker/blob/master/schism/version.c version.c]</tt> or OpenMPT’s <tt>[https://source.openmpt.org/browse/openmpt/trunk/OpenMPT/soundlib/Load_it.cpp Load_it.cpp]</tt>.
* <tt>4xyy</tt> - pyIT x.yy
* <tt>5xyy</tt> - OpenMPT x.yy - lower two bytes of version number are stored in the "reserved" header field starting from OpenMPT 1.29.10.00 in compatible mode (otherwise OpenMPT song extensions are used as before).
* <tt>6xyy</tt> - BeRoTracker x.yy
* <tt>7xyz</tt> - ITMCK x.y.z (N.B. the user can override the value of the <tt>Cwt/v</tt> header by the <tt>-w</tt> command-line switch or the <tt>#TRACKER-VERSION</tt> command in the input file)
* <tt>7FFF</tt>, <tt>Cmwt = 0215</tt>: munch.py
* <tt>8xyy</tt> - Tralala x.yy; prealpha versions, built from svn, before the first release identify as version 0.00 (i.e. Cwt/v=8000)
* <tt>Cxyy</tt> - ChickDune ChipTune Tracker x.yy (currently non-public alpha version)
* <tt>DAEB</tt> - spc2it (after commit d3d1b524032f668be8ee20d25339e1c635fb9bcf)
* <tt>D1CE</tt> - [https://github.com/chr15m/itwriter itwriter] JavaScript library (user can change this default)

Are you a tracker developer and your tracker can save IT files? Please add your Tracker ID to this list!

Once we run out of tracker IDs, a more sophisticated approach will have to be found. For example, the ID <tt>0FFF</tt> could be reserved, and a pointer to extended tracker information could be placed in the <tt>reserved</tt> header field.

== Detecting other trackers ==

Some trackers disguise as Impulse Tracker 2, but there are ways to uncover this disguise:

=== BeRoTracker ===

Earlier versions of BeRoTracker, which did not use the tracker ID described above, can be identified by the four byte <tt>MODU</tt> magic which can be found after the Edit History / MIDI Macro / ModPlug extension block. <tt>Cwt/v</tt> is <tt>0217</tt> and <tt>Cmwt</tt> is <tt>0214</tt> or <tt>0200</tt> (overlaps with ModPlug Tracker). The edit history flag is set and there are always 0 entries in the edit history.

=== CheeseTracker ===

* <tt>Cwt/v</tt> and <tt>Cmwt</tt> are both <tt>0214</tt>
* Instrument mode flag is always set. The only other flags that can be optionally set are: Stereo Mode, Linear Slides, Old Effects, Compatible Gxx.
* The only <tt>special</tt> flag ever set is the song message flag (even though row highlights are always written).
* <tt>reserved</tt> is <tt>0</tt>
* All sample and instrument filenames read <tt>XXXXXXXX.YYY</tt> (obviously this should not be used as a stand-alone detection criterion, as files re-saved with other trackers will still use these filenames).

=== ChibiTracker ===

<tt>Cwt/v</tt> and <tt>Cmwt</tt> are both <tt>0214</tt>, <tt>reserved</tt> reads <tt>CHBI</tt>.

Further interesting criteria: Sample data is stored directly after header. All sample and instrument filenames read <tt>-DEPRECATED-</tt> (obviously this should not be used as a stand-alone detection criterion, as files re-saved with other trackers will still use these filenames). ChibiTracker also uses a line feed character (<tt>0A</tt> or <tt>\n</tt>) instead of a carriage return (<tt>0D</tt> or <tt>\r</tt>) in the song message.

=== ModPlug Tracker ===

* '''ModPlug Tracker 1.0 pre-alpha 4 (and possibly earlier) - 1.0 alpha 4''': <tt>Cwt/v</tt> is <tt>0202</tt>, <tt>Cmwt</tt> is <tt>0200</tt>, <tt>reserved</tt> is <tt>0</tt>, row highlights are both 0. These attributes alone are not enough to fingerprint these ModPlug Tracker versions, but luckily it also stores the remaining data in a very peculiar order: patterns first, then instrument headers, and then interleaves sample headers and their corresponding sample data. These versions also do not optimize empty 64-row patterns with a 0 parapointer, so they can be identified by checking if the first pattern parapointer is not 0 and less than the first sample parapointer.
* '''ModPlug Tracker 1.0 alpha 5''': <tt>Cwt/v</tt> is <tt>0214</tt>, <tt>Cmwt</tt> is <tt>0200</tt>, <tt>reserved</tt> is <tt>0</tt>. Pattern highlights and edit history flags are not set. Instruments are 560 bytes apart.
* '''ModPlug Tracker 1.0 alpha 6 / beta 1 / beta 2''': <tt>Cwt/v</tt> is <tt>0214</tt>, <tt>Cmwt</tt> is <tt>0200</tt>, <tt>reserved</tt> is <tt>0</tt>. Pattern highlights and edit history flags are set. Instruments are 560 bytes apart up to and including beta 1, in beta 2 they are 557 bytes apart.
* '''ModPlug Tracker 1.0 beta 3.2 - 1.09 build 66 (possibly up to build 89)''': <tt>Cwt/v</tt> is <tt>0214</tt>, <tt>Cmwt</tt> is <tt>0202</tt>, <tt>reserved</tt> is <tt>0</tt>. Instruments are 557 bytes apart.
* Newer versions of '''ModPlug Tracker''', '''OpenMPT 1.17 in compatible mode''': <tt>Cwt/v</tt> is <tt>0217</tt>, <tt>Cmwt</tt> is <tt>0200</tt>, <tt>reserved</tt> is <tt>0</tt>. If there are any instruments in the file, the instrument <tt>TrkVers</tt> field is <tt>0211</tt> for ModPlug Tracker and <tt>0220</tt> for OpenMPT. ModPlug Tracker writes <tt>FF</tt> for unused channels in the panning map, OpenMPT never does this. When an IT file uses all 64 channels (so the panning map cannot be used for distinction), the presence of ModPlug extensions (channel names, plugin chunks, etc.) can help telling MPT 1.16 and OpenMPT 1.17 compatibility export apart. The latter also does not save a final "---" order list item, while MPT 1.16 does.

=== OpenMPT ===

* OpenMPT 1.17.02.20 to OpenMPT 1.17.02.25 wrote the value <tt>0300</tt> in both the <tt>Cwt/v</tt> and <tt>Cmwt</tt> fields.
* OpenMPT 1.17.02.26 to OpenMPT 1.18 wrote the value <tt>0888</tt> in both the <tt>Cwt/v</tt> and <tt>Cmwt</tt> fields.
* Later versions of OpenMPT use the tracker ID provided above. In that case, the <tt>reserved</tt> field reads <tt>OMPT</tt> if the file was saved in normal mode, and is <tt>0</tt> (or the lower two bytes of version information starting from OpenMPT 1.29.10.00) if it was saved in compatible mode.

=== OpenSPC conversions ===

OpenSPC is a tool to convert SNES music from the SPC format to the IT format. If all the following conditions are true, you can be fairly sure that a module was written with OpenSPC:
* <tt>Cwt/v</tt> is <tt>0214</tt>.
* <tt>Cmwt</tt> is <tt>0200</tt>.
* <tt>Flags</tt> is <tt>09</tt> (Linear Slides, Stereo Playback).
* <tt>Special</tt> is <tt>0</tt>.
* Both pattern highlight values are <tt>00</tt>.
* No instruments are used.
* <tt>PatNum</tt> + 1 == <tt>OrdNum</tt>.
* Global volume is 128 decimal.
* Master volume is 100 decimal.
* Initial Speed is 1.
* Pan Separation is 128 decimal.
* Pitch wheel depth is 0.
* There is no song message, i.e. message length and offset are 0.
* <tt>reserved</tt> is 0.

Earlier versions of spc2it (before commit d3d1b524032f668be8ee20d25339e1c635fb9bcf) will be mis-identified as OpenSPC, as the tool closely follows the way its predecessor writes out IT files.

=== Unknown XM to IT conversion tool ===

There is a currently unknown XM to IT conversion tool which can be identified easily by the fact that it writes unsigned samples (which was the default only until Impulse Tracker 2.01). However, only sample slots with actual sample data should be considered for this test, as re-saving such a file in Impulse Tracker will not reset the unsigned flag for empty slots. If the following conditions are true, you can be fairly sure that a module was written with the unknown converter:
* <tt>Cwt/v</tt> is <tt>0204</tt>.
* <tt>Cmwt</tt> is <tt>0200</tt>.
* <tt>Flags</tt>: Stereo Playback, Instrument Mode, Old Effects are always set, Linear Slides are optional.
* <tt>Special</tt> is <tt>0</tt>.
* Both pattern highlight values are <tt>0</tt>.
* Global volume is 128 decimal.
* Master volume is 48 decimal.
* Pan Separation is 128 decimal.
* Pitch wheel depth is 0.
* There is no song message, i.e. message length and offset are 0.
* <tt>reserved</tt> is 0.
* Song title is no longer than 20 characters.
* All channels are panned centre (32) or muted, and their volume is 64 decimal.

To be extra sure, you can check all of these properties, but just checking <tt>Cwt/v</tt>, <tt>Cmwt</tt> and unsigned sample data is probably enough.

=== UNMO3 ===

UNMO3 is a tool to convert an MO3-compressed module file back into its original format.

In IT files created with UNMO3, the following are always true:

* <tt>Cwt/v</tt> and <tt>Cmwt</tt> are <tt>0214</tt>
* <tt>reserved</tt> is <tt>0</tt>
* <tt>pwd</tt> is 0
* Both row highlights are 0
* Flags: Use MIDI Pitch Controller (bit 6) and Request embedded MIDI configuration (bit 7) are never set

This partially overlaps with Impulse Tracker 2.14 and CheeseTracker fingerprints, however:
* CheeseTracker should write non-zero row highlights, even when resaving an UNMO3-ed file.
* It is highly unlikely that Impulse Tracker 2.14 writes a <tt>reserved</tt> value of <tt>0</tt>. If it writes zero row highlights, the row highlight <tt>special</tt> flag is set.
* Impulse Tracker 2.14 never writes an empty edit history (see below).
* CheeseTracker always uses instrument mode.

Some older versions of UNMO3 write out IT files that are malformed in some way or another, but it is easy to detect and work around. Some UNMO3-ed IT files are floating around in the wild, so it may be worthwile to implement those work-arounds:

==== Special flags prior UNMO3 2.4.0.2 ====

* UNMO3 2.4 (released in 2008) and older sets the <tt>special</tt> flag bits 1 (edit history) and 2 (row highlights) whenever bit 3 (MIDI macros) is set as well.
* UNMO3 2.4.0.1 (January 2011) always sets the <tt>special</tt> flag bit 1 (edit history), but the behaviour for bit 2 (row highlights) remains as in previous versions.
* UNMO3 2.4.0.2 (July 2011) never sets the row highlights flag.

==== Sample mode prior to UNMO3 2.4.0.1 ====

UNMO3 2.4 and older reserves space for the instrument parapointers (as many as there are samples) even when the IT file is in sample mode. This can be detected by the fact that 4 * <tt>SmpNum</tt> zero bytes follow after the pattern parapointers. These bytes need to be skipped in order to be able to read MIDI macros and ModPlug plugin settings which may potentially follow.

UNMO3 2.4.0.1 fixes this problem.

==== Edit History prior to UNMO3 2.4.0.1 ====

As mentioned above, UNMO3 older than version 2.4.0.1 may or may not set the edit history flag, but they always write two edit history length bytes (zeroes) in the file anyway. Keep this in mind, as MIDI Macros and ModPlug plugin settings will not load properly if you don’t.

* '''Edit history flag is set''': Nothing needs to be done. We can still use this for identifying UNMO3-saved IT files, because Impulse Tracker never writes an edit history of length 0.
* '''Edit history flag is not set''': This is the troublesome case due to MIDI macros and plugin settings. However, a reliable way to detect such malformed IT files would be to try to read the edit history length if all of the above detection criteria for UNMO3 are fulfilled. For those old UNMO3 versions, you should read two zero bytes. If that is the case, it means that the first MIDI macro would be empty (if MIDI macros are embedded) or the first plugin chunk ID starts with two zero bytes (impossible). Since UNMO3 writes out default values for the nine global MIDI macros, the first MIDI macro would have to start with “FF” (MIDI Start) and not be empty, so it is clear that the two zero bytes belong to the (empty) edit history.

Later version of UNMO3 set the correct header flag for the edit history and write the two zero length bytes.

== Special Header Flags ==

The following "Special" flags are not documented:

* Bit 1 (<tt>02</tt>): If set, edit history information (see [[#Edit History|below]]) is present.
* Bit 2 (<tt>04</tt>): If set, the row highlights (at offset <tt>1E</tt> - <tt>1F</tt>) should be read. If not set, they should be ignored.

== Edit History ==

It is little known that Impulse Tracker 2.08 and later keep track of when an IT file is opened and how long it is left open.
The edit history can be found directly after the IT header and before the possibly present MIDI macro configuration.

A 16-Bit integer <tt>num</tt> tells how many edit history blocks are present. Every block is 8 bytes long, so the 16-bit integer is followed by <tt>8 * num</tt> bytes of edit history information.

Each history block consists of a 16-Bit FAT date, a 16-Bit FAT time and a 32-Bit DOS timer, which contains the time how long the file was open in the editor, in 1/18.2th seconds.
Information on how to decode the FAT date and time stamps can be found on the [https://msdn.microsoft.com/en-us/library/windows/desktop/ms724247%28v=vs.85%29.aspx MSDN].

Note: Many programs don’t write an edit history, but they set the edit history flag in the header and write the two zero bytes for the history length. Many of them also ignore the edit history flag when loading files and always read the two <tt>num</tt> num bytes (ignoring the special flag), so if you want to write out an IT file that does not have an edit history and do not mind about the two extra bytes, the safest (most compatible) way is to set the edit history flag and write two zero bytes for <tt>num</tt>.

Also note that none of this is really relevant if you are sure that you never write out the MIDI macro configuration or ModPlug extensions, since these are the only two things that could normally follow the edit history. So if you have no MIDI macros and no ModPlug extensions, it is always safe to not set the special flag and not write the two extra bytes.

== Edit Timer ==

Before the addition of the full Edit History, a simple Edit Timer was stored in the <tt>reserved</tt> field of the file header. Starting from Impulse Tracker 2.07, this field contains the total edit time as a 32-Bit DOS timer (same resolution as in the Edit History). Starting from Impulse Tracker 2.08, the timer is encrypted. To decrypt:

editTime = editTime XOR 'ITRK'
editTime = editTime RoR 7
editTime = -editTime
editTime = editTime RoL 4
editTime = editTime XOR 'JTHL'

== Proposed way to store compressed stereo samples ==

Since Impulse Tracker itself does not support stereo samples, a common way of how to decode compressed stereo samples had to be found - After all, it is possible to just treat them as one continuous stream (not stopping the encoding / decoding process after the end of the left channel), or to treat them as two separate, consecutive streams. XMPlay was probably the only player that could handle compressed stereo samples even before there was a single implementation for saving compressed stereo samples. GreaseMonkey has decided to follow [https://www.un4seen.com/forum/?topic=12448.msg86479#msg86479 XMPlay's way] of decoding compressed stereo samples by treating them as two streams of the same length, so OpenMPT follows this example. If you intend to add IT sample compression support in your application, you should do the same to ensure compatibility across as many applications as possible.

== OpenMPT Hacks ==

For a list of all the file format hacks that ModPlug Tracker / OpenMPT added to the IT format over the years, see the [[Development: OpenMPT Format Extensions|OpenMPT Format Extensions]] article.

[[Category:Development|Formats/IT]]
[[Category:IT Format|Format Specification]]

Development: Formats/S3M

2024-11-09T05:04:46Z

CS127: /* Tracker IDs */ fix typo

General information concerning the S3M file format. Variable names and hexadecimal numbers (in little-endian formats) are indicated by a <tt>monospace font</tt>.

== Tracker IDs ==

The S3M header contains a field, <tt>Cwt/v</tt>, which is used to identify the application that was used to create the file.
The following custom tracker IDs (read as little-endian hexadecimal numbers) are known to be found in the <tt>Cwt/v</tt> field:

* <tt>0208</tt> - Found in some tracks by Yerzmyey, appears to be from a tracker called Akord (Polish localized version of a tracker called Squeak Tracker)
* <tt>1xyy</tt> - Scream Tracker x.yy - Many other trackers, like ModPlug Tracker, disguise as Scream Tracker 3.20, so this is not a reliable way to tell if a file was really made with Scream Tracker, [[#Detecting trackers disguising as Scream Tracker|see below]].
* <tt>2xyy</tt> - Imago Orpheus x.yy
* <tt>2013</tt> - PlayerPRO on little-endian platforms
* <tt>3xyy</tt> - Impulse Tracker x.yy. Impulse Tracker v1.03 (and possibly v1.02) writes <tt>3320</tt>. For even older Impulse Tracker versions, see [[#Early Impulse Tracker versions|below]].
* <tt>4xyy</tt> - Schism Tracker x.yy up to Schism Tracker v0.50, later versions encode a timestamp in the version number - see Schism Tracker’s <tt>[https://github.com/schismtracker/schismtracker/blob/master/schism/version.c version.c]</tt> or OpenMPT’s <tt>[https://source.openmpt.org/browse/openmpt/trunk/OpenMPT/soundlib/Load_it.cpp Load_it.cpp]</tt>.
* <tt>5xyy</tt> - OpenMPT x.yy - lower two bytes of version number are stored in the two reserved bytes at offset 54 starting from OpenMPT 1.29.10.00.
* <tt>5xyy</tt> - Liquid Tracker x.yy - OpenMPT unfortunately shares this tracker ID with Liquid Tracker. Only one S3M file made with Liquid Tracker has been found in the wild. The two programs can be told apart, though: Either by the fact that the full OpenMPT version info is present, or for older OpenMPT versions by checking the ultraclick value (Liquid Tracker writes an ultraclick value of 16, while OpenMPT versions before the addition of the full version information wrote an ultraclick value of 8. Shortly after the full version information was added, the ultraclick value was changed to 16).
* <tt>57yy</tt> - NESMusa 7.yy
* <tt>5447</tt> - Graoumf Tracker (appears as "GT" magic bytes on disk)
* <tt>6xyy</tt> - BeRoTracker x.yy
* <tt>7xyy</tt> - CreamTracker x.yy
* <tt>CA00</tt> - Camoto / libgamemusic

'''Note''': BeRoTracker used the ID <tt>4100</tt> since 2004, but has switched to using the <tt>6xyy</tt> scheme in 2012. Luckily, this version is not used by Schism Tracker, so it is still possible to tell the two trackers apart.

Are you a tracker developer and your tracker can save S3M files? Please add your Tracker ID to this list!

== Detecting trackers disguising as Scream Tracker ==

Some trackers disguise as Scream Tracker 3, but there are ways to uncover this disguise:

=== ModPlug Tracker ===

ModPlug Tracker and OpenMPT up to version 1.17.03.01 identifies as Scream Tracker 3.20 in the <tt>Cwt/v</tt> field, but it puts zeroes for the <tt>special</tt> field, only ever sets flags <tt>10</tt> (Amiga Limits) and <tt>40</tt> (Fast Volume Slides), writes multiples of 16 orders, always saves channel pannings, and writes zero into the ultraclick removal field (Scream Tracker 3 always puts either 16, 24, or 32 there).

ModPlug Tracker versions up to 1.0 alpha 5 can be identified by not setting the stereo bit on the master volume. Versions 1.0 alpha 6 up to 1.16.203 can be told apart from later versions if less than 32 channels are used: In the extended panning table, all channels have bit 5 (use panning) set, even those past the last used channel. Later versions write <tt>08</tt> (center panning, do not use) for such channels instead.

=== Early Schism Tracker versions ===

Before Schism Tracker switched to using its own tracker ID, it largely used the original ModPlug Tracker source code, so many files may me mis-identified as being made with ModPlug. However, at some point it swtiched to writing multiples of 2 orders instead of 16, so if all the other ModPlug detections are correct, but the order list length is only a multiple of 2, it was most likely Schism Tracker that wrote the file.

Note that there is an automatic conversion of Vic's soundtrack for Acme's "Paper" demo which would match these conditions as well; however that conversion writes pattern data before sample headers, which can be used to tell it apart.

=== Early Impulse Tracker versions ===

Impulse Tracker v1.01 (and potentially v1.00 and v1.02) identifies as Scream Tracker 3.20, puts zeros for the <tt>special</tt> and <tt>ultraclick</tt> fields, and sets flag 8 (zero-volume optimizations). It does not use the channel panning table, which sets it apart from real Scream Tracker 3.20.

=== Velvet Studio / PlayerPRO ===

Velvet Studio and PlayerPRO also pretend to be Scream Tracker 3.20, but write zeroes for <tt>special</tt>, <tt>ultraclick</tt>, and <tt>flags</tt>, and do '''not''' save channel pannings. Velvet Studio also writes a fairly recognizable LRRL pattern for the channels.

To tell the two trackers apart: PlayerPRO always writes a global volume of 64 and a mix volume of 48 (mono). On the other hand, Velvet Studio always writes the stereo flag.

PlayerPRO also writes an extra 16 bytes of padding between sample headers.

=== Sound Club 2 ===

Sound Club two writes "SCLUB2.0" into the 8 consecutive reserved bytes in the file header.

=== UNMO3 ===

Nowadays, the MO3 format has support for storing the original value of the <tt>Cwt/v</tt> field, so recent UNMO3 versions make use of this. When this information is not available, or if an older UNMO3 version is used, it can be identified as follows: It pretends to be Scream Tacker 3.01, <tt>special</tt> and <tt>ultraclick</tt> are 0, channel pannings are always saved (a feature not supported by Scream Tracker 3.01). The only flags it should ever write are Fast Slides and Amiga Limits. Mix volume should always indicate stereo mixing.

=== deMODifier ===

[https://worrydream.com/iigs/#demodifier deMODifier] is a converter for SoundSmith files to S3M format. It disguises as Scream Tracker 3.01, <tt>flags</tt>, <tt>special</tt> and <tt>ultraclick</tt> are 0, global volume is always 48, mix volume is 176 (48 + stereo), tempo is always 150 and no panning table is present. Sample filenames of non-empty sample slots always end in <code>.IFF</code>.

Note: This detection should only take place after it can be ruled out that the file was saved with Scream Tracker (see [[#Output driver detection]]).

=== To-S3M ===

[https://files.scene.org/view/resources/music/utils/tos3m100.zip To-S3M] is a converter for MTM modules to S3M format. It disguises as Scream Tracker 3.01, <tt>flags</tt>, <tt>special</tt> and <tt>ultraclick</tt> are 0, global volume is always 64, mix volume is 176 (48 + stereo), speed is always 6, tempo is always 125 and no panning table is present. Files with and without the stereo flag have been spotted, but ignoring that, the mix volume is always 48.

Note: This detection should only take place after it can be ruled out that the file was saved with Scream Tracker (see [[#Output driver detection]]).

=== Detecting other trackers ===

Scream Tracker 3.10 / 3.20 / 3.21 normally only writes 16, 24 or 32 in the ''ultraclick removal'' field (earlier versions write 0 there), so this could be a way to check if a file was ''not'' saved with Scream Tracker 3. However, Scream Tracker does not sanitize this field when re-saving a file made with another tracker, so even if the file was saved with Scream Tracker, a different value might still be carried over from another tracker. See the following section for more reliable fingerprinting.

== Output driver detection ==

Scream Tracker’s Gravis Ultrasound and Sound Blaster drivers differ in their interpretation of various pattern effects, which affects playback of some modules noticeably. Luckily, there is a way to tell which driver was loaded when the S3M file was last saved in Scream Tracker, which can serve as a detection heuristic: If the file was saved with the Gravis Ultrasound driver loaded, every non-empty sample header will have a unique <tt>Int:Gp</tt> value. If the file was saved with the Sound Blaster driver loaded, every non-empty sample header will have 1 in this field. Note that the first GUS sample also uses address 1, so if there is only one non-empty sample slot, GUS and SB cannot be told apart.

Note that some S3Ms saved with Scream Tracker 3.00 (<tt>cwtv</tt> = <tt>1300</tt>) have a <tt>Int:Gp</tt> value of 0 for all samples. There is probably a very early version of Scream Tracker 3.00 (probably from 1992) which does not support the Gravis Ultrasound. For higher <tt>cwtv</tt> values, the fact that all <tt>Int:Gp</tt> values are 0 can be used for detecting other trackers or tools disguising as Scream Tracker (e.g. automatic PSM to S3M conversions).

== Impulse Tracker Edit Timer ==

Impulse Tracker hides its [[Development: Formats/IT#Edit Timer|edit timer]] in the file header; there is a section of 8 reserved bytes, of which the first and last two are zero, and the four bytes in the middle contain the edit timer in the same format as in the IT format.

[[Category:Development|Formats/S3M]]
[[Category:S3M Format|Format Specification]]

Development: Formats/S3M

2024-10-30T05:46:43Z

CS127: /* Velvet Studio / PlayePRO */

General information concerning the S3M file format. Variable names and hexadecimal numbers (in little-endian formats) are indicated by a <tt>monospace font</tt>.

== Tracker IDs ==

The S3M header contains a field, <tt>Cwt/v</tt>, which is used to identify the application that was used to create the file.
The following custom tracker IDs (read as little-endian hexadecimal numbers) are known to be found in the <tt>Cwt/v</tt> field:

* <tt>0208</tt> - Found in some tracks by Yerzmyey, appears to be from a tracker called Akord (Polish localized version of a tracker called Squeak Tracker)
* <tt>1xyy</tt> - Scream Tracker x.yy - Many other trackers, like ModPlug Tracker, disguise as Scream Tracker 3.20, so this is not a reliable way to tell if a file was really made with Scream Tracker, [[#Detecting trackers disguising as Scream Tracker|see below]].
* <tt>2xyy</tt> - Imago Orpheus x.yy
* <tt>2013</tt> - PlayerPRO on little-endian platforms
* <tt>3xyy</tt> - Impulse Tracker x.yy. Impulse Tracker v1.03 (and possibly v1.02) writes <tt>3320</tt>. For even older Impulse Tracker versions, see [[#Early Impulse Tracker versions|below]].
* <tt>4xyy</tt> - Schism Tracker x.yy up to Schism Tracker v0.50, later versions encode a timestamp in the version number - see Schism Tracker’s <tt>[https://github.com/schismtracker/schismtracker/blob/master/schism/version.c version.c]</tt> or OpenMPT’s <tt>[https://source.openmpt.org/browse/openmpt/trunk/OpenMPT/soundlib/Load_it.cpp Load_it.cpp]</tt>.
* <tt>5xyy</tt> - OpenMPT x.yy - lower two bytes of version number are stored in the two reserved bytes at offset 54 starting from OpenMPT 1.29.10.00.
* <tt>5xyy</tt> - Liquid Tracker x.yy - OpenMPT unfortunately shares this tracker ID with Liquid Tracker. Only one S3M file made with Liquid Tracker has been found in the wild. The two programs can be told apart, though: Either by the fact that the full OpenMPT version info is present, or for older OpenMPT versions by checking the ultraclick value (Liquid Tracker writes an ultraclick value of 16, while OpenMPT versions before the addition of the full version information wrote an ultraclick value of 8. Shortly after the full version information was added, the ultraclick value was changed to 16).
* <tt>57yy</tt> - NESMusa 7.yy
* <tt>5447</tt> - Graoumf Tracker (appears as "GT" magic bytes on disk)
* <tt>6xyy</tt> - BeRoTracker x.yy
* <tt>7xyy</tt> - CreamTracker x.yy
* <tt>CA00</tt> - Camoto / libgamemusic

'''Note''': BeRoTracker used the ID <tt>4100</tt> since 2004, but has switched to using the <tt>6xyy</tt> scheme in 2012. Luckily, this version is not used by Schism Tracker, so it is still possible to tell the two trackers apart.

Are you a tracker developer and you tracker can save S3M files? Please add your Tracker ID to this list!

== Detecting trackers disguising as Scream Tracker ==

Some trackers disguise as Scream Tracker 3, but there are ways to uncover this disguise:

=== ModPlug Tracker ===

ModPlug Tracker and OpenMPT up to version 1.17.03.01 identifies as Scream Tracker 3.20 in the <tt>Cwt/v</tt> field, but it puts zeroes for the <tt>special</tt> field, only ever sets flags <tt>10</tt> (Amiga Limits) and <tt>40</tt> (Fast Volume Slides), writes multiples of 16 orders, always saves channel pannings, and writes zero into the ultraclick removal field (Scream Tracker 3 always puts either 16, 24, or 32 there).

ModPlug Tracker versions up to 1.0 alpha 5 can be identified by not setting the stereo bit on the master volume. Versions 1.0 alpha 6 up to 1.16.203 can be told apart from later versions if less than 32 channels are used: In the extended panning table, all channels have bit 5 (use panning) set, even those past the last used channel. Later versions write <tt>08</tt> (center panning, do not use) for such channels instead.

=== Early Schism Tracker versions ===

Before Schism Tracker switched to using its own tracker ID, it largely used the original ModPlug Tracker source code, so many files may me mis-identified as being made with ModPlug. However, at some point it swtiched to writing multiples of 2 orders instead of 16, so if all the other ModPlug detections are correct, but the order list length is only a multiple of 2, it was most likely Schism Tracker that wrote the file.

Note that there is an automatic conversion of Vic's soundtrack for Acme's "Paper" demo which would match these conditions as well; however that conversion writes pattern data before sample headers, which can be used to tell it apart.

=== Early Impulse Tracker versions ===

Impulse Tracker v1.01 (and potentially v1.00 and v1.02) identifies as Scream Tracker 3.20, puts zeros for the <tt>special</tt> and <tt>ultraclick</tt> fields, and sets flag 8 (zero-volume optimizations). It does not use the channel panning table, which sets it apart from real Scream Tracker 3.20.

=== Velvet Studio / PlayerPRO ===

Velvet Studio and PlayerPRO also pretend to be Scream Tracker 3.20, but write zeroes for <tt>special</tt>, <tt>ultraclick</tt>, and <tt>flags</tt>, and do '''not''' save channel pannings. Velvet Studio also writes a fairly recognizable LRRL pattern for the channels.

To tell the two trackers apart: PlayerPRO always writes a global volume of 64 and a mix volume of 48 (mono). On the other hand, Velvet Studio always writes the stereo flag.

PlayerPRO also writes an extra 16 bytes of padding between sample headers.

=== Sound Club 2 ===

Sound Club two writes "SCLUB2.0" into the 8 consecutive reserved bytes in the file header.

=== UNMO3 ===

Nowadays, the MO3 format has support for storing the original value of the <tt>Cwt/v</tt> field, so recent UNMO3 versions make use of this. When this information is not available, or if an older UNMO3 version is used, it can be identified as follows: It pretends to be Scream Tacker 3.01, <tt>special</tt> and <tt>ultraclick</tt> are 0, channel pannings are always saved (a feature not supported by Scream Tracker 3.01). The only flags it should ever write are Fast Slides and Amiga Limits. Mix volume should always indicate stereo mixing.

=== deMODifier ===

[https://worrydream.com/iigs/#demodifier deMODifier] is a converter for SoundSmith files to S3M format. It disguises as Scream Tracker 3.01, <tt>flags</tt>, <tt>special</tt> and <tt>ultraclick</tt> are 0, global volume is always 48, mix volume is 176 (48 + stereo), tempo is always 150 and no panning table is present. Sample filenames of non-empty sample slots always end in <code>.IFF</code>.

Note: This detection should only take place after it can be ruled out that the file was saved with Scream Tracker (see [[#Output driver detection]]).

=== To-S3M ===

[https://files.scene.org/view/resources/music/utils/tos3m100.zip To-S3M] is a converter for MTM modules to S3M format. It disguises as Scream Tracker 3.01, <tt>flags</tt>, <tt>special</tt> and <tt>ultraclick</tt> are 0, global volume is always 64, mix volume is 176 (48 + stereo), speed is always 6, tempo is always 125 and no panning table is present. Files with and without the stereo flag have been spotted, but ignoring that, the mix volume is always 48.

Note: This detection should only take place after it can be ruled out that the file was saved with Scream Tracker (see [[#Output driver detection]]).

=== Detecting other trackers ===

Scream Tracker 3.10 / 3.20 / 3.21 normally only writes 16, 24 or 32 in the ''ultraclick removal'' field (earlier versions write 0 there), so this could be a way to check if a file was ''not'' saved with Scream Tracker 3. However, Scream Tracker does not sanitize this field when re-saving a file made with another tracker, so even if the file was saved with Scream Tracker, a different value might still be carried over from another tracker. See the following section for more reliable fingerprinting.

== Output driver detection ==

Scream Tracker’s Gravis Ultrasound and Sound Blaster drivers differ in their interpretation of various pattern effects, which affects playback of some modules noticeably. Luckily, there is a way to tell which driver was loaded when the S3M file was last saved in Scream Tracker, which can serve as a detection heuristic: If the file was saved with the Gravis Ultrasound driver loaded, every non-empty sample header will have a unique <tt>Int:Gp</tt> value. If the file was saved with the Sound Blaster driver loaded, every non-empty sample header will have 1 in this field. Note that the first GUS sample also uses address 1, so if there is only one non-empty sample slot, GUS and SB cannot be told apart.

Note that some S3Ms saved with Scream Tracker 3.00 (<tt>cwtv</tt> = <tt>1300</tt>) have a <tt>Int:Gp</tt> value of 0 for all samples. There is probably a very early version of Scream Tracker 3.00 (probably from 1992) which does not support the Gravis Ultrasound. For higher <tt>cwtv</tt> values, the fact that all <tt>Int:Gp</tt> values are 0 can be used for detecting other trackers or tools disguising as Scream Tracker (e.g. automatic PSM to S3M conversions).

== Impulse Tracker Edit Timer ==

Impulse Tracker hides its [[Development: Formats/IT#Edit Timer|edit timer]] in the file header; there is a section of 8 reserved bytes, of which the first and last two are zero, and the four bytes in the middle contain the edit timer in the same format as in the IT format.

[[Category:Development|Formats/S3M]]
[[Category:S3M Format|Format Specification]]

Development: Test Cases/S3M

2024-10-30T05:35:16Z

CS127: fix typo

{{Testsuite Introduction|format=S3M|tracker=Scream Tracker 3}}

{{Testcase|format=s3m|name=AdlibZeroVolumeNote.s3m|pass=14612}}
A peculiar edge case where a note played at volume 0 causes a following note playing at volume 64 to not be heard. This was caused by the note-on bit not being reset before triggering the new note.

{{Testcase|format=s3m|name=FreqLimits.s3m|pass=1134}}
Scream Tracker 3 stops playback if the period is too low (the frequency is too high). The upper period limit is tested in [[#PeriodLimitUpper.s3m|PeriodLimitUpper.s3m]].

{{Testcase|format=s3m|name=LoopReset.s3m|pass=6127}}
Scream Tracker 3 resets the start position of the last pattern loop on every pattern transition. Each time pattern 1 is played, seven notes should be heard.

{{Testcase|format=s3m|name=NOP.s3m|pass=11602}}
Related to [[#ParamMemory.s3m|ParamMemory.s3m]], even empty effect cells with a non-zero parameter contribute to the effect memory. In this example, a major arpeggio should be heard, as there is a <tt> 37</tt> no-op effect on the first row.

{{Testcase|format=s3m|name=NoCombinedSlidesOnFirstTick-Fast.s3m|pass=21826}}
Combined slide commands Kxy and Lxy do not run on the first tick in Scream Tracker, effectively rendering fine slides with such commands inefficient. This test is with Fast Slides enabled.
As most other software supports fine slides with these commands, OpenMPT will only emulate this quirk when opening a file saved with Scream Tracker 3.

{{Testcase|format=s3m|name=NoCombinedSlidesOnFirstTick-Normal.s3m|pass=21826}}
Combined slide commands Kxy and Lxy do not run on the first tick in Scream Tracker, effectively rendering fine slides with such commands inefficient. This test is with Fast Slides disabled.
As most other software supports fine slides with these commands, OpenMPT will only emulate this quirk when opening a file saved with Scream Tracker 3.

{{Testcase|format=s3m|name=OffsetLoopWraparound.s3m|pass=12507}}
Offset commands beyond the loop end do two things in Scream Tracker 3: With a GUS, the playback wraps around to the loop start, but with a SB sample playback is stopped. This test case is for the more useful GUS behaviour. It is possible to [[Development:_Formats/S3M#Output_driver_detection|identify the sound card last used in Scream Tracker]], so this check can be applied conditionally.

{{Testcase|format=s3m|name=OffsetPastSampleEnd.s3m|pass=12761}}
Offset commands beyond the sample end of non-looped samples should stop sample playback.

{{Testcase|format=s3m|name=OxxMemory.s3m|pass=10915}}
When Scream Tracker 3 encounters a note without instrument number, it recalls the previous note′s offset. But unlike ProTracker, it does not add up offset values. When played correctly, this module should stay silent.

{{Testcase|format=s3m|name=OxxMemoryWithRetrig.s3m|pass=12762}}
Refined version of [[#OxxMemory.s3m|OxxMemory.s3m]] which tests the interaction between Oxx and Qxx with and without instrument numbers. The numbers should be heard in the same order as specified in the module title.

{{Testcase|format=s3m|name=ParamMemory.s3m|pass=1053}}
Scream Tracker 3 uses the last non-zero effect parameter as a memory for most effects: Dxy, Kxy, Lxy, Exx, Fxx, Ixy, Jxy, Qxy, Rxy, Sxy. Other effects may have their own memory or share it with another command (such as Hxy / Uxy).

{{Testcase|format=s3m|name=PatternDelays.s3m|pass=1221}}
When there are multiple row delays (SEx), only the first one is considered. The tricky part here is that the “first one” might not always be the “leftmost” one, because Scream Tracker 3 first evaluates all “left” channels (whose name starts with <tt>L</tt> in the pan table), and then all “right” channels (whose name starts with <tt>R</tt> in the pan table). This test case does not exploit this behaviour, the first row delay is always found on a left channel or there are only row delays on a right channel. I do not really know if it is worth emulating this idiosynchrasy.
Note: Scream Tracker 3 does not have tick delay (S6x) commands, but they are tested here for completeness (Impulse Tracker supports them as well, so its playback behaviour is used as a reference).

{{Testcase|format=s3m|name=PatternDelaysRetrig.s3m|pass=1221}}
Rows on which a row delay (SEx) effect is placed have multiple “first ticks”, i.e. you should set your “first tick flag” on every tick that is a multiple of the song speed (or <tt>speed + tick delay</tt> if you support tick delays in your S3M player). In this test module, the note pitch is changed multiple times per row, depending on the row delay values.
 Note: This test case broke in r3520 and was fixed again in r4895.

{{Testcase|format=s3m|name=PeriodLimit.s3m|pass=4796}}
Scream Tracker 3 limits the final output period to be at least 64, i.e. when playing a note that is too high or when sliding the period lower than 64, the output period will simply be clamped to 64. However, when reaching a period of 0 through slides, the output on the channel should be stopped. When played correctly, both channels in this module should play identically.

{{Testcase|format=s3m|name=PeriodLimitUpper.s3m|pass=15258}}
Scream Tracker 3 limits the channel period to be at most 32767, but when using the GUS driver, the frequency resolution is too low so the test module will sound very different.

{{Testcase|format=s3m|name=PortaAfterArp.s3m|pass=7525}}
A portamento up or portamento down effect immediately following an arpeggio effect should slide from the last arpeggiated note, and not from the channel frequency as it was before the arpeggio. Tone portamento is not affected. When played correctly, both channels in this module should play identically.

{{Testcase|format=s3m|name=PortaSmpChange.s3m|pass=3578}}
If the sample number next to a portamento effect differs from the previous number, the old sample should be kept, but the new sample's default volume should still be applied.

{{Testcase|format=s3m|name=RetrigAfterNoteCut.s3m|pass=12760}}
<tt>Qxy</tt> should not retrigger notes after they have been cut with <tt>^^^</tt> or <tt>SCx</tt>.

{{Testcase|format=s3m|name=RetrigSlide.s3m|pass=16646}}
<tt>Qxy</tt> should not reset the note frequency after a pitch slide.

{{Testcase|format=s3m|name=TonePortamentoWithAdlibNote.s3m|pass=17731}}
If there is a tone portamento next to an Adlib note, the tone portamento is not executed. If there is no note on the next row, the target note of the tone portamento is instantly heard on the first tick of the next row instead. Note that tone portamento without a note is not affected by this.

In Scream Tracker 3.01, this feature still works as intended. Only Scream Tracker 3.03 and later expose this weird behaviour.

{{Testcase|format=s3m|name=VibratoTypeChange.s3m|pass=6316}}
Hxx and Uxx use the same effect memory for the vibrato depth. For example, U1F followed by H00 causes the second effect to be played as H1F and vice versa. This also effectively means that Kxx will always plays “normal” vibratos, even if a fine vibrato has previously been used. When played correctly, this module should remain silent.

{{Testcase|format=s3m|name=weirdloop.s3m}}
A “broken” pattern loop. The voice should say “1” and then repeat “4 2 1 2”. Interestingly, the playback differs between various versions of Scream Tracker 3.

{{Testcase Summary}}

[[Category:Development|Test Cases/S3M]]
[[Category:S3M Format|Test Cases]]

Manual: Setup/Keyboard

2024-10-30T05:34:07Z

CS127: /* Key */ fix typo

[[Image:Settings Keyboard.png|thumb|300px|Keyboard tab of the settings dialog]]

In this page you can choose or edit keyboard shortcuts for many of the actions in OpenMPT, which are always active unless the input focus is within a textbox. OpenMPT keeps an internal default layout, but you can save your own or load others, for example from the <code>ExtraKeymaps</code> folder in OpenMPT’s application folder by clicking on the “Import Keys” button near the middle of the page. The list of the '''current''' shortcuts are kept in the <code>Keybindings.mkb</code> file in the <code>%APPDATA%\OpenMPT</code> folder (or OpenMPT’s application folder if in portable mode), but with this dialog, you can save these shortcuts in a separate file for safekeeping or sharing.
The following is a description of the various items on the page.

To view or edit keyboard shortcuts, first find the context to which the keypress would be applied by clicking on the Category field. A popup menu will open and you can choose the context to view. If you wanted, for example, to assign the <kbd>Q</kbd> key to the base octave C when inputting a note in a pattern, this keypress would be needed in the Pattern Editor for the note column. So you would select “Pattern Editor – Note Column” from the popup menu. The list of assignable note messages will be displayed in the field below it. Select the “Base octave C” entry and select it. Alternatively, if you know (parts of) the shortcut name, you can type it into the “Find” box.

Limited support for MIDI message handling is also there: Additionally to computer keyboard keys, MIDI CCs and MIDI note events may be used to trigger shortcuts. To make use of them, first [[Manual: MIDI Reference#Enabling MIDI Input|enable MIDI Input]]. Then, go to this settings dialog, focus the Key input field and send the wanted MIDI CC or note using your MIDI device.

It is possible to assign the same key combination to several shortcuts by means of the hidden setting [[Manual: Hidden Settings#.5BMisc.5D|Misc.AllowMultipleCommandsPerKey]], but a warning about this potentially unwanted situation is emitted if you are trying to re-use an existing key combination that may be conflicting.

== Shortcut List ==

=== Select Category ===
Shows the current set of functions you can assign shortcuts to. Clicking this field opens a popup menu so you can choose which set of shortcuts you wish to edit or assign.

=== Action List ===
Clicking on one of the entries selects it for key assignment. See the [[Manual: Keyboard Actions|Keyboard Actions]] table for a description of all available actions.

=== Find ===
This can be used to search for a specific shortcut in the complete shortcut list by its name. Instead of searching by name, you can also search by shortcut. Just click on the '''Key''' edit box and enter the key combination that you want to find (e.g. pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> would bring up the “Copy” shortcut when using the default configuration). Focus the edit box again to remove the search term.

== Key Setup ==

=== Key setup choice ===
This field lets you switch between the choices of key assignments for this action. If there is no key assigned, it will display <code><new></code>; otherwise, the text will read <code>"Choice ''x'' (of ''y'')"</code> where '''''x''''' is the number of the current shortcut and '''''y''''' is the total count of this action’s current key assignments. Clicking in this field will display other choices, where you can select the one to edit.

=== Key ===
Shows the key assignment for this shortcut. Double-clicking in this field (after choosing an action in the Action List) will “listen” for a new key assignment. Any keypresses or recognized MIDI events will be entered into this field and assigned to the action as a keyboard shortcut. In order to stop “listening” for new key assignments, press the Cancel button right next to it or click on another control.

=== Set / Cancel ===
You can also press the Set button to start “listening” for a new shortcut assignment. It then changes into a Cancel button, in case you want to abort the action and not assign a new key.

=== Restore ===
Clicking on this button resets the key assignments of this action to when the action was first selected.

=== On Key Down/Hold/Up ===
When any of these are checked, the action will be activated at the corresponding event of the keypress, either when the key is pressed down, when it is held down, and / or when the key is released.

=== Delete ===
Clicking on this button deletes the current key assignment. If there were other keyboard shortcuts for this action, they remain.

=== Repeat notes on hold ===
These two buttons are a shortcut for enabling or disabling the “On Key Hold” property for all '''note''' keys.

=== Chord Detect Interval ===
If you have the Pattern Editor’s Edit Step setting set to some other value than 0 and have a record group set up, OpenMPT will put all notes detected within the Chord Detect Interval on the same row, regardless of the Edit Step setting, i.e. the notes are interpreted as a chord.

=== Import Keys ===
Use this button to import an <code>.mkb</code> (OpenMPT keyboard layout) file. This allows you to use an alternate set of pre-defined keyboard assignments. In the side bar of the file dialog, a shortcut to the <code>ExtraKeymaps</code> can be found to quickly jump to the alternative keyboard layouts shipped with OpenMPT.

=== Export Keys ===
Use this button to export the current set of keyboard shortcuts to a keyboard layout file. This is helpful not only for multiple users of one OpenMPT setup, but also for testing different setups for ease of use.

=== Restore Default Configuration ===
Clicking on this button restores all keybindings to their default keys.

=== Error Log ===
Shows conflicts between key assignments. Conflicts occur when one keypress or combination keypress is already assigned to an action within the same context or a parent context. A problem may also occur when modifier keys (<kbd>Shift</kbd>, <kbd>Ctrl</kbd>, <kbd>Alt</kbd> or the <kbd>Windows</kbd> key) are expected but another key is assigned. In this case, OpenMPT will not allow the non-modifier key to be assigned.

=== Clear Log ===
Clicking this button deletes all the text in the log window.

[[Category:Manual|Setup/Keyboard]]
[[de:Handbuch: Setup/Keyboard]]

Development: OpenMPT Format Extensions

2024-08-19T02:00:16Z

CS127: /* OpenMPT Instrument Extensions */ typo fix

ModPlug Tracker and OpenMPT have extended the IT and XM formats in various ways. In general, these hacks are frowned upon, but here is some documentation on those hacks in case you want to support them in your own player. I am really sorry about all this mess, but all of this has grown historically way before I joined OpenMPT development.

Presence of these format extensions in a file does not necessarily imply that it was created with ModPlug Tracker or OpenMPT. Some of the extensions are also used e.g. by BeRoTracker.

Any numeric values are stored in little-endian format, unless noted otherwise.

Data types used in this document:
* uint8, uint16, uint32: Unsigned integers with the given bit width.
* int8, int16, int32: Signed integers with the given bit width.
* char: A single character (i.e. a byte)
* float32: Single precision IEEE float
* VarInt: A MIDI-like variable-length unsigned integer (big-endian value where the highest bit of each byte indicates if another byte follows, and the lower 7 bits containing the actual number).
* Square brackets [] denote an array of values:
** [] is a variable-length array (length is deduced from some other attribute)
** [42] denotes an array with 42 entries.

== ModPlug Song Extensions ==

The following extensions exist since the (closed-source) ModPlug Tracker days. These extensions are found in [https://en.wikipedia.org/wiki/Interchange_File_Format IFF]-like chunks, but without any padding bytes. The chunks are placed right after the header data in the IT format (i.e. after the edit history / MIDI macro block). In the XM format these chunks are placed right at the end of the file (i.e. after the sample data). At the time of writing, these chunks are always written out in the order described here, but if possible you should probably try to read them without expecting a certain order. All chunks are optional.

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint32 || Size of this chunk, excluding the header
|}

=== Chunks ===

==== text (XM only) ====

Contains the song message (CR line endings), its length is determined by the chunk size.

==== MIDI (XM only) ====

Contains the MIDI macro configuration, in the same format as in the IT format.

==== PNAM ====

Contains the pattern names. Each pattern name is 32 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The pattern names are stored continuously, i.e. there are (chunk size / 32) pattern names in the chunk, for pattern 0, pattern 1, ... pattern (chunk size / 32 - 1).

==== CNAM ====

Contains the channel names. Each channel name is 20 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The channel names are stored continuously, i.e. there are (chunk size / 20) channel names in the chunk, for channel 1, channel 2, ... channel (chunk size / 20).

==== CHFX ====

Contains the plugin assignment for each channel. For every channel, there is a 32-bit integer plugin index. 0 means no plugin, 1 is the first plugin, etc...

==== FX00, ... FX99, F100, ... F255 ====

Contains plugin information for each plugin slot. <code>FX00</code> contains the information for the first plugin slot, <code>FX99</code> for the 100th, <code>F100</code> for the 101st, etc...

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint32 || Plugin Type
<ul>
<li>VST plugins: <code>PtsV</code> (<code>0x56737450</code>)</li>
<li>DMO plugins: <code>OMXD</code> (<code>0x44584D4F</code>)</li>
<li>Internal plugins use various other IDs.</li>
</ul>
|-
| 4 || uint32 || Unique Plugin ID
|-
| 8 || uint8 || Routing Flags
<ul>
<li>0x01: Apply to master mix</li>
<li>0x02: Bypass</li>
<li>0x04: Dry mix</li>
<li>0x08: Expand mix [0%,100%] → [-100%,100%]</li>
<li>0x10: Auto-suspend on silence</li>
</ul>
|-
| 9 || uint8 || Mix mode
<ul>
<li>0: Default (<code>MIX += DRY * dryRatio + WET * wetRatio</code>)</li>
<li>1: Wet Subtract (<code>MIX += DRY - WET * wetRatio</code>)</li>
<li>2: Dry Subtract (<code>MIX += WET - DRY * dryRatio</code>)</li>
<li>3: Mix Subtract (<code>MIX -= WET - DRY * wetRatio</code>)</li>
<li>4: Middle Subtract (<code>MIX -= middle - WET * wetRatio + middle - DRY</code>)</li>
<li>5: L/R Balance (<code>MIX_L += wetRatio * (WET_L - DRY_L) + dryRatio * (DRY_R - WET_R)</code>)</li>
<li>6: Instrument (<code>MIX += DRY + WET * wetRatio</code>)</li>
</ul>
Prior to OpenMPT 1.32.00.11, instrument plugins behaved like the "Instrument" mix mode regardless of their actual mix mode (mix mode and expand mix options were not available in the GUI for instrument plugins). 
This was fixed in 1.32.00.11, and the "Instrument" mix mode was added to emulate the old behaviour for old modules.
|-
| 10 || uint8 || Gain Factor * 10 (9 = 90%, 10 = 100%, 11 = 110%, etc.). A value of 0 is equal to 10 (i.e. 100%).
|-
| 11 || uint8 || (Reserved)
|-
| 12 || uint32 || Output Routing (0 = send to master, 0x80 + x = send to plugin x)
|-
| 16 || uint32 || Shell plugin ID (0 if this is not a shell plugin)
|-
| 20 || uint8[12] || (Reserved)
|-
| 32 || char[32] || User-chosen plugin name (Windows code page)
|-
| 64 || char[64] || Library name (Original DLL name / DMO identifier). UTF-8 (max. 64 bytes) since OpenMPT 1.22.07.01, Windows code page in older versions.
|-
| 128 || uint32 || Size of plugin-specific data in bytes (parameters or opaque chunk)
|-
| 132 || uint8[] || Plugin-specific data
|}

The first four bytes of the plugin-specific data determine the type of data. If they are all 0, then the plugin parameters follow as an array of float32 values. Otherwise, plugin type specific data follows which should be treated as an opaque chunk. For example, for VST plugins that support the effGetChunk / effSetChunk opcodes, the first four bytes will be "fEvN", followed by the data to be sent to the plugin.

After the plugin information described above, more information may follow in OpenMPT modules. This information is again stored in chunks. However, there are two legacy chunks which do not have any size stored alongside the chunk identifier:

{| class="wikitable"
|-
! FOURCC !! Data Type !! Description
|-
| <code>DWRT</code> || float32 || Dry/Wet Ratio of the plugin. This chunk does not denote its size!
|-
| <code>PROG</code> || uint32 || Default plugin program (preset) to restore. This chunk does not denote its size!
|}

Any chunks that will be added in the future will have proper IFF-like chunks with a 32-bit size field.

== ModPlug Instrument Extensions (IT only) ==

To be able to address more than 256 samples in the IT format, ModPlug Tracker has an extension to store the high byte of sample indices for the instrument sample map.

By default, the last four bytes of an IT instrument (right after the pitch envelope) are unused. If they read <code>MPTX</code> or <code>XTPM</code>, 120 extra bytes follow, one for each note in the sample map. These bytes are the high byte of the sample index, i.e. they need to be multiplied by 256 and then added to the already read sample index.

== OpenMPT Extensions (General Information) ==

In the XM format, OpenMPT instrument extensions may follow the ModPlug song extensions and may in return be followed by OpenMPT song extensions.

In the IT format, OpenMPT instrument extensions may follow the sample block and may in return be followed by OpenMPT song extensions.
This is very ugly, because there might not be any samples, in which case the last thing before the extension block would be the last pattern. If there are no patterns, the last thing before the extension block would be a sample header (at least one sample header will be present even if there is no sample data – but you may even want to cover the case where there are no sample headers, for being compatible with possible future changes). So you will somehow have to keep track of the highest offset you have read into the file. If the last sample is IT-compressed, things become even more complicated: There is no way to know the compressed size of a compressed sample, so in case you want to skip sample loading, and the last sample happens to be compressed, you can do the following:
Since we know that the extended instrument and song properties start right after the last sample, and since IT-compressed samples consist of chunks with a prepended 16-bit length field, you can simply read that 16-bit number, skip this amount of bytes, then check if you can read OpenMPT's <code>XTPM</code> or <code>STPM</code> magic bytes, and if not, read the next 16-bit length, skip the bytes, etc...

In pseudo code, finding the OpenMPT extensions in an IT / MPTM file could look somewhat like this:

''offset'' = 0
''lastSampleCompressed'' = false

// In case there are no patterns and no sample data (just empty sample slots):
if(number of samples > 0):
''offset'' = last sample header pointer + sizeof(ITSampleHeader)

for all samples:
if sample is not compressed or if samples are decoded:
''lastSampleCompressed'' = false
''offset'' = max(''offset'', pointer to sample data + sample size)
else if sample is compressed and samples are not decoded:
''lastSampleCompressed'' = true
''offset'' = max(''offset'', pointer to sample data)

// In case there is no sample data:
for all patterns:
''offset'' = max(''offset'', end of pattern data)

if ''lastSampleCompressed'':
while not eof:
if next four bytes are XTPM or STPM:
''chunkID'' = next four bytes
if ''chunkID'' only contains ASCII characters (all bytes are in 32…127)
''offset'' = current position - 4; break
else
skip back 8 bytes
read uint16 value and skip as many bytes

Try reading XTPM and STPM extensions at ''offset''

The provided data types are just for orientation, i.e. the minimum recommended field size for storing the values in memory. You must expect fields to have a different size, since sometimes they do so for historic reasons. Defensive programming is your friend. Most of the FOURCCs also just make sense when read backwards, again for historic reasons. Note that some of these extensions duplicate existing functionality of the IT/XM format. In this case, the extensions take precedence over the value previous found in the file.

== OpenMPT Instrument Extensions ==

Instrument extensions start with the <code>XTPM</code> magic bytes, but there is no size indication of the total size of this block. So you have to read the following chunks and as soon as you read the <code>STPM</code> magic bytes for a chunk, you know you have read too far and can continue with reading OpenMPT Song Extensions instead.

Instrument extensions are stored in a peculiar way: There is one chunk per property, and it contains the values for all instruments at once. The layout is as follows:

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint16 || Size of this chunk's entry '''for one instrument''' (i.e. total chunk content size is this field × number of instruments)
|}

=== Chunk Contents ===

The following instrument properties exist. Some of them are redundant depending on the file type and thus not present in all files. If they are redundant, they overwrite the values that were obtained from the format-specific structures.

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..OF</code> || uint32 || IT, MPTM, XM || Fade-out
|-
| <code>...P</code> || uint32 || IT, MPTM, XM || Panning (0...256)
|-
| <code>..EV</code> || uint32 || MPTM || Number of volume envelope nodes (if ≥ 25 nodes)
|-
| <code>..EP</code> || uint32 || MPTM || Number of pan envelope nodes (if ≥ 25 nodes)
|-
| <code>.EiP</code> || uint32 || MPTM || Number of pitch envelope nodes (if ≥ 25 nodes)
|-
| <code>..BM</code> || uint16 || IT, MPTM, XM || MIDI Bank
|-
| <code>..PM</code> || uint8 || IT, MPTM, XM || MIDI Program
|-
| <code>..CM</code> || uint8 || IT, MPTM, XM || MIDI Channel
|-
| <code>.[PV</code> || uint16[] || MPTM || Volume Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EV</code> || uint8[] || MPTM || Volume Envelope Values (if ≥ 25 nodes)
|-
| <code>.[PP</code> || uint16[] || MPTM || Pan Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EP</code> || uint8[] || MPTM || Pan Envelope Values (if ≥ 25 nodes)
|-
| <code>[PiP</code> || uint16[] || MPTM || Pitch Envelope Ticks (if ≥ 25 nodes)
|-
| <code>[EiP</code> || uint8[] || MPTM || Pitch Envelope Values (if ≥ 25 nodes)
|-
| <code>.PiM</code> || uint8 || IT, MPTM, XM || Plugin, 0 = no plugin, 1 = first plugin, etc.
|-
| <code>..RV</code> || uint16 || IT, MPTM, XM || Ramping / Attack
|-
| <code>...R</code> || uint8 || IT, MPTM, XM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>..SC</code> || uint8 || IT, MPTM, XM || Cutoff Swing
|-
| <code>..SR</code> || uint8 || IT, MPTM, XM || Resonance Swing
|-
| <code>..MF</code> || uint8 || IT, MPTM, XM || Filter Mode
|-
| <code>HEVP</code> || uint8 || IT, MPTM, XM || Plugin Velocity Handling
|-
| <code>HOVP</code> || uint8 || IT, MPTM, XM || Plugin Volume Handling
|-
| <code>NREV</code> || uint8 || IT, MPTM, XM || Volume Envelope Release Node
|-
| <code>NREA</code> || uint8 || IT, MPTM, XM || Pan Envelope Release Node
|-
| <code>NREP</code> || uint8 || IT, MPTM, XM || Pitch Envelope Release Node
|-
| <code>DWPM</code> || uint8 || IT, MPTM || Pitch Wheel Depth
|-
| <code>LTTP</code> || uint16 || IT, MPTM, XM || Integer part of Pitch / Tempo Lock
|-
| <code>PTTF</code> || uint16 || MPTM || Fractional part of Pitch / Tempo Lock (0...9999)
|}

=== Legacy Extension ===

But wait, there is more! Some really old OpenMPT versions (1.17 RC1 and older, but not 1.17 RC2) do not use the instrument extensions described above. However, they also need to store the plugin reference for each instrument, which is done in another modular block following each instrument header (and possibly the <code>MPTX</code> / <code>XTPM</code> extension of that instrument header).
If this legacy extension is present, the instrument header is followed by the magic bytes <code>MSNI</code> and an uint32 containing the modular data size.

Currently there is only one chunk in this modular data block. Its FOURCC is <code>GULP</code>, has no size information and contains an uint8 for the plugin index (0 = no plugin, 1 = first plugin, etc.).

== OpenMPT Song Extensions ==

Song extensions start with the <code>STPM</code> magic bytes, but there is no size indication of the total size of this block. In an IT / XM file, these extensions are the last chunks in the file, so you can continue reading until you are out of data. In the case of MPTM files, some further MPTM-specific data follows. This data starts with the bytes "228" followed by ASCII charater 4 (not the digit), so you can keep reading the song extensions until you read this FOURCC.

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint16 || Size of this chunk, excluding the header
|}

=== Chunk Contents ===

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..TD</code> || uint32 || IT, MPTM, XM || Integer part of the default tempo (required if it is larger than 255 in IT / MPTM, but also found in legacy XM files)
|-
| <code>DTFR</code> || uint32 || MPTM || Fractional part of the default tempo (0...9999)
|-
| <code>.BPR</code> || uint32 || IT, MPTM, XM || Rows Per Beat
|-
| <code>.MPR</code> || uint32 || IT, MPTM, XM || Rows Per Measure
|-
| <code>...C</code> || uint16 || IT, MPTM || Number of channels
|-
| <code>SnhC</code> || - || IT, MPTM || If there are more than 64 channels in the IT / MTPM format, this chunk contains the default panning, volume and flags for channels 65+. They are encoded the same way as in the IT header, except that volume and panning are stored in an interleaved way (i.e. volume for channel 65, pan for channel 65, volume for channel 66, ...)
|-
| <code>..MT</code> || uint32 || IT, MPTM, XM || Tempo Mode <ul> <li>0: classic</li> <li>1: alternative</li> <li>2: modern</li> </ul>
|-
| <code>.MMP</code> || uint32 || IT, MPTM, XM || Mix Levels <ul> <li>0: Original</li> <li>1: 1.17 RC1</li> <li>2: 1.17 RC2</li> <li>3: 1.17 RC3</li> <li>4: Compatible</li> <li>5: Compatible (FT2 Pan Law)</li> </ul>
|-
| <code>.VWC</code> || uint32 || IT, MPTM, XM || OpenMPT "Created With" version (e.g. OpenMPT 1.23.45.67 = 0x01234567)
|-
| <code>VWSL</code> || uint32 || IT, MPTM, XM || OpenMPT "Last Saved With" version
|-
| <code>.APS</code> || uint32 || IT, MPTM, XM || Sample Pre-Amp
|-
| <code>VTSV</code> || uint32 || IT, MPTM, XM || Synth Pre-Amp (VSTi / OPL)
|-
| <code>.VGD</code> || uint32 || XM || Global Volume (0...256)
|-
| <code>..PR</code> || uint16 || IT, MPTM || Restart Position
|-
| <code>RSMP</code> || uint32 || MPTM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>CUES</code> || - || MPTM || Sample cue points for a single sample (only MPTM format). The first uint16 in the chunk indicates for which sample slot the cue points are meant. The rest of the chunk contains all cue points as uint32s. If this chunk is missing for a particular sample slot, OpenMPT assumes the default cue points for this slot. In this case, the i-th cue point can be computed as i × 2048.
|-
| <code>SWNG</code> || - || MPTM || Contains tempo swing factors (only MPTM format). The first uint16 in the chunk indicates the number of swing rows. The rest of the chunk contains all swing factors as uint32s. A factor of 16777216 (224) is considered to be unity, i.e. does not modify the row duration. After loading, the number of swing factors must be resized to the actual number of rows per beat (in case of malformed file) and re-normalized.
|-
| <code>.FSM</code> || - || IT, MPTM, XM || A bit field of generic compatibility flags. For modules made with OpenMPT 1.25 and older, the most important one is 0x01 (first bit set), which is IT-/XM-compatible playback mode. All other flags indicate which [[Manual: Compatible Playback#Playback Compatibility Settings|compatibility settings]] are toggled.
|-
| <code>AUTH</code> || uint8[] || IT, MPTM, XM || Song artist, as UTF-8 string
|-
| <code>AMIM</code> || - || IT, MPTM, XM || MIDI Mapping settings
|-
| <code>CCOL</code> || rgbx[] || IT, MPTM, XM || Channel colors. The chunk size divided by 4 indicates the number of channels present. Format is [R, G, B, 0] for channels that have a color assigned, or [x, x, x, non-zero] for a channel with no color.
|}

== MPTM Extensions ==

=== Detecting an MPTM file ===

There are two types of hacked IT files: In early versions of the MPTM format (used in OpenMPT 1.17.02.4x), the <code>IMPM</code> magic bytes are replaced by <code>tpm.</code>, so they are not backwards compatible. Newer MPTM files use the original magic, but use a <code>cwtv</code> value between 0889h and 0FFFh (inclusive) in the header.

In both cases, the last four bytes of the file point to the start of the MPTM extensions. If the magic bytes "228" can be found at this start position, it is a valid MPTM file.

=== 228 Extensions ===

228 Extensions have been used since OpenMPT 1.17.02.48 r192 for features that are only available in the MPTM format,
such as Custom Tunings, Multiple Sequences, and Parameter Control notes.

They are documented [[Development:_228_Extensions|here]].

=== External Samples ===

MPTM files can reference external samples. If the <code>cvt</code> value in the sample header is 80h, then the sample is external. In this case, the sample pointer does not point to actual sample data but to a filename:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || VarInt || Length of the filename
|-
| ? || char[] || Filename (UTF-8, not null-terminated)
|}

Note that only the sample waveform must be loaded, but not its metadata: Frequency, loop points, volume, panning, auto-vibrato etc. must be read from the IT file. If the sample length according to the IT header is shorter than the actual sample, the sample data must be trimmed, too.

External samples are used exactly the same way in ITI files.

=== OPL Instruments ===

MPTM files can make use of OPL instruments, just like S3M files. Unlike in S3M files, patch data is not stuffed into the sample header but stored as regular sample data. To tell OPL patches apart from regular samples, the <code>cvt</code> value in the sample header is set to 40h. Note that the check for this flag must be an equal comparison (<code>cvt == 40h</code>), not a bitwise AND, due to ModPlug's legacy ADPCM sample <code>cvt</code> type (FFh). Any combination with other <code>cvt</code> flags is also considered to be illegal.

OPL2 patches are stored in the same order as in S3M files, i.e. interleaved modulator and carrier bytes, with the last (12th) byte being unused and set to 0.

=== Order list (old) ===

If the <code>cwtv</code> is between 088Bh and 088Dh (inclusive), the order list at the start of the file is replaced by the following struct:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint16 || Version of the order list. Only version 0 is defined. Reject any other values.
|-
| 2 || uint32 || Number of items in the order list
|-
| 6 || uint32[] || The order list, as a series of uint32 values. The number of values is determined by the previous field.
|}

=== Custom Tunings (old) ===

This section is for OpenMPT versions before 1.17.02.48 r192. For newer versions, check [[Development:_228_Extensions|228 Extensions]].

Before OpenMPT 1.17.02.48 r192, the only feature that was only available in the MPTM format was Custom Tunings.
MPTM files that were made before r192 have a <code>cwtv</code> value between 0x0888 and 0x088C (inclusive).

These MPTM files contain a "Tuning Collection" chunk that contains all the custom tunings that are specific to the song (called "Tune specific tunings" in OpenMPT),
which is right after the OpenMPT song extensions.
It is then followed by a "Tuning Map" that determines which tuning each instrument should use.

A Tuning Collection could also exist separately in a <code>.TC</code> file, that can be exported/imported into an MPTM file in the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In an MPTM file, the last four bytes pointed to the start of the "Tune specific tunings" Tuning Collection,
similar to how they point to the start of 228 extensions in newer (<code>cwtv</code> > 0x088C) MPTM files.

==== Tuning Collection structure ====

The structure of a Tuning Collection is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| char[4]
| Tuning Collection beginning signature: <code>HSCT</code> (4 bytes)
|-
| int32
| Tuning Collection version: Always 1 or 2. 
|-
| uint8 or uint32
| Length of the Tuning Collection's name. 
Data type:
* uint8 if the Tuning Collection version is 2.
* uint32 if the Tuning Collection version is 1.

|-
| char[]
| Tuning Collection name. The current version of OpenMPT reads a maximum of 256 (0x100) characters. 
If the collection is in a TC file, its name is the same as what it was in OpenMPT when the TC file was exported. 
But in MPTM files, only the tune-specific tuning collection is stored, and its name is always <code>Tune specific tunings</code>.
|-
| int16
| Tuning Collection edit mask. 
A set of 16 bits that was used to specify which settings of the tunings can be changed, but is no longer used in newer versions of OpenMPT.

|-
| uint32
| Number of tunings in the collection. The current version of OpenMPT does not load custom tunings at all if the number of tunings in an MPTM file is greater than 50.
|-
| (custom structure)
| The tunings in this collection, stored right after each other. The structure of a tuning is described below.
|-
| char[4]
| Tuning Collection end signature: <code>FSCT</code> (4 bytes)
|}

==== Tuning structure ====

The structure of a Custom Tuning is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| char[8]
| Tuning beginning signature: <code>CTRTI_B.</code> (8 bytes)
|-
| int16
| Tuning version: Always 2 or 3. 
|-
| char[8]
| Tuning SFS chunk beginning signature: <code>CT<sfs>B</code> (8 bytes)
|-
| int16
| Tuning SFS chunk version: Always 3 or 4. 
|-
| uint8 or uint32
| Length of the tuning's name. 
Data type:
* uint8 if the SFS chunk version is 4.
* uint32 if the SFS chunk version is 3.

|-
| char[]
| Tuning name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|-
| int16
| Tuning edit mask. 
A set of 16 bits that was used to specify which settings of the tuning can be changed, but is no longer used in newer versions of OpenMPT.

|-
| int16
| Tuning type.
* 0: Generic
* 1: Group-geometric (originally called "Ratio-periodic")
* 3: Geometric (originally called "TET")
Newer versions of OpenMPT that use the new tuning format will convert old Geometric tunings to Group-geometric for compatibility reasons.
|-
| uint16 or uint32
| Size of the tuning's note name map. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. 
Data type:
* uint16 if the SFS chunk version is 4.
* uint32 if the SFS chunk version is 3.

|-
| (custom structure)
| The tuning's note name map. Contains the names of notes that have custom names. The structure is described in further below.
|-
| char[8]
| Tuning SFS chunk end signature: <code>CT<sfs>E</code> (8 bytes)
|-
| uint16 or uint32
| Size of the tuning's ratio table. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. This value is usually set to 256 (or 0 if the ratio table is unneeded). 
Data type:
* uint16 if the tuning version is 3.
* uint32 if the tuning version is 2.

|-
| float32[]
| The tuning's ratio table. Contains the frequency ratios for every note. If all ratios are 1, the ratio table is unneeded, so its size would be 0. 
Unlike the newer tuning format that uses 228 extensions, this table contains ratios for every note in every group, regardless of the tuning type.
|-
| uint16 or uint32
| Finetune steps. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. 
Data type:
* uint16 if the tuning version is 3.
* uint32 if the tuning version is 2.

|-
| float32[]
| An array of finetune step ratios, containing the same number of values as the finetune steps value. 
The first value is 1, and each value is r(1/finetunesteps) times the previous value, 
where r is the ratio of note 1 (the note after the middle note) to note 0 (the middle note). 
This table no longer exists in the newer tuning format that uses 228 extensions.
|-
| int16
| First note index in the ratio table. Usually set to -128. 
The current version of OpenMPT rejects values smaller than -200 and greater than 200.
|-
| int16
| Group size. 
For generic tunings, this value is 0.
|-
| float32
| Group ratio. 
For generic tunings, this value is 0.
|-
| char[8]
| Tuning end signature: <code>CTRTI_E.</code> (8 bytes)
|}

Many of the values that are stored for each tuning are redundant.
For example, the ratio table contains ratios for every note, regardless of the tuning type, even though it makes sense to
only have ratios for a single group in group-geometric tunings, and to not be stored at all in geometric tunings.
But they still have to be stored for these old versions of OpenMPT to work correctly.
However, these redundancies no longer exist in the newer tuning format that uses 228 extensions.

==== Tuning note name map structure ====

The structure of a single entry in the note name map is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| int16
| Note number.
|-
| uint8 or uint32
| Length of the note name. 
Data type:
* uint8 if the tuning's SFS chunk version is 4.
* uint32 if the tuning's SFS chunk version is 3.

|-
| char[]
| Note name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|}

This structure is stored for every note that has a custom name.

For geometric and group-geometric tunings, only the notes of a single group, where the note numbers are between 0 and groupsize-1 (inclusive).
The note names for that single group are then applied to every group (group/octave numbers are not a part of the note name).

==== Tuning Map structure ====

The structure of a tuning map is identical to that of the new 228 tuning format (documented [[Development:_228_Extensions#Tuning_Map|here]]), but with a difference if the <code>cwtv</code> value is 0x088B or older:

The number of tunings in the map and the length of the tuning names in the map are both stored as uint32 instead of uint16 and uint8 respectively.

== RIFF WAVE ==

OpenMPT uses its own <code>xtra</code> chunk in RIFF WAVE files to store some sample properties which could otherwise not be represented in the format.

Its layout is as follows:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint32 || Sample flags (0x20: Default panning is enabled)
|-
| 4 || uint16 || Default panning (0...256)
|-
| 6 || uint16 || Default volume (0...256)
|-
| 8 || uint16 || Global volume (0...64)
|-
| 10 || uint16 || (Reserved, must be 0)
|-
| 12 || uint8 || Auto-vibrato type 
|-
| 13 || uint8 || Auto-vibrato sweep
|-
| 14 || uint8 || Auto-vibrato depth
|-
| 15 || uint8 || Auto-vibrato rate
|}

Optionally, when copying a sample to the system clipboard, the sample name (32 characters, null-padded) and filename (22 characters, null-padded) follow.

== FLAC ==

Since the FLAC format has no native and standardized way to store loop information, OpenMPT follows Renoise′s way of storing loop information: FLAC supports application-defined metadata, so OpenMPT writes a metadata block with application ID <code>riff</code>. The block contains a <code>smpl</code> chunk (as defined in the [https://www.mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/RIFFNEW.pdf RIFF specification]). Similarly, extended sample properties are stored in another <code>riff</code> application block contaning the OpenMPT-specific <code>[[#RIFF WAVE|xtra]]</code> chunk, and sample cue points are stored in a <code>cue </code> chunk.

OpenMPT also reads and writes the following non-standard Vorbis comments:
* '''SAMPLERATE''': Contains the sample rate (as text) in case it would exceed the maximum sample rate supported by the FLAC format, 1,048,575 Hz (655350 Hz for older versions).
* '''LOOPSTART''': The start of the sample loop in frames. This tag is only read, not written.
* '''LOOPLENGTH''': The length of the sample loop in frames. This tag is only read, not written.

[[Category:Development|OpenMPT Format Extensions]]

Development: OpenMPT Format Extensions

2024-08-18T11:20:41Z

CS127: /* FX00, ... FX99, F100, ... F255 */

ModPlug Tracker and OpenMPT have extended the IT and XM formats in various ways. In general, these hacks are frowned upon, but here is some documentation on those hacks in case you want to support them in your own player. I am really sorry about all this mess, but all of this has grown historically way before I joined OpenMPT development.

Presence of these format extensions in a file does not necessarily imply that it was created with ModPlug Tracker or OpenMPT. Some of the extensions are also used e.g. by BeRoTracker.

Any numeric values are stored in little-endian format, unless noted otherwise.

Data types used in this document:
* uint8, uint16, uint32: Unsigned integers with the given bit width.
* int8, int16, int32: Signed integers with the given bit width.
* char: A single character (i.e. a byte)
* float32: Single precision IEEE float
* VarInt: A MIDI-like variable-length unsigned integer (big-endian value where the highest bit of each byte indicates if another byte follows, and the lower 7 bits containing the actual number).
* Square brackets [] denote an array of values:
** [] is a variable-length array (length is deduced from some other attribute)
** [42] denotes an array with 42 entries.

== ModPlug Song Extensions ==

The following extensions exist since the (closed-source) ModPlug Tracker days. These extensions are found in [https://en.wikipedia.org/wiki/Interchange_File_Format IFF]-like chunks, but without any padding bytes. The chunks are placed right after the header data in the IT format (i.e. after the edit history / MIDI macro block). In the XM format these chunks are placed right at the end of the file (i.e. after the sample data). At the time of writing, these chunks are always written out in the order described here, but if possible you should probably try to read them without expecting a certain order. All chunks are optional.

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint32 || Size of this chunk, excluding the header
|}

=== Chunks ===

==== text (XM only) ====

Contains the song message (CR line endings), its length is determined by the chunk size.

==== MIDI (XM only) ====

Contains the MIDI macro configuration, in the same format as in the IT format.

==== PNAM ====

Contains the pattern names. Each pattern name is 32 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The pattern names are stored continuously, i.e. there are (chunk size / 32) pattern names in the chunk, for pattern 0, pattern 1, ... pattern (chunk size / 32 - 1).

==== CNAM ====

Contains the channel names. Each channel name is 20 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The channel names are stored continuously, i.e. there are (chunk size / 20) channel names in the chunk, for channel 1, channel 2, ... channel (chunk size / 20).

==== CHFX ====

Contains the plugin assignment for each channel. For every channel, there is a 32-bit integer plugin index. 0 means no plugin, 1 is the first plugin, etc...

==== FX00, ... FX99, F100, ... F255 ====

Contains plugin information for each plugin slot. <code>FX00</code> contains the information for the first plugin slot, <code>FX99</code> for the 100th, <code>F100</code> for the 101st, etc...

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint32 || Plugin Type
<ul>
<li>VST plugins: <code>PtsV</code> (<code>0x56737450</code>)</li>
<li>DMO plugins: <code>OMXD</code> (<code>0x44584D4F</code>)</li>
<li>Internal plugins use various other IDs.</li>
</ul>
|-
| 4 || uint32 || Unique Plugin ID
|-
| 8 || uint8 || Routing Flags
<ul>
<li>0x01: Apply to master mix</li>
<li>0x02: Bypass</li>
<li>0x04: Dry mix</li>
<li>0x08: Expand mix [0%,100%] → [-100%,100%]</li>
<li>0x10: Auto-suspend on silence</li>
</ul>
|-
| 9 || uint8 || Mix mode
<ul>
<li>0: Default (<code>MIX += DRY * dryRatio + WET * wetRatio</code>)</li>
<li>1: Wet Subtract (<code>MIX += DRY - WET * wetRatio</code>)</li>
<li>2: Dry Subtract (<code>MIX += WET - DRY * dryRatio</code>)</li>
<li>3: Mix Subtract (<code>MIX -= WET - DRY * wetRatio</code>)</li>
<li>4: Middle Subtract (<code>MIX -= middle - WET * wetRatio + middle - DRY</code>)</li>
<li>5: L/R Balance (<code>MIX_L += wetRatio * (WET_L - DRY_L) + dryRatio * (DRY_R - WET_R)</code>)</li>
<li>6: Instrument (<code>MIX += DRY + WET * wetRatio</code>)</li>
</ul>
Prior to OpenMPT 1.32.00.11, instrument plugins behaved like the "Instrument" mix mode regardless of their actual mix mode (mix mode and expand mix options were not available in the GUI for instrument plugins). 
This was fixed in 1.32.00.11, and the "Instrument" mix mode was added to emulate the old behaviour for old modules.
|-
| 10 || uint8 || Gain Factor * 10 (9 = 90%, 10 = 100%, 11 = 110%, etc.). A value of 0 is equal to 10 (i.e. 100%).
|-
| 11 || uint8 || (Reserved)
|-
| 12 || uint32 || Output Routing (0 = send to master, 0x80 + x = send to plugin x)
|-
| 16 || uint32 || Shell plugin ID (0 if this is not a shell plugin)
|-
| 20 || uint8[12] || (Reserved)
|-
| 32 || char[32] || User-chosen plugin name (Windows code page)
|-
| 64 || char[64] || Library name (Original DLL name / DMO identifier). UTF-8 (max. 64 bytes) since OpenMPT 1.22.07.01, Windows code page in older versions.
|-
| 128 || uint32 || Size of plugin-specific data in bytes (parameters or opaque chunk)
|-
| 132 || uint8[] || Plugin-specific data
|}

The first four bytes of the plugin-specific data determine the type of data. If they are all 0, then the plugin parameters follow as an array of float32 values. Otherwise, plugin type specific data follows which should be treated as an opaque chunk. For example, for VST plugins that support the effGetChunk / effSetChunk opcodes, the first four bytes will be "fEvN", followed by the data to be sent to the plugin.

After the plugin information described above, more information may follow in OpenMPT modules. This information is again stored in chunks. However, there are two legacy chunks which do not have any size stored alongside the chunk identifier:

{| class="wikitable"
|-
! FOURCC !! Data Type !! Description
|-
| <code>DWRT</code> || float32 || Dry/Wet Ratio of the plugin. This chunk does not denote its size!
|-
| <code>PROG</code> || uint32 || Default plugin program (preset) to restore. This chunk does not denote its size!
|}

Any chunks that will be added in the future will have proper IFF-like chunks with a 32-bit size field.

== ModPlug Instrument Extensions (IT only) ==

To be able to address more than 256 samples in the IT format, ModPlug Tracker has an extension to store the high byte of sample indices for the instrument sample map.

By default, the last four bytes of an IT instrument (right after the pitch envelope) are unused. If they read <code>MPTX</code> or <code>XTPM</code>, 120 extra bytes follow, one for each note in the sample map. These bytes are the high byte of the sample index, i.e. they need to be multiplied by 256 and then added to the already read sample index.

== OpenMPT Extensions (General Information) ==

In the XM format, OpenMPT instrument extensions may follow the ModPlug song extensions and may in return be followed by OpenMPT song extensions.

In the IT format, OpenMPT instrument extensions may follow the sample block and may in return be followed by OpenMPT song extensions.
This is very ugly, because there might not be any samples, in which case the last thing before the extension block would be the last pattern. If there are no patterns, the last thing before the extension block would be a sample header (at least one sample header will be present even if there is no sample data – but you may even want to cover the case where there are no sample headers, for being compatible with possible future changes). So you will somehow have to keep track of the highest offset you have read into the file. If the last sample is IT-compressed, things become even more complicated: There is no way to know the compressed size of a compressed sample, so in case you want to skip sample loading, and the last sample happens to be compressed, you can do the following:
Since we know that the extended instrument and song properties start right after the last sample, and since IT-compressed samples consist of chunks with a prepended 16-bit length field, you can simply read that 16-bit number, skip this amount of bytes, then check if you can read OpenMPT's <code>XTPM</code> or <code>STPM</code> magic bytes, and if not, read the next 16-bit length, skip the bytes, etc...

In pseudo code, finding the OpenMPT extensions in an IT / MPTM file could look somewhat like this:

''offset'' = 0
''lastSampleCompressed'' = false

// In case there are no patterns and no sample data (just empty sample slots):
if(number of samples > 0):
''offset'' = last sample header pointer + sizeof(ITSampleHeader)

for all samples:
if sample is not compressed or if samples are decoded:
''lastSampleCompressed'' = false
''offset'' = max(''offset'', pointer to sample data + sample size)
else if sample is compressed and samples are not decoded:
''lastSampleCompressed'' = true
''offset'' = max(''offset'', pointer to sample data)

// In case there is no sample data:
for all patterns:
''offset'' = max(''offset'', end of pattern data)

if ''lastSampleCompressed'':
while not eof:
if next four bytes are XTPM or STPM:
''chunkID'' = next four bytes
if ''chunkID'' only contains ASCII characters (all bytes are in 32…127)
''offset'' = current position - 4; break
else
skip back 8 bytes
read uint16 value and skip as many bytes

Try reading XTPM and STPM extensions at ''offset''

The provided data types are just for orientation, i.e. the minimum recommended field size for storing the values in memory. You must expect fields to have a different size, since sometimes they do so for historic reasons. Defensive programming is your friend. Most of the FOURCCs also just make sense when read backwards, again for historic reasons. Note that some of these extensions duplicate existing functionality of the IT/XM format. In this case, the extensions take precedence over the value previous found in the file.

== OpenMPT Instrument Extensions ==

Instrument extensions start with the <code>XTPM</code> magic bytes, but there is no size indication of the total size of this block. So you have to read the following chunks and as soon as you read the <code>STPM</code> magic bytes for a chunk, you know you have read to far and can continue with reading OpenMPT Song Extensions instead.

Instrument extensions are stored in a peculiar way: There is one chunk per property, and it contains the values for all instruments at once. The layout is as follows:

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint16 || Size of this chunk's entry '''for one instrument''' (i.e. total chunk content size is this field × number of instruments)
|}

=== Chunk Contents ===

The following instrument properties exist. Some of them are redundant depending on the file type and thus not present in all files. If they are redundant, they overwrite the values that were obtained from the format-specific structures.

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..OF</code> || uint32 || IT, MPTM, XM || Fade-out
|-
| <code>...P</code> || uint32 || IT, MPTM, XM || Panning (0...256)
|-
| <code>..EV</code> || uint32 || MPTM || Number of volume envelope nodes (if ≥ 25 nodes)
|-
| <code>..EP</code> || uint32 || MPTM || Number of pan envelope nodes (if ≥ 25 nodes)
|-
| <code>.EiP</code> || uint32 || MPTM || Number of pitch envelope nodes (if ≥ 25 nodes)
|-
| <code>..BM</code> || uint16 || IT, MPTM, XM || MIDI Bank
|-
| <code>..PM</code> || uint8 || IT, MPTM, XM || MIDI Program
|-
| <code>..CM</code> || uint8 || IT, MPTM, XM || MIDI Channel
|-
| <code>.[PV</code> || uint16[] || MPTM || Volume Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EV</code> || uint8[] || MPTM || Volume Envelope Values (if ≥ 25 nodes)
|-
| <code>.[PP</code> || uint16[] || MPTM || Pan Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EP</code> || uint8[] || MPTM || Pan Envelope Values (if ≥ 25 nodes)
|-
| <code>[PiP</code> || uint16[] || MPTM || Pitch Envelope Ticks (if ≥ 25 nodes)
|-
| <code>[EiP</code> || uint8[] || MPTM || Pitch Envelope Values (if ≥ 25 nodes)
|-
| <code>.PiM</code> || uint8 || IT, MPTM, XM || Plugin, 0 = no plugin, 1 = first plugin, etc.
|-
| <code>..RV</code> || uint16 || IT, MPTM, XM || Ramping / Attack
|-
| <code>...R</code> || uint8 || IT, MPTM, XM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>..SC</code> || uint8 || IT, MPTM, XM || Cutoff Swing
|-
| <code>..SR</code> || uint8 || IT, MPTM, XM || Resonance Swing
|-
| <code>..MF</code> || uint8 || IT, MPTM, XM || Filter Mode
|-
| <code>HEVP</code> || uint8 || IT, MPTM, XM || Plugin Velocity Handling
|-
| <code>HOVP</code> || uint8 || IT, MPTM, XM || Plugin Volume Handling
|-
| <code>NREV</code> || uint8 || IT, MPTM, XM || Volume Envelope Release Node
|-
| <code>NREA</code> || uint8 || IT, MPTM, XM || Pan Envelope Release Node
|-
| <code>NREP</code> || uint8 || IT, MPTM, XM || Pitch Envelope Release Node
|-
| <code>DWPM</code> || uint8 || IT, MPTM || Pitch Wheel Depth
|-
| <code>LTTP</code> || uint16 || IT, MPTM, XM || Integer part of Pitch / Tempo Lock
|-
| <code>PTTF</code> || uint16 || MPTM || Fractional part of Pitch / Tempo Lock (0...9999)
|}

=== Legacy Extension ===

But wait, there is more! Some really old OpenMPT versions (1.17 RC1 and older, but not 1.17 RC2) do not use the instrument extensions described above. However, they also need to store the plugin reference for each instrument, which is done in another modular block following each instrument header (and possibly the <code>MPTX</code> / <code>XTPM</code> extension of that instrument header).
If this legacy extension is present, the instrument header is followed by the magic bytes <code>MSNI</code> and an uint32 containing the modular data size.

Currently there is only one chunk in this modular data block. Its FOURCC is <code>GULP</code>, has no size information and contains an uint8 for the plugin index (0 = no plugin, 1 = first plugin, etc.).

== OpenMPT Song Extensions ==

Song extensions start with the <code>STPM</code> magic bytes, but there is no size indication of the total size of this block. In an IT / XM file, these extensions are the last chunks in the file, so you can continue reading until you are out of data. In the case of MPTM files, some further MPTM-specific data follows. This data starts with the bytes "228" followed by ASCII charater 4 (not the digit), so you can keep reading the song extensions until you read this FOURCC.

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint16 || Size of this chunk, excluding the header
|}

=== Chunk Contents ===

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..TD</code> || uint32 || IT, MPTM, XM || Integer part of the default tempo (required if it is larger than 255 in IT / MPTM, but also found in legacy XM files)
|-
| <code>DTFR</code> || uint32 || MPTM || Fractional part of the default tempo (0...9999)
|-
| <code>.BPR</code> || uint32 || IT, MPTM, XM || Rows Per Beat
|-
| <code>.MPR</code> || uint32 || IT, MPTM, XM || Rows Per Measure
|-
| <code>...C</code> || uint16 || IT, MPTM || Number of channels
|-
| <code>SnhC</code> || - || IT, MPTM || If there are more than 64 channels in the IT / MTPM format, this chunk contains the default panning, volume and flags for channels 65+. They are encoded the same way as in the IT header, except that volume and panning are stored in an interleaved way (i.e. volume for channel 65, pan for channel 65, volume for channel 66, ...)
|-
| <code>..MT</code> || uint32 || IT, MPTM, XM || Tempo Mode <ul> <li>0: classic</li> <li>1: alternative</li> <li>2: modern</li> </ul>
|-
| <code>.MMP</code> || uint32 || IT, MPTM, XM || Mix Levels <ul> <li>0: Original</li> <li>1: 1.17 RC1</li> <li>2: 1.17 RC2</li> <li>3: 1.17 RC3</li> <li>4: Compatible</li> <li>5: Compatible (FT2 Pan Law)</li> </ul>
|-
| <code>.VWC</code> || uint32 || IT, MPTM, XM || OpenMPT "Created With" version (e.g. OpenMPT 1.23.45.67 = 0x01234567)
|-
| <code>VWSL</code> || uint32 || IT, MPTM, XM || OpenMPT "Last Saved With" version
|-
| <code>.APS</code> || uint32 || IT, MPTM, XM || Sample Pre-Amp
|-
| <code>VTSV</code> || uint32 || IT, MPTM, XM || Synth Pre-Amp (VSTi / OPL)
|-
| <code>.VGD</code> || uint32 || XM || Global Volume (0...256)
|-
| <code>..PR</code> || uint16 || IT, MPTM || Restart Position
|-
| <code>RSMP</code> || uint32 || MPTM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>CUES</code> || - || MPTM || Sample cue points for a single sample (only MPTM format). The first uint16 in the chunk indicates for which sample slot the cue points are meant. The rest of the chunk contains all cue points as uint32s. If this chunk is missing for a particular sample slot, OpenMPT assumes the default cue points for this slot. In this case, the i-th cue point can be computed as i × 2048.
|-
| <code>SWNG</code> || - || MPTM || Contains tempo swing factors (only MPTM format). The first uint16 in the chunk indicates the number of swing rows. The rest of the chunk contains all swing factors as uint32s. A factor of 16777216 (224) is considered to be unity, i.e. does not modify the row duration. After loading, the number of swing factors must be resized to the actual number of rows per beat (in case of malformed file) and re-normalized.
|-
| <code>.FSM</code> || - || IT, MPTM, XM || A bit field of generic compatibility flags. For modules made with OpenMPT 1.25 and older, the most important one is 0x01 (first bit set), which is IT-/XM-compatible playback mode. All other flags indicate which [[Manual: Compatible Playback#Playback Compatibility Settings|compatibility settings]] are toggled.
|-
| <code>AUTH</code> || uint8[] || IT, MPTM, XM || Song artist, as UTF-8 string
|-
| <code>AMIM</code> || - || IT, MPTM, XM || MIDI Mapping settings
|-
| <code>CCOL</code> || rgbx[] || IT, MPTM, XM || Channel colors. The chunk size divided by 4 indicates the number of channels present. Format is [R, G, B, 0] for channels that have a color assigned, or [x, x, x, non-zero] for a channel with no color.
|}

== MPTM Extensions ==

=== Detecting an MPTM file ===

There are two types of hacked IT files: In early versions of the MPTM format (used in OpenMPT 1.17.02.4x), the <code>IMPM</code> magic bytes are replaced by <code>tpm.</code>, so they are not backwards compatible. Newer MPTM files use the original magic, but use a <code>cwtv</code> value between 0889h and 0FFFh (inclusive) in the header.

In both cases, the last four bytes of the file point to the start of the MPTM extensions. If the magic bytes "228" can be found at this start position, it is a valid MPTM file.

=== 228 Extensions ===

228 Extensions have been used since OpenMPT 1.17.02.48 r192 for features that are only available in the MPTM format,
such as Custom Tunings, Multiple Sequences, and Parameter Control notes.

They are documented [[Development:_228_Extensions|here]].

=== External Samples ===

MPTM files can reference external samples. If the <code>cvt</code> value in the sample header is 80h, then the sample is external. In this case, the sample pointer does not point to actual sample data but to a filename:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || VarInt || Length of the filename
|-
| ? || char[] || Filename (UTF-8, not null-terminated)
|}

Note that only the sample waveform must be loaded, but not its metadata: Frequency, loop points, volume, panning, auto-vibrato etc. must be read from the IT file. If the sample length according to the IT header is shorter than the actual sample, the sample data must be trimmed, too.

External samples are used exactly the same way in ITI files.

=== OPL Instruments ===

MPTM files can make use of OPL instruments, just like S3M files. Unlike in S3M files, patch data is not stuffed into the sample header but stored as regular sample data. To tell OPL patches apart from regular samples, the <code>cvt</code> value in the sample header is set to 40h. Note that the check for this flag must be an equal comparison (<code>cvt == 40h</code>), not a bitwise AND, due to ModPlug's legacy ADPCM sample <code>cvt</code> type (FFh). Any combination with other <code>cvt</code> flags is also considered to be illegal.

OPL2 patches are stored in the same order as in S3M files, i.e. interleaved modulator and carrier bytes, with the last (12th) byte being unused and set to 0.

=== Order list (old) ===

If the <code>cwtv</code> is between 088Bh and 088Dh (inclusive), the order list at the start of the file is replaced by the following struct:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint16 || Version of the order list. Only version 0 is defined. Reject any other values.
|-
| 2 || uint32 || Number of items in the order list
|-
| 6 || uint32[] || The order list, as a series of uint32 values. The number of values is determined by the previous field.
|}

=== Custom Tunings (old) ===

This section is for OpenMPT versions before 1.17.02.48 r192. For newer versions, check [[Development:_228_Extensions|228 Extensions]].

Before OpenMPT 1.17.02.48 r192, the only feature that was only available in the MPTM format was Custom Tunings.
MPTM files that were made before r192 have a <code>cwtv</code> value between 0x0888 and 0x088C (inclusive).

These MPTM files contain a "Tuning Collection" chunk that contains all the custom tunings that are specific to the song (called "Tune specific tunings" in OpenMPT),
which is right after the OpenMPT song extensions.
It is then followed by a "Tuning Map" that determines which tuning each instrument should use.

A Tuning Collection could also exist separately in a <code>.TC</code> file, that can be exported/imported into an MPTM file in the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In an MPTM file, the last four bytes pointed to the start of the "Tune specific tunings" Tuning Collection,
similar to how they point to the start of 228 extensions in newer (<code>cwtv</code> > 0x088C) MPTM files.

==== Tuning Collection structure ====

The structure of a Tuning Collection is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| char[4]
| Tuning Collection beginning signature: <code>HSCT</code> (4 bytes)
|-
| int32
| Tuning Collection version: Always 1 or 2. 
|-
| uint8 or uint32
| Length of the Tuning Collection's name. 
Data type:
* uint8 if the Tuning Collection version is 2.
* uint32 if the Tuning Collection version is 1.

|-
| char[]
| Tuning Collection name. The current version of OpenMPT reads a maximum of 256 (0x100) characters. 
If the collection is in a TC file, its name is the same as what it was in OpenMPT when the TC file was exported. 
But in MPTM files, only the tune-specific tuning collection is stored, and its name is always <code>Tune specific tunings</code>.
|-
| int16
| Tuning Collection edit mask. 
A set of 16 bits that was used to specify which settings of the tunings can be changed, but is no longer used in newer versions of OpenMPT.

|-
| uint32
| Number of tunings in the collection. The current version of OpenMPT does not load custom tunings at all if the number of tunings in an MPTM file is greater than 50.
|-
| (custom structure)
| The tunings in this collection, stored right after each other. The structure of a tuning is described below.
|-
| char[4]
| Tuning Collection end signature: <code>FSCT</code> (4 bytes)
|}

==== Tuning structure ====

The structure of a Custom Tuning is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| char[8]
| Tuning beginning signature: <code>CTRTI_B.</code> (8 bytes)
|-
| int16
| Tuning version: Always 2 or 3. 
|-
| char[8]
| Tuning SFS chunk beginning signature: <code>CT<sfs>B</code> (8 bytes)
|-
| int16
| Tuning SFS chunk version: Always 3 or 4. 
|-
| uint8 or uint32
| Length of the tuning's name. 
Data type:
* uint8 if the SFS chunk version is 4.
* uint32 if the SFS chunk version is 3.

|-
| char[]
| Tuning name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|-
| int16
| Tuning edit mask. 
A set of 16 bits that was used to specify which settings of the tuning can be changed, but is no longer used in newer versions of OpenMPT.

|-
| int16
| Tuning type.
* 0: Generic
* 1: Group-geometric (originally called "Ratio-periodic")
* 3: Geometric (originally called "TET")
Newer versions of OpenMPT that use the new tuning format will convert old Geometric tunings to Group-geometric for compatibility reasons.
|-
| uint16 or uint32
| Size of the tuning's note name map. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. 
Data type:
* uint16 if the SFS chunk version is 4.
* uint32 if the SFS chunk version is 3.

|-
| (custom structure)
| The tuning's note name map. Contains the names of notes that have custom names. The structure is described in further below.
|-
| char[8]
| Tuning SFS chunk end signature: <code>CT<sfs>E</code> (8 bytes)
|-
| uint16 or uint32
| Size of the tuning's ratio table. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. This value is usually set to 256 (or 0 if the ratio table is unneeded). 
Data type:
* uint16 if the tuning version is 3.
* uint32 if the tuning version is 2.

|-
| float32[]
| The tuning's ratio table. Contains the frequency ratios for every note. If all ratios are 1, the ratio table is unneeded, so its size would be 0. 
Unlike the newer tuning format that uses 228 extensions, this table contains ratios for every note in every group, regardless of the tuning type.
|-
| uint16 or uint32
| Finetune steps. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. 
Data type:
* uint16 if the tuning version is 3.
* uint32 if the tuning version is 2.

|-
| float32[]
| An array of finetune step ratios, containing the same number of values as the finetune steps value. 
The first value is 1, and each value is r(1/finetunesteps) times the previous value, 
where r is the ratio of note 1 (the note after the middle note) to note 0 (the middle note). 
This table no longer exists in the newer tuning format that uses 228 extensions.
|-
| int16
| First note index in the ratio table. Usually set to -128. 
The current version of OpenMPT rejects values smaller than -200 and greater than 200.
|-
| int16
| Group size. 
For generic tunings, this value is 0.
|-
| float32
| Group ratio. 
For generic tunings, this value is 0.
|-
| char[8]
| Tuning end signature: <code>CTRTI_E.</code> (8 bytes)
|}

Many of the values that are stored for each tuning are redundant.
For example, the ratio table contains ratios for every note, regardless of the tuning type, even though it makes sense to
only have ratios for a single group in group-geometric tunings, and to not be stored at all in geometric tunings.
But they still have to be stored for these old versions of OpenMPT to work correctly.
However, these redundancies no longer exist in the newer tuning format that uses 228 extensions.

==== Tuning note name map structure ====

The structure of a single entry in the note name map is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| int16
| Note number.
|-
| uint8 or uint32
| Length of the note name. 
Data type:
* uint8 if the tuning's SFS chunk version is 4.
* uint32 if the tuning's SFS chunk version is 3.

|-
| char[]
| Note name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|}

This structure is stored for every note that has a custom name.

For geometric and group-geometric tunings, only the notes of a single group, where the note numbers are between 0 and groupsize-1 (inclusive).
The note names for that single group are then applied to every group (group/octave numbers are not a part of the note name).

==== Tuning Map structure ====

The structure of a tuning map is identical to that of the new 228 tuning format (documented [[Development:_228_Extensions#Tuning_Map|here]]), but with a difference if the <code>cwtv</code> value is 0x088B or older:

The number of tunings in the map and the length of the tuning names in the map are both stored as uint32 instead of uint16 and uint8 respectively.

== RIFF WAVE ==

OpenMPT uses its own <code>xtra</code> chunk in RIFF WAVE files to store some sample properties which could otherwise not be represented in the format.

Its layout is as follows:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint32 || Sample flags (0x20: Default panning is enabled)
|-
| 4 || uint16 || Default panning (0...256)
|-
| 6 || uint16 || Default volume (0...256)
|-
| 8 || uint16 || Global volume (0...64)
|-
| 10 || uint16 || (Reserved, must be 0)
|-
| 12 || uint8 || Auto-vibrato type 
|-
| 13 || uint8 || Auto-vibrato sweep
|-
| 14 || uint8 || Auto-vibrato depth
|-
| 15 || uint8 || Auto-vibrato rate
|}

Optionally, when copying a sample to the system clipboard, the sample name (32 characters, null-padded) and filename (22 characters, null-padded) follow.

== FLAC ==

Since the FLAC format has no native and standardized way to store loop information, OpenMPT follows Renoise′s way of storing loop information: FLAC supports application-defined metadata, so OpenMPT writes a metadata block with application ID <code>riff</code>. The block contains a <code>smpl</code> chunk (as defined in the [https://www.mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/RIFFNEW.pdf RIFF specification]). Similarly, extended sample properties are stored in another <code>riff</code> application block contaning the OpenMPT-specific <code>[[#RIFF WAVE|xtra]]</code> chunk, and sample cue points are stored in a <code>cue </code> chunk.

OpenMPT also reads and writes the following non-standard Vorbis comments:
* '''SAMPLERATE''': Contains the sample rate (as text) in case it would exceed the maximum sample rate supported by the FLAC format, 1,048,575 Hz (655350 Hz for older versions).
* '''LOOPSTART''': The start of the sample loop in frames. This tag is only read, not written.
* '''LOOPLENGTH''': The length of the sample loop in frames. This tag is only read, not written.

[[Category:Development|OpenMPT Format Extensions]]

Development: OpenMPT Format Extensions

2024-08-18T11:20:23Z

CS127: /* FX00, ... FX99, F100, ... F255 */

ModPlug Tracker and OpenMPT have extended the IT and XM formats in various ways. In general, these hacks are frowned upon, but here is some documentation on those hacks in case you want to support them in your own player. I am really sorry about all this mess, but all of this has grown historically way before I joined OpenMPT development.

Presence of these format extensions in a file does not necessarily imply that it was created with ModPlug Tracker or OpenMPT. Some of the extensions are also used e.g. by BeRoTracker.

Any numeric values are stored in little-endian format, unless noted otherwise.

Data types used in this document:
* uint8, uint16, uint32: Unsigned integers with the given bit width.
* int8, int16, int32: Signed integers with the given bit width.
* char: A single character (i.e. a byte)
* float32: Single precision IEEE float
* VarInt: A MIDI-like variable-length unsigned integer (big-endian value where the highest bit of each byte indicates if another byte follows, and the lower 7 bits containing the actual number).
* Square brackets [] denote an array of values:
** [] is a variable-length array (length is deduced from some other attribute)
** [42] denotes an array with 42 entries.

== ModPlug Song Extensions ==

The following extensions exist since the (closed-source) ModPlug Tracker days. These extensions are found in [https://en.wikipedia.org/wiki/Interchange_File_Format IFF]-like chunks, but without any padding bytes. The chunks are placed right after the header data in the IT format (i.e. after the edit history / MIDI macro block). In the XM format these chunks are placed right at the end of the file (i.e. after the sample data). At the time of writing, these chunks are always written out in the order described here, but if possible you should probably try to read them without expecting a certain order. All chunks are optional.

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint32 || Size of this chunk, excluding the header
|}

=== Chunks ===

==== text (XM only) ====

Contains the song message (CR line endings), its length is determined by the chunk size.

==== MIDI (XM only) ====

Contains the MIDI macro configuration, in the same format as in the IT format.

==== PNAM ====

Contains the pattern names. Each pattern name is 32 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The pattern names are stored continuously, i.e. there are (chunk size / 32) pattern names in the chunk, for pattern 0, pattern 1, ... pattern (chunk size / 32 - 1).

==== CNAM ====

Contains the channel names. Each channel name is 20 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The channel names are stored continuously, i.e. there are (chunk size / 20) channel names in the chunk, for channel 1, channel 2, ... channel (chunk size / 20).

==== CHFX ====

Contains the plugin assignment for each channel. For every channel, there is a 32-bit integer plugin index. 0 means no plugin, 1 is the first plugin, etc...

==== FX00, ... FX99, F100, ... F255 ====

Contains plugin information for each plugin slot. <code>FX00</code> contains the information for the first plugin slot, <code>FX99</code> for the 100th, <code>F100</code> for the 101st, etc...

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint32 || Plugin Type
<ul>
<li>VST plugins: <code>PtsV</code> (`0x56737450`)</li>
<li>DMO plugins: <code>OMXD</code> (`0x44584D4F`)</li>
<li>Internal plugins use various other IDs.</li>
</ul>
|-
| 4 || uint32 || Unique Plugin ID
|-
| 8 || uint8 || Routing Flags
<ul>
<li>0x01: Apply to master mix</li>
<li>0x02: Bypass</li>
<li>0x04: Dry mix</li>
<li>0x08: Expand mix [0%,100%] → [-100%,100%]</li>
<li>0x10: Auto-suspend on silence</li>
</ul>
|-
| 9 || uint8 || Mix mode
<ul>
<li>0: Default (<code>MIX += DRY * dryRatio + WET * wetRatio</code>)</li>
<li>1: Wet Subtract (<code>MIX += DRY - WET * wetRatio</code>)</li>
<li>2: Dry Subtract (<code>MIX += WET - DRY * dryRatio</code>)</li>
<li>3: Mix Subtract (<code>MIX -= WET - DRY * wetRatio</code>)</li>
<li>4: Middle Subtract (<code>MIX -= middle - WET * wetRatio + middle - DRY</code>)</li>
<li>5: L/R Balance (<code>MIX_L += wetRatio * (WET_L - DRY_L) + dryRatio * (DRY_R - WET_R)</code>)</li>
<li>6: Instrument (<code>MIX += DRY + WET * wetRatio</code>)</li>
</ul>
Prior to OpenMPT 1.32.00.11, instrument plugins behaved like the "Instrument" mix mode regardless of their actual mix mode (mix mode and expand mix options were not available in the GUI for instrument plugins). 
This was fixed in 1.32.00.11, and the "Instrument" mix mode was added to emulate the old behaviour for old modules.
|-
| 10 || uint8 || Gain Factor * 10 (9 = 90%, 10 = 100%, 11 = 110%, etc.). A value of 0 is equal to 10 (i.e. 100%).
|-
| 11 || uint8 || (Reserved)
|-
| 12 || uint32 || Output Routing (0 = send to master, 0x80 + x = send to plugin x)
|-
| 16 || uint32 || Shell plugin ID (0 if this is not a shell plugin)
|-
| 20 || uint8[12] || (Reserved)
|-
| 32 || char[32] || User-chosen plugin name (Windows code page)
|-
| 64 || char[64] || Library name (Original DLL name / DMO identifier). UTF-8 (max. 64 bytes) since OpenMPT 1.22.07.01, Windows code page in older versions.
|-
| 128 || uint32 || Size of plugin-specific data in bytes (parameters or opaque chunk)
|-
| 132 || uint8[] || Plugin-specific data
|}

The first four bytes of the plugin-specific data determine the type of data. If they are all 0, then the plugin parameters follow as an array of float32 values. Otherwise, plugin type specific data follows which should be treated as an opaque chunk. For example, for VST plugins that support the effGetChunk / effSetChunk opcodes, the first four bytes will be "fEvN", followed by the data to be sent to the plugin.

After the plugin information described above, more information may follow in OpenMPT modules. This information is again stored in chunks. However, there are two legacy chunks which do not have any size stored alongside the chunk identifier:

{| class="wikitable"
|-
! FOURCC !! Data Type !! Description
|-
| <code>DWRT</code> || float32 || Dry/Wet Ratio of the plugin. This chunk does not denote its size!
|-
| <code>PROG</code> || uint32 || Default plugin program (preset) to restore. This chunk does not denote its size!
|}

Any chunks that will be added in the future will have proper IFF-like chunks with a 32-bit size field.

== ModPlug Instrument Extensions (IT only) ==

To be able to address more than 256 samples in the IT format, ModPlug Tracker has an extension to store the high byte of sample indices for the instrument sample map.

By default, the last four bytes of an IT instrument (right after the pitch envelope) are unused. If they read <code>MPTX</code> or <code>XTPM</code>, 120 extra bytes follow, one for each note in the sample map. These bytes are the high byte of the sample index, i.e. they need to be multiplied by 256 and then added to the already read sample index.

== OpenMPT Extensions (General Information) ==

In the XM format, OpenMPT instrument extensions may follow the ModPlug song extensions and may in return be followed by OpenMPT song extensions.

In the IT format, OpenMPT instrument extensions may follow the sample block and may in return be followed by OpenMPT song extensions.
This is very ugly, because there might not be any samples, in which case the last thing before the extension block would be the last pattern. If there are no patterns, the last thing before the extension block would be a sample header (at least one sample header will be present even if there is no sample data – but you may even want to cover the case where there are no sample headers, for being compatible with possible future changes). So you will somehow have to keep track of the highest offset you have read into the file. If the last sample is IT-compressed, things become even more complicated: There is no way to know the compressed size of a compressed sample, so in case you want to skip sample loading, and the last sample happens to be compressed, you can do the following:
Since we know that the extended instrument and song properties start right after the last sample, and since IT-compressed samples consist of chunks with a prepended 16-bit length field, you can simply read that 16-bit number, skip this amount of bytes, then check if you can read OpenMPT's <code>XTPM</code> or <code>STPM</code> magic bytes, and if not, read the next 16-bit length, skip the bytes, etc...

In pseudo code, finding the OpenMPT extensions in an IT / MPTM file could look somewhat like this:

''offset'' = 0
''lastSampleCompressed'' = false

// In case there are no patterns and no sample data (just empty sample slots):
if(number of samples > 0):
''offset'' = last sample header pointer + sizeof(ITSampleHeader)

for all samples:
if sample is not compressed or if samples are decoded:
''lastSampleCompressed'' = false
''offset'' = max(''offset'', pointer to sample data + sample size)
else if sample is compressed and samples are not decoded:
''lastSampleCompressed'' = true
''offset'' = max(''offset'', pointer to sample data)

// In case there is no sample data:
for all patterns:
''offset'' = max(''offset'', end of pattern data)

if ''lastSampleCompressed'':
while not eof:
if next four bytes are XTPM or STPM:
''chunkID'' = next four bytes
if ''chunkID'' only contains ASCII characters (all bytes are in 32…127)
''offset'' = current position - 4; break
else
skip back 8 bytes
read uint16 value and skip as many bytes

Try reading XTPM and STPM extensions at ''offset''

The provided data types are just for orientation, i.e. the minimum recommended field size for storing the values in memory. You must expect fields to have a different size, since sometimes they do so for historic reasons. Defensive programming is your friend. Most of the FOURCCs also just make sense when read backwards, again for historic reasons. Note that some of these extensions duplicate existing functionality of the IT/XM format. In this case, the extensions take precedence over the value previous found in the file.

== OpenMPT Instrument Extensions ==

Instrument extensions start with the <code>XTPM</code> magic bytes, but there is no size indication of the total size of this block. So you have to read the following chunks and as soon as you read the <code>STPM</code> magic bytes for a chunk, you know you have read to far and can continue with reading OpenMPT Song Extensions instead.

Instrument extensions are stored in a peculiar way: There is one chunk per property, and it contains the values for all instruments at once. The layout is as follows:

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint16 || Size of this chunk's entry '''for one instrument''' (i.e. total chunk content size is this field × number of instruments)
|}

=== Chunk Contents ===

The following instrument properties exist. Some of them are redundant depending on the file type and thus not present in all files. If they are redundant, they overwrite the values that were obtained from the format-specific structures.

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..OF</code> || uint32 || IT, MPTM, XM || Fade-out
|-
| <code>...P</code> || uint32 || IT, MPTM, XM || Panning (0...256)
|-
| <code>..EV</code> || uint32 || MPTM || Number of volume envelope nodes (if ≥ 25 nodes)
|-
| <code>..EP</code> || uint32 || MPTM || Number of pan envelope nodes (if ≥ 25 nodes)
|-
| <code>.EiP</code> || uint32 || MPTM || Number of pitch envelope nodes (if ≥ 25 nodes)
|-
| <code>..BM</code> || uint16 || IT, MPTM, XM || MIDI Bank
|-
| <code>..PM</code> || uint8 || IT, MPTM, XM || MIDI Program
|-
| <code>..CM</code> || uint8 || IT, MPTM, XM || MIDI Channel
|-
| <code>.[PV</code> || uint16[] || MPTM || Volume Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EV</code> || uint8[] || MPTM || Volume Envelope Values (if ≥ 25 nodes)
|-
| <code>.[PP</code> || uint16[] || MPTM || Pan Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EP</code> || uint8[] || MPTM || Pan Envelope Values (if ≥ 25 nodes)
|-
| <code>[PiP</code> || uint16[] || MPTM || Pitch Envelope Ticks (if ≥ 25 nodes)
|-
| <code>[EiP</code> || uint8[] || MPTM || Pitch Envelope Values (if ≥ 25 nodes)
|-
| <code>.PiM</code> || uint8 || IT, MPTM, XM || Plugin, 0 = no plugin, 1 = first plugin, etc.
|-
| <code>..RV</code> || uint16 || IT, MPTM, XM || Ramping / Attack
|-
| <code>...R</code> || uint8 || IT, MPTM, XM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>..SC</code> || uint8 || IT, MPTM, XM || Cutoff Swing
|-
| <code>..SR</code> || uint8 || IT, MPTM, XM || Resonance Swing
|-
| <code>..MF</code> || uint8 || IT, MPTM, XM || Filter Mode
|-
| <code>HEVP</code> || uint8 || IT, MPTM, XM || Plugin Velocity Handling
|-
| <code>HOVP</code> || uint8 || IT, MPTM, XM || Plugin Volume Handling
|-
| <code>NREV</code> || uint8 || IT, MPTM, XM || Volume Envelope Release Node
|-
| <code>NREA</code> || uint8 || IT, MPTM, XM || Pan Envelope Release Node
|-
| <code>NREP</code> || uint8 || IT, MPTM, XM || Pitch Envelope Release Node
|-
| <code>DWPM</code> || uint8 || IT, MPTM || Pitch Wheel Depth
|-
| <code>LTTP</code> || uint16 || IT, MPTM, XM || Integer part of Pitch / Tempo Lock
|-
| <code>PTTF</code> || uint16 || MPTM || Fractional part of Pitch / Tempo Lock (0...9999)
|}

=== Legacy Extension ===

But wait, there is more! Some really old OpenMPT versions (1.17 RC1 and older, but not 1.17 RC2) do not use the instrument extensions described above. However, they also need to store the plugin reference for each instrument, which is done in another modular block following each instrument header (and possibly the <code>MPTX</code> / <code>XTPM</code> extension of that instrument header).
If this legacy extension is present, the instrument header is followed by the magic bytes <code>MSNI</code> and an uint32 containing the modular data size.

Currently there is only one chunk in this modular data block. Its FOURCC is <code>GULP</code>, has no size information and contains an uint8 for the plugin index (0 = no plugin, 1 = first plugin, etc.).

== OpenMPT Song Extensions ==

Song extensions start with the <code>STPM</code> magic bytes, but there is no size indication of the total size of this block. In an IT / XM file, these extensions are the last chunks in the file, so you can continue reading until you are out of data. In the case of MPTM files, some further MPTM-specific data follows. This data starts with the bytes "228" followed by ASCII charater 4 (not the digit), so you can keep reading the song extensions until you read this FOURCC.

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint16 || Size of this chunk, excluding the header
|}

=== Chunk Contents ===

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..TD</code> || uint32 || IT, MPTM, XM || Integer part of the default tempo (required if it is larger than 255 in IT / MPTM, but also found in legacy XM files)
|-
| <code>DTFR</code> || uint32 || MPTM || Fractional part of the default tempo (0...9999)
|-
| <code>.BPR</code> || uint32 || IT, MPTM, XM || Rows Per Beat
|-
| <code>.MPR</code> || uint32 || IT, MPTM, XM || Rows Per Measure
|-
| <code>...C</code> || uint16 || IT, MPTM || Number of channels
|-
| <code>SnhC</code> || - || IT, MPTM || If there are more than 64 channels in the IT / MTPM format, this chunk contains the default panning, volume and flags for channels 65+. They are encoded the same way as in the IT header, except that volume and panning are stored in an interleaved way (i.e. volume for channel 65, pan for channel 65, volume for channel 66, ...)
|-
| <code>..MT</code> || uint32 || IT, MPTM, XM || Tempo Mode <ul> <li>0: classic</li> <li>1: alternative</li> <li>2: modern</li> </ul>
|-
| <code>.MMP</code> || uint32 || IT, MPTM, XM || Mix Levels <ul> <li>0: Original</li> <li>1: 1.17 RC1</li> <li>2: 1.17 RC2</li> <li>3: 1.17 RC3</li> <li>4: Compatible</li> <li>5: Compatible (FT2 Pan Law)</li> </ul>
|-
| <code>.VWC</code> || uint32 || IT, MPTM, XM || OpenMPT "Created With" version (e.g. OpenMPT 1.23.45.67 = 0x01234567)
|-
| <code>VWSL</code> || uint32 || IT, MPTM, XM || OpenMPT "Last Saved With" version
|-
| <code>.APS</code> || uint32 || IT, MPTM, XM || Sample Pre-Amp
|-
| <code>VTSV</code> || uint32 || IT, MPTM, XM || Synth Pre-Amp (VSTi / OPL)
|-
| <code>.VGD</code> || uint32 || XM || Global Volume (0...256)
|-
| <code>..PR</code> || uint16 || IT, MPTM || Restart Position
|-
| <code>RSMP</code> || uint32 || MPTM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>CUES</code> || - || MPTM || Sample cue points for a single sample (only MPTM format). The first uint16 in the chunk indicates for which sample slot the cue points are meant. The rest of the chunk contains all cue points as uint32s. If this chunk is missing for a particular sample slot, OpenMPT assumes the default cue points for this slot. In this case, the i-th cue point can be computed as i × 2048.
|-
| <code>SWNG</code> || - || MPTM || Contains tempo swing factors (only MPTM format). The first uint16 in the chunk indicates the number of swing rows. The rest of the chunk contains all swing factors as uint32s. A factor of 16777216 (224) is considered to be unity, i.e. does not modify the row duration. After loading, the number of swing factors must be resized to the actual number of rows per beat (in case of malformed file) and re-normalized.
|-
| <code>.FSM</code> || - || IT, MPTM, XM || A bit field of generic compatibility flags. For modules made with OpenMPT 1.25 and older, the most important one is 0x01 (first bit set), which is IT-/XM-compatible playback mode. All other flags indicate which [[Manual: Compatible Playback#Playback Compatibility Settings|compatibility settings]] are toggled.
|-
| <code>AUTH</code> || uint8[] || IT, MPTM, XM || Song artist, as UTF-8 string
|-
| <code>AMIM</code> || - || IT, MPTM, XM || MIDI Mapping settings
|-
| <code>CCOL</code> || rgbx[] || IT, MPTM, XM || Channel colors. The chunk size divided by 4 indicates the number of channels present. Format is [R, G, B, 0] for channels that have a color assigned, or [x, x, x, non-zero] for a channel with no color.
|}

== MPTM Extensions ==

=== Detecting an MPTM file ===

There are two types of hacked IT files: In early versions of the MPTM format (used in OpenMPT 1.17.02.4x), the <code>IMPM</code> magic bytes are replaced by <code>tpm.</code>, so they are not backwards compatible. Newer MPTM files use the original magic, but use a <code>cwtv</code> value between 0889h and 0FFFh (inclusive) in the header.

In both cases, the last four bytes of the file point to the start of the MPTM extensions. If the magic bytes "228" can be found at this start position, it is a valid MPTM file.

=== 228 Extensions ===

228 Extensions have been used since OpenMPT 1.17.02.48 r192 for features that are only available in the MPTM format,
such as Custom Tunings, Multiple Sequences, and Parameter Control notes.

They are documented [[Development:_228_Extensions|here]].

=== External Samples ===

MPTM files can reference external samples. If the <code>cvt</code> value in the sample header is 80h, then the sample is external. In this case, the sample pointer does not point to actual sample data but to a filename:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || VarInt || Length of the filename
|-
| ? || char[] || Filename (UTF-8, not null-terminated)
|}

Note that only the sample waveform must be loaded, but not its metadata: Frequency, loop points, volume, panning, auto-vibrato etc. must be read from the IT file. If the sample length according to the IT header is shorter than the actual sample, the sample data must be trimmed, too.

External samples are used exactly the same way in ITI files.

=== OPL Instruments ===

MPTM files can make use of OPL instruments, just like S3M files. Unlike in S3M files, patch data is not stuffed into the sample header but stored as regular sample data. To tell OPL patches apart from regular samples, the <code>cvt</code> value in the sample header is set to 40h. Note that the check for this flag must be an equal comparison (<code>cvt == 40h</code>), not a bitwise AND, due to ModPlug's legacy ADPCM sample <code>cvt</code> type (FFh). Any combination with other <code>cvt</code> flags is also considered to be illegal.

OPL2 patches are stored in the same order as in S3M files, i.e. interleaved modulator and carrier bytes, with the last (12th) byte being unused and set to 0.

=== Order list (old) ===

If the <code>cwtv</code> is between 088Bh and 088Dh (inclusive), the order list at the start of the file is replaced by the following struct:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint16 || Version of the order list. Only version 0 is defined. Reject any other values.
|-
| 2 || uint32 || Number of items in the order list
|-
| 6 || uint32[] || The order list, as a series of uint32 values. The number of values is determined by the previous field.
|}

=== Custom Tunings (old) ===

This section is for OpenMPT versions before 1.17.02.48 r192. For newer versions, check [[Development:_228_Extensions|228 Extensions]].

Before OpenMPT 1.17.02.48 r192, the only feature that was only available in the MPTM format was Custom Tunings.
MPTM files that were made before r192 have a <code>cwtv</code> value between 0x0888 and 0x088C (inclusive).

These MPTM files contain a "Tuning Collection" chunk that contains all the custom tunings that are specific to the song (called "Tune specific tunings" in OpenMPT),
which is right after the OpenMPT song extensions.
It is then followed by a "Tuning Map" that determines which tuning each instrument should use.

A Tuning Collection could also exist separately in a <code>.TC</code> file, that can be exported/imported into an MPTM file in the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In an MPTM file, the last four bytes pointed to the start of the "Tune specific tunings" Tuning Collection,
similar to how they point to the start of 228 extensions in newer (<code>cwtv</code> > 0x088C) MPTM files.

==== Tuning Collection structure ====

The structure of a Tuning Collection is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| char[4]
| Tuning Collection beginning signature: <code>HSCT</code> (4 bytes)
|-
| int32
| Tuning Collection version: Always 1 or 2. 
|-
| uint8 or uint32
| Length of the Tuning Collection's name. 
Data type:
* uint8 if the Tuning Collection version is 2.
* uint32 if the Tuning Collection version is 1.

|-
| char[]
| Tuning Collection name. The current version of OpenMPT reads a maximum of 256 (0x100) characters. 
If the collection is in a TC file, its name is the same as what it was in OpenMPT when the TC file was exported. 
But in MPTM files, only the tune-specific tuning collection is stored, and its name is always <code>Tune specific tunings</code>.
|-
| int16
| Tuning Collection edit mask. 
A set of 16 bits that was used to specify which settings of the tunings can be changed, but is no longer used in newer versions of OpenMPT.

|-
| uint32
| Number of tunings in the collection. The current version of OpenMPT does not load custom tunings at all if the number of tunings in an MPTM file is greater than 50.
|-
| (custom structure)
| The tunings in this collection, stored right after each other. The structure of a tuning is described below.
|-
| char[4]
| Tuning Collection end signature: <code>FSCT</code> (4 bytes)
|}

==== Tuning structure ====

The structure of a Custom Tuning is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| char[8]
| Tuning beginning signature: <code>CTRTI_B.</code> (8 bytes)
|-
| int16
| Tuning version: Always 2 or 3. 
|-
| char[8]
| Tuning SFS chunk beginning signature: <code>CT<sfs>B</code> (8 bytes)
|-
| int16
| Tuning SFS chunk version: Always 3 or 4. 
|-
| uint8 or uint32
| Length of the tuning's name. 
Data type:
* uint8 if the SFS chunk version is 4.
* uint32 if the SFS chunk version is 3.

|-
| char[]
| Tuning name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|-
| int16
| Tuning edit mask. 
A set of 16 bits that was used to specify which settings of the tuning can be changed, but is no longer used in newer versions of OpenMPT.

|-
| int16
| Tuning type.
* 0: Generic
* 1: Group-geometric (originally called "Ratio-periodic")
* 3: Geometric (originally called "TET")
Newer versions of OpenMPT that use the new tuning format will convert old Geometric tunings to Group-geometric for compatibility reasons.
|-
| uint16 or uint32
| Size of the tuning's note name map. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. 
Data type:
* uint16 if the SFS chunk version is 4.
* uint32 if the SFS chunk version is 3.

|-
| (custom structure)
| The tuning's note name map. Contains the names of notes that have custom names. The structure is described in further below.
|-
| char[8]
| Tuning SFS chunk end signature: <code>CT<sfs>E</code> (8 bytes)
|-
| uint16 or uint32
| Size of the tuning's ratio table. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. This value is usually set to 256 (or 0 if the ratio table is unneeded). 
Data type:
* uint16 if the tuning version is 3.
* uint32 if the tuning version is 2.

|-
| float32[]
| The tuning's ratio table. Contains the frequency ratios for every note. If all ratios are 1, the ratio table is unneeded, so its size would be 0. 
Unlike the newer tuning format that uses 228 extensions, this table contains ratios for every note in every group, regardless of the tuning type.
|-
| uint16 or uint32
| Finetune steps. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. 
Data type:
* uint16 if the tuning version is 3.
* uint32 if the tuning version is 2.

|-
| float32[]
| An array of finetune step ratios, containing the same number of values as the finetune steps value. 
The first value is 1, and each value is r(1/finetunesteps) times the previous value, 
where r is the ratio of note 1 (the note after the middle note) to note 0 (the middle note). 
This table no longer exists in the newer tuning format that uses 228 extensions.
|-
| int16
| First note index in the ratio table. Usually set to -128. 
The current version of OpenMPT rejects values smaller than -200 and greater than 200.
|-
| int16
| Group size. 
For generic tunings, this value is 0.
|-
| float32
| Group ratio. 
For generic tunings, this value is 0.
|-
| char[8]
| Tuning end signature: <code>CTRTI_E.</code> (8 bytes)
|}

Many of the values that are stored for each tuning are redundant.
For example, the ratio table contains ratios for every note, regardless of the tuning type, even though it makes sense to
only have ratios for a single group in group-geometric tunings, and to not be stored at all in geometric tunings.
But they still have to be stored for these old versions of OpenMPT to work correctly.
However, these redundancies no longer exist in the newer tuning format that uses 228 extensions.

==== Tuning note name map structure ====

The structure of a single entry in the note name map is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| int16
| Note number.
|-
| uint8 or uint32
| Length of the note name. 
Data type:
* uint8 if the tuning's SFS chunk version is 4.
* uint32 if the tuning's SFS chunk version is 3.

|-
| char[]
| Note name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|}

This structure is stored for every note that has a custom name.

For geometric and group-geometric tunings, only the notes of a single group, where the note numbers are between 0 and groupsize-1 (inclusive).
The note names for that single group are then applied to every group (group/octave numbers are not a part of the note name).

==== Tuning Map structure ====

The structure of a tuning map is identical to that of the new 228 tuning format (documented [[Development:_228_Extensions#Tuning_Map|here]]), but with a difference if the <code>cwtv</code> value is 0x088B or older:

The number of tunings in the map and the length of the tuning names in the map are both stored as uint32 instead of uint16 and uint8 respectively.

== RIFF WAVE ==

OpenMPT uses its own <code>xtra</code> chunk in RIFF WAVE files to store some sample properties which could otherwise not be represented in the format.

Its layout is as follows:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint32 || Sample flags (0x20: Default panning is enabled)
|-
| 4 || uint16 || Default panning (0...256)
|-
| 6 || uint16 || Default volume (0...256)
|-
| 8 || uint16 || Global volume (0...64)
|-
| 10 || uint16 || (Reserved, must be 0)
|-
| 12 || uint8 || Auto-vibrato type 
|-
| 13 || uint8 || Auto-vibrato sweep
|-
| 14 || uint8 || Auto-vibrato depth
|-
| 15 || uint8 || Auto-vibrato rate
|}

Optionally, when copying a sample to the system clipboard, the sample name (32 characters, null-padded) and filename (22 characters, null-padded) follow.

== FLAC ==

Since the FLAC format has no native and standardized way to store loop information, OpenMPT follows Renoise′s way of storing loop information: FLAC supports application-defined metadata, so OpenMPT writes a metadata block with application ID <code>riff</code>. The block contains a <code>smpl</code> chunk (as defined in the [https://www.mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/RIFFNEW.pdf RIFF specification]). Similarly, extended sample properties are stored in another <code>riff</code> application block contaning the OpenMPT-specific <code>[[#RIFF WAVE|xtra]]</code> chunk, and sample cue points are stored in a <code>cue </code> chunk.

OpenMPT also reads and writes the following non-standard Vorbis comments:
* '''SAMPLERATE''': Contains the sample rate (as text) in case it would exceed the maximum sample rate supported by the FLAC format, 1,048,575 Hz (655350 Hz for older versions).
* '''LOOPSTART''': The start of the sample loop in frames. This tag is only read, not written.
* '''LOOPLENGTH''': The length of the sample loop in frames. This tag is only read, not written.

[[Category:Development|OpenMPT Format Extensions]]

Development: OpenMPT Format Extensions

2024-05-08T07:42:40Z

CS127: /* FX00, ... FX99, F100, ... F255 */

ModPlug Tracker and OpenMPT have extended the IT and XM formats in various ways. In general, these hacks are frowned upon, but here is some documentation on those hacks in case you want to support them in your own player. I am really sorry about all this mess, but all of this has grown historically way before I joined OpenMPT development.

Presence of these format extensions in a file does not necessarily imply that it was created with ModPlug Tracker or OpenMPT. Some of the extensions are also used e.g. by BeRoTracker.

Any numeric values are stored in little-endian format, unless noted otherwise.

Data types used in this document:
* uint8, uint16, uint32: Unsigned integers with the given bit width.
* int8, int16, int32: Signed integers with the given bit width.
* char: A single character (i.e. a byte)
* float32: Single precision IEEE float
* VarInt: A MIDI-like variable-length unsigned integer (big-endian value where the highest bit of each byte indicates if another byte follows, and the lower 7 bits containing the actual number).
* Square brackets [] denote an array of values:
** [] is a variable-length array (length is deduced from some other attribute)
** [42] denotes an array with 42 entries.

== ModPlug Song Extensions ==

The following extensions exist since the (closed-source) ModPlug Tracker days. These extensions are found in [https://en.wikipedia.org/wiki/Interchange_File_Format IFF]-like chunks, but without any padding bytes. The chunks are placed right after the header data in the IT format (i.e. after the edit history / MIDI macro block). In the XM format these chunks are placed right at the end of the file (i.e. after the sample data). At the time of writing, these chunks are always written out in the order described here, but if possible you should probably try to read them without expecting a certain order. All chunks are optional.

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint32 || Size of this chunk, excluding the header
|}

=== Chunks ===

==== text (XM only) ====

Contains the song message (CR line endings), its length is determined by the chunk size.

==== MIDI (XM only) ====

Contains the MIDI macro configuration, in the same format as in the IT format.

==== PNAM ====

Contains the pattern names. Each pattern name is 32 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The pattern names are stored continuously, i.e. there are (chunk size / 32) pattern names in the chunk, for pattern 0, pattern 1, ... pattern (chunk size / 32 - 1).

==== CNAM ====

Contains the channel names. Each channel name is 20 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The channel names are stored continuously, i.e. there are (chunk size / 20) channel names in the chunk, for channel 1, channel 2, ... channel (chunk size / 20).

==== CHFX ====

Contains the plugin assignment for each channel. For every channel, there is a 32-bit integer plugin index. 0 means no plugin, 1 is the first plugin, etc...

==== FX00, ... FX99, F100, ... F255 ====

Contains plugin information for each plugin slot. <code>FX00</code> contains the information for the first plugin slot, <code>FX99</code> for the 100th, <code>F100</code> for the 101st, etc...

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Plugin Type
<ul>
<li>VST plugins: <code>PtsV</code></li>
<li>DMO plugins: <code>OMXD</code></li>
<li>Internal plugins use various other IDs.</li>
</ul>
|-
| 4 || char[4] || Unique Plugin ID
|-
| 8 || uint8 || Routing Flags
<ul>
<li>0x01: Apply to master mix</li>
<li>0x02: Bypass</li>
<li>0x04: Dry mix</li>
<li>0x08: Expand mix [0%,100%] → [-100%,100%]</li>
<li>0x10: Auto-suspend on silence</li>
</ul>
|-
| 9 || uint8 || Mix mode
<ul>
<li>0: Default (<code>MIX += DRY * dryRatio + WET * wetRatio</code>)</li>
<li>1: Wet Subtract (<code>MIX += DRY - WET * wetRatio</code>)</li>
<li>2: Dry Subtract (<code>MIX += WET - DRY * dryRatio</code>)</li>
<li>3: Mix Subtract (<code>MIX -= WET - DRY * wetRatio</code>)</li>
<li>4: Middle Subtract (<code>MIX -= middle - WET * wetRatio + middle - DRY</code>)</li>
<li>5: L/R Balance (<code>MIX_L += wetRatio * (WET_L - DRY_L) + dryRatio * (DRY_R - WET_R)</code>)</li>
<li>6: Instrument (<code>MIX += DRY + WET * wetRatio</code>)</li>
</ul>
Prior to OpenMPT 1.32.00.11, instrument plugins behaved like the "Instrument" mix mode regardless of their actual mix mode (mix mode and expand mix options were not available in the GUI for instrument plugins). 
This was fixed in 1.32.00.11, and the "Instrument" mix mode was added to emulate the old behaviour for old modules.
|-
| 10 || uint8 || Gain Factor * 10 (9 = 90%, 10 = 100%, 11 = 110%, etc.). A value of 0 is equal to 10 (i.e. 100%).
|-
| 11 || uint8 || (Reserved)
|-
| 12 || uint32 || Output Routing (0 = send to master, 0x80 + x = send to plugin x)
|-
| 16 || uint8[16] || (Reserved)
|-
| 32 || char[32] || User-chosen plugin name (Windows code page)
|-
| 64 || char[64] || Library name (Original DLL name / DMO identifier). UTF-8 (max. 64 bytes) since OpenMPT 1.22.07.01, Windows code page in older versions.
|-
| 128 || uint32 || Size of plugin-specific data in bytes (parameters or opaque chunk)
|-
| 132 || uint8[] || Plugin-specific data
|}

The first four bytes of the plugin-specific data determine the type of data. If they are all 0, then the plugin parameters follow as an array of float32 values. Otherwise, plugin type specific data follows which should be treated as an opaque chunk. For example, for VST plugins that support the effGetChunk / effSetChunk opcodes, the first four bytes will be "fEvN", followed by the data to be sent to the plugin.

After the plugin information described above, more information may follow in OpenMPT modules. This information is again stored in chunks. However, there are two legacy chunks which do not have any size stored alongside the chunk identifier:

{| class="wikitable"
|-
! FOURCC !! Data Type !! Description
|-
| <code>DWRT</code> || float32 || Dry/Wet Ratio of the plugin. This chunk does not denote its size!
|-
| <code>PROG</code> || uint32 || Default plugin program (preset) to restore. This chunk does not denote its size!
|}

Any chunks that will be added in the future will have proper IFF-like chunks with a 32-bit size field.

== ModPlug Instrument Extensions (IT only) ==

To be able to address more than 256 samples in the IT format, ModPlug Tracker has an extension to store the high byte of sample indices for the instrument sample map.

By default, the last four bytes of an IT instrument (right after the pitch envelope) are unused. If they read <code>MPTX</code> or <code>XTPM</code>, 120 extra bytes follow, one for each note in the sample map. These bytes are the high byte of the sample index, i.e. they need to be multiplied by 256 and then added to the already read sample index.

== OpenMPT Extensions (General Information) ==

In the XM format, OpenMPT instrument extensions may follow the ModPlug song extensions and may in return be followed by OpenMPT song extensions.

In the IT format, OpenMPT instrument extensions may follow the sample block and may in return be followed by OpenMPT song extensions.
This is very ugly, because there might not be any samples, in which case the last thing before the extension block would be the last pattern. If there are no patterns, the last thing before the extension block would be a sample header (at least one sample header will be present even if there is no sample data – but you may even want to cover the case where there are no sample headers, for being compatible with possible future changes). So you will somehow have to keep track of the highest offset you have read into the file. If the last sample is IT-compressed, things become even more complicated: There is no way to know the compressed size of a compressed sample, so in case you want to skip sample loading, and the last sample happens to be compressed, you can do the following:
Since we know that the extended instrument and song properties start right after the last sample, and since IT-compressed samples consist of chunks with a prepended 16-bit length field, you can simply read that 16-bit number, skip this amount of bytes, then check if you can read OpenMPT's <code>XTPM</code> or <code>STPM</code> magic bytes, and if not, read the next 16-bit length, skip the bytes, etc...

In pseudo code, finding the OpenMPT extensions in an IT / MPTM file could look somewhat like this:

''offset'' = 0
''lastSampleCompressed'' = false

// In case there are no patterns and no sample data (just empty sample slots):
if(number of samples > 0):
''offset'' = last sample header pointer + sizeof(ITSampleHeader)

for all samples:
if sample is not compressed or if samples are decoded:
''lastSampleCompressed'' = false
''offset'' = max(''offset'', pointer to sample data + sample size)
else if sample is compressed and samples are not decoded:
''lastSampleCompressed'' = true
''offset'' = max(''offset'', pointer to sample data)

// In case there is no sample data:
for all patterns:
''offset'' = max(''offset'', end of pattern data)

if ''lastSampleCompressed'':
while not eof:
if next four bytes are XTPM or STPM:
''chunkID'' = next four bytes
if ''chunkID'' only contains ASCII characters (all bytes are in 32…127)
''offset'' = current position - 4; break
else
skip back 8 bytes
read uint16 value and skip as many bytes

Try reading XTPM and STPM extensions at ''offset''

The provided data types are just for orientation, i.e. the minimum recommended field size for storing the values in memory. You must expect fields to have a different size, since sometimes they do so for historic reasons. Defensive programming is your friend. Most of the FOURCCs also just make sense when read backwards, again for historic reasons. Note that some of these extensions duplicate existing functionality of the IT/XM format. In this case, the extensions take precedence over the value previous found in the file.

== OpenMPT Instrument Extensions ==

Instrument extensions start with the <code>XTPM</code> magic bytes, but there is no size indication of the total size of this block. So you have to read the following chunks and as soon as you read the <code>STPM</code> magic bytes for a chunk, you know you have read to far and can continue with reading OpenMPT Song Extensions instead.

Instrument extensions are stored in a peculiar way: There is one chunk per property, and it contains the values for all instruments at once. The layout is as follows:

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint16 || Size of this chunk's entry '''for one instrument''' (i.e. total chunk content size is this field × number of instruments)
|}

=== Chunk Contents ===

The following instrument properties exist. Some of them are redundant depending on the file type and thus not present in all files. If they are redundant, they overwrite the values that were obtained from the format-specific structures.

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..OF</code> || uint32 || IT, MPTM, XM || Fade-out
|-
| <code>...P</code> || uint32 || IT, MPTM, XM || Panning (0...256)
|-
| <code>..EV</code> || uint32 || MPTM || Number of volume envelope nodes (if ≥ 25 nodes)
|-
| <code>..EP</code> || uint32 || MPTM || Number of pan envelope nodes (if ≥ 25 nodes)
|-
| <code>.EiP</code> || uint32 || MPTM || Number of pitch envelope nodes (if ≥ 25 nodes)
|-
| <code>..BM</code> || uint16 || IT, MPTM, XM || MIDI Bank
|-
| <code>..PM</code> || uint8 || IT, MPTM, XM || MIDI Program
|-
| <code>..CM</code> || uint8 || IT, MPTM, XM || MIDI Channel
|-
| <code>.[PV</code> || uint16[] || MPTM || Volume Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EV</code> || uint8[] || MPTM || Volume Envelope Values (if ≥ 25 nodes)
|-
| <code>.[PP</code> || uint16[] || MPTM || Pan Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EP</code> || uint8[] || MPTM || Pan Envelope Values (if ≥ 25 nodes)
|-
| <code>[PiP</code> || uint16[] || MPTM || Pitch Envelope Ticks (if ≥ 25 nodes)
|-
| <code>[EiP</code> || uint8[] || MPTM || Pitch Envelope Values (if ≥ 25 nodes)
|-
| <code>.PiM</code> || uint8 || IT, MPTM, XM || Plugin, 0 = no plugin, 1 = first plugin, etc.
|-
| <code>..RV</code> || uint16 || IT, MPTM, XM || Ramping / Attack
|-
| <code>...R</code> || uint8 || IT, MPTM, XM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>..SC</code> || uint8 || IT, MPTM, XM || Cutoff Swing
|-
| <code>..SR</code> || uint8 || IT, MPTM, XM || Resonance Swing
|-
| <code>..MF</code> || uint8 || IT, MPTM, XM || Filter Mode
|-
| <code>HEVP</code> || uint8 || IT, MPTM, XM || Plugin Velocity Handling
|-
| <code>HOVP</code> || uint8 || IT, MPTM, XM || Plugin Volume Handling
|-
| <code>NREV</code> || uint8 || IT, MPTM, XM || Volume Envelope Release Node
|-
| <code>NREA</code> || uint8 || IT, MPTM, XM || Pan Envelope Release Node
|-
| <code>NREP</code> || uint8 || IT, MPTM, XM || Pitch Envelope Release Node
|-
| <code>DWPM</code> || uint8 || IT, MPTM || Pitch Wheel Depth
|-
| <code>LTTP</code> || uint16 || IT, MPTM, XM || Integer part of Pitch / Tempo Lock
|-
| <code>PTTF</code> || uint16 || MPTM || Fractional part of Pitch / Tempo Lock (0...9999)
|}

=== Legacy Extension ===

But wait, there is more! Some really old OpenMPT versions (1.17 RC1 and older, but not 1.17 RC2) do not use the instrument extensions described above. However, they also need to store the plugin reference for each instrument, which is done in another modular block following each instrument header (and possibly the <code>MPTX</code> / <code>XTPM</code> extension of that instrument header).
If this legacy extension is present, the instrument header is followed by the magic bytes <code>MSNI</code> and an uint32 containing the modular data size.

Currently there is only one chunk in this modular data block. Its FOURCC is <code>GULP</code>, has no size information and contains an uint8 for the plugin index (0 = no plugin, 1 = first plugin, etc.).

== OpenMPT Song Extensions ==

Song extensions start with the <code>STPM</code> magic bytes, but there is no size indication of the total size of this block. In an IT / XM file, these extensions are the last chunks in the file, so you can continue reading until you are out of data. In the case of MPTM files, some further MPTM-specific data follows. This data starts with the bytes "228" followed by ASCII charater 4 (not the digit), so you can keep reading the song extensions until you read this FOURCC.

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint16 || Size of this chunk, excluding the header
|}

=== Chunk Contents ===

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..TD</code> || uint32 || IT, MPTM, XM || Integer part of the default tempo (required if it is larger than 255 in IT / MPTM, but also found in legacy XM files)
|-
| <code>DTFR</code> || uint32 || MPTM || Fractional part of the default tempo (0...9999)
|-
| <code>.BPR</code> || uint32 || IT, MPTM, XM || Rows Per Beat
|-
| <code>.MPR</code> || uint32 || IT, MPTM, XM || Rows Per Measure
|-
| <code>...C</code> || uint16 || IT, MPTM || Number of channels
|-
| <code>SnhC</code> || - || IT, MPTM || If there are more than 64 channels in the IT / MTPM format, this chunk contains the default panning, volume and flags for channels 65+. They are encoded the same way as in the IT header, except that volume and panning are stored in an interleaved way (i.e. volume for channel 65, pan for channel 65, volume for channel 66, ...)
|-
| <code>..MT</code> || uint32 || IT, MPTM, XM || Tempo Mode <ul> <li>0: classic</li> <li>1: alternative</li> <li>2: modern</li> </ul>
|-
| <code>.MMP</code> || uint32 || IT, MPTM, XM || Mix Levels <ul> <li>0: Original</li> <li>1: 1.17 RC1</li> <li>2: 1.17 RC2</li> <li>3: 1.17 RC3</li> <li>4: Compatible</li> <li>5: Compatible (FT2 Pan Law)</li> </ul>
|-
| <code>.VWC</code> || uint32 || IT, MPTM, XM || OpenMPT "Created With" version (e.g. OpenMPT 1.23.45.67 = 0x01234567)
|-
| <code>VWSL</code> || uint32 || IT, MPTM, XM || OpenMPT "Last Saved With" version
|-
| <code>.APS</code> || uint32 || IT, MPTM, XM || Sample Pre-Amp
|-
| <code>VTSV</code> || uint32 || IT, MPTM, XM || Synth Pre-Amp (VSTi / OPL)
|-
| <code>.VGD</code> || uint32 || XM || Global Volume (0...256)
|-
| <code>..PR</code> || uint16 || IT, MPTM || Restart Position
|-
| <code>RSMP</code> || uint32 || MPTM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>CUES</code> || - || MPTM || Sample cue points for a single sample (only MPTM format). The first uint16 in the chunk indicates for which sample slot the cue points are meant. The rest of the chunk contains all cue points as uint32s. If this chunk is missing for a particular sample slot, OpenMPT assumes the default cue points for this slot. In this case, the i-th cue point can be computed as i × 2048.
|-
| <code>SWNG</code> || - || MPTM || Contains tempo swing factors (only MPTM format). The first uint16 in the chunk indicates the number of swing rows. The rest of the chunk contains all swing factors as uint32s. A factor of 16777216 (224) is considered to be unity, i.e. does not modify the row duration. After loading, the number of swing factors must be resized to the actual number of rows per beat (in case of malformed file) and re-normalized.
|-
| <code>.FSM</code> || - || IT, MPTM, XM || A bit field of generic compatibility flags. For modules made with OpenMPT 1.25 and older, the most important one is 0x01 (first bit set), which is IT-/XM-compatible playback mode. All other flags indicate which [[Manual: Compatible Playback#Playback Compatibility Settings|compatibility settings]] are toggled.
|-
| <code>AUTH</code> || uint8[] || IT, MPTM, XM || Song artist, as UTF-8 string
|-
| <code>AMIM</code> || - || IT, MPTM, XM || MIDI Mapping settings
|-
| <code>CCOL</code> || rgbx[] || IT, MPTM, XM || Channel colors. The chunk size divided by 4 indicates the number of channels present. Format is [R, G, B, 0] for channels that have a color assigned, or [x, x, x, non-zero] for a channel with no color.
|}

== MPTM Extensions ==

=== Detecting an MPTM file ===

There are two types of hacked IT files: In early versions of the MPTM format (used in OpenMPT 1.17.02.4x), the <code>IMPM</code> magic bytes are replaced by <code>tpm.</code>, so they are not backwards compatible. Newer MPTM files use the original magic, but use a <code>cwtv</code> value between 0889h and 0FFFh (inclusive) in the header.

In both cases, the last four bytes of the file point to the start of the MPTM extensions. If the magic bytes "228" can be found at this start position, it is a valid MPTM file.

=== 228 Extensions ===

228 Extensions have been used since OpenMPT 1.17.02.48 r192 for features that are only available in the MPTM format,
such as Custom Tunings, Multiple Sequences, and Parameter Control notes.

They are documented [[Development:_228_Extensions|here]].

=== External Samples ===

MPTM files can reference external samples. If the <code>cvt</code> value in the sample header is 80h, then the sample is external. In this case, the sample pointer does not point to actual sample data but to a filename:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || VarInt || Length of the filename
|-
| ? || char[] || Filename (UTF-8, not null-terminated)
|}

Note that only the sample waveform must be loaded, but not its metadata: Frequency, loop points, volume, panning, auto-vibrato etc. must be read from the IT file. If the sample length according to the IT header is shorter than the actual sample, the sample data must be trimmed, too.

External samples are used exactly the same way in ITI files.

=== OPL Instruments ===

MPTM files can make use of OPL instruments, just like S3M files. Unlike in S3M files, patch data is not stuffed into the sample header but stored as regular sample data. To tell OPL patches apart from regular samples, the <code>cvt</code> value in the sample header is set to 40h. Note that the check for this flag must be an equal comparison (<code>cvt == 40h</code>), not a bitwise AND, due to ModPlug's legacy ADPCM sample <code>cvt</code> type (FFh). Any combination with other <code>cvt</code> flags is also considered to be illegal.

OPL2 patches are stored in the same order as in S3M files, i.e. interleaved modulator and carrier bytes, with the last (12th) byte being unused and set to 0.

=== Order list (old) ===

If the <code>cwtv</code> is between 088Bh and 088Dh (inclusive), the order list at the start of the file is replaced by the following struct:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint16 || Version of the order list. Only version 0 is defined. Reject any other values.
|-
| 2 || uint32 || Number of items in the order list
|-
| 6 || uint32[] || The order list, as a series of uint32 values. The number of values is determined by the previous field.
|}

=== Custom Tunings (old) ===

This section is for OpenMPT versions before 1.17.02.48 r192. For newer versions, check [[Development:_228_Extensions|228 Extensions]].

Before OpenMPT 1.17.02.48 r192, the only feature that was only available in the MPTM format was Custom Tunings.
MPTM files that were made before r192 have a <code>cwtv</code> value between 0x0888 and 0x088C (inclusive).

These MPTM files contain a "Tuning Collection" chunk that contains all the custom tunings that are specific to the song (called "Tune specific tunings" in OpenMPT),
which is right after the OpenMPT song extensions.
It is then followed by a "Tuning Map" that determines which tuning each instrument should use.

A Tuning Collection could also exist separately in a <code>.TC</code> file, that can be exported/imported into an MPTM file in the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In an MPTM file, the last four bytes pointed to the start of the "Tune specific tunings" Tuning Collection,
similar to how they point to the start of 228 extensions in newer (<code>cwtv</code> > 0x088C) MPTM files.

==== Tuning Collection structure ====

The structure of a Tuning Collection is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| char[4]
| Tuning Collection beginning signature: <code>HSCT</code> (4 bytes)
|-
| int32
| Tuning Collection version: Always 1 or 2. 
|-
| uint8 or uint32
| Length of the Tuning Collection's name. 
Data type:
* uint8 if the Tuning Collection version is 2.
* uint32 if the Tuning Collection version is 1.

|-
| char[]
| Tuning Collection name. The current version of OpenMPT reads a maximum of 256 (0x100) characters. 
If the collection is in a TC file, its name is the same as what it was in OpenMPT when the TC file was exported. 
But in MPTM files, only the tune-specific tuning collection is stored, and its name is always <code>Tune specific tunings</code>.
|-
| int16
| Tuning Collection edit mask. 
A set of 16 bits that was used to specify which settings of the tunings can be changed, but is no longer used in newer versions of OpenMPT.

|-
| uint32
| Number of tunings in the collection. The current version of OpenMPT does not load custom tunings at all if the number of tunings in an MPTM file is greater than 50.
|-
| (custom structure)
| The tunings in this collection, stored right after each other. The structure of a tuning is described below.
|-
| char[4]
| Tuning Collection end signature: <code>FSCT</code> (4 bytes)
|}

==== Tuning structure ====

The structure of a Custom Tuning is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| char[8]
| Tuning beginning signature: <code>CTRTI_B.</code> (8 bytes)
|-
| int16
| Tuning version: Always 2 or 3. 
|-
| char[8]
| Tuning SFS chunk beginning signature: <code>CT<sfs>B</code> (8 bytes)
|-
| int16
| Tuning SFS chunk version: Always 3 or 4. 
|-
| uint8 or uint32
| Length of the tuning's name. 
Data type:
* uint8 if the SFS chunk version is 4.
* uint32 if the SFS chunk version is 3.

|-
| char[]
| Tuning name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|-
| int16
| Tuning edit mask. 
A set of 16 bits that was used to specify which settings of the tuning can be changed, but is no longer used in newer versions of OpenMPT.

|-
| int16
| Tuning type.
* 0: Generic
* 1: Group-geometric (originally called "Ratio-periodic")
* 3: Geometric (originally called "TET")
Newer versions of OpenMPT that use the new tuning format will convert old Geometric tunings to Group-geometric for compatibility reasons.
|-
| uint16 or uint32
| Size of the tuning's note name map. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. 
Data type:
* uint16 if the SFS chunk version is 4.
* uint32 if the SFS chunk version is 3.

|-
| (custom structure)
| The tuning's note name map. Contains the names of notes that have custom names. The structure is described in further below.
|-
| char[8]
| Tuning SFS chunk end signature: <code>CT<sfs>E</code> (8 bytes)
|-
| uint16 or uint32
| Size of the tuning's ratio table. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. This value is usually set to 256 (or 0 if the ratio table is unneeded). 
Data type:
* uint16 if the tuning version is 3.
* uint32 if the tuning version is 2.

|-
| float32[]
| The tuning's ratio table. Contains the frequency ratios for every note. If all ratios are 1, the ratio table is unneeded, so its size would be 0. 
Unlike the newer tuning format that uses 228 extensions, this table contains ratios for every note in every group, regardless of the tuning type.
|-
| uint16 or uint32
| Finetune steps. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. 
Data type:
* uint16 if the tuning version is 3.
* uint32 if the tuning version is 2.

|-
| float32[]
| An array of finetune step ratios, containing the same number of values as the finetune steps value. 
The first value is 1, and each value is r(1/finetunesteps) times the previous value, 
where r is the ratio of note 1 (the note after the middle note) to note 0 (the middle note). 
This table no longer exists in the newer tuning format that uses 228 extensions.
|-
| int16
| First note index in the ratio table. Usually set to -128. 
The current version of OpenMPT rejects values smaller than -200 and greater than 200.
|-
| int16
| Group size. 
For generic tunings, this value is 0.
|-
| float32
| Group ratio. 
For generic tunings, this value is 0.
|-
| char[8]
| Tuning end signature: <code>CTRTI_E.</code> (8 bytes)
|}

Many of the values that are stored for each tuning are redundant.
For example, the ratio table contains ratios for every note, regardless of the tuning type, even though it makes sense to
only have ratios for a single group in group-geometric tunings, and to not be stored at all in geometric tunings.
But they still have to be stored for these old versions of OpenMPT to work correctly.
However, these redundancies no longer exist in the newer tuning format that uses 228 extensions.

==== Tuning note name map structure ====

The structure of a single entry in the note name map is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| int16
| Note number.
|-
| uint8 or uint32
| Length of the note name. 
Data type:
* uint8 if the tuning's SFS chunk version is 4.
* uint32 if the tuning's SFS chunk version is 3.

|-
| char[]
| Note name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|}

This structure is stored for every note that has a custom name.

For geometric and group-geometric tunings, only the notes of a single group, where the note numbers are between 0 and groupsize-1 (inclusive).
The note names for that single group are then applied to every group (group/octave numbers are not a part of the note name).

==== Tuning Map structure ====

The structure of a tuning map is identical to that of the new 228 tuning format (documented [[Development:_228_Extensions#Tuning_Map|here]]), but with a difference if the <code>cwtv</code> value is 0x088B or older:

The number of tunings in the map and the length of the tuning names in the map are both stored as uint32 instead of uint16 and uint8 respectively.

== RIFF WAVE ==

OpenMPT uses its own <code>xtra</code> chunk in RIFF WAVE files to store some sample properties which could otherwise not be represented in the format.

Its layout is as follows:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint32 || Sample flags (0x20: Default panning is enabled)
|-
| 4 || uint16 || Default panning (0...256)
|-
| 6 || uint16 || Default volume (0...256)
|-
| 8 || uint16 || Global volume (0...64)
|-
| 10 || uint16 || (Reserved, must be 0)
|-
| 12 || uint8 || Auto-vibrato type 
|-
| 13 || uint8 || Auto-vibrato sweep
|-
| 14 || uint8 || Auto-vibrato depth
|-
| 15 || uint8 || Auto-vibrato rate
|}

Optionally, when copying a sample to the system clipboard, the sample name (32 characters, null-padded) and filename (22 characters, null-padded) follow.

== FLAC ==

Since the FLAC format has no native and standardized way to store loop information, OpenMPT follows Renoise′s way of storing loop information: FLAC supports application-defined metadata, so OpenMPT writes a metadata block with application ID <code>riff</code>. The block contains a <code>smpl</code> chunk (as defined in the [https://www.mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/RIFFNEW.pdf RIFF specification]). Similarly, extended sample properties are stored in another <code>riff</code> application block contaning the OpenMPT-specific <code>[[#RIFF WAVE|xtra]]</code> chunk, and sample cue points are stored in a <code>cue </code> chunk.

OpenMPT also reads and writes the following non-standard Vorbis comments:
* '''SAMPLERATE''': Contains the sample rate (as text) in case it would exceed the maximum sample rate supported by the FLAC format, 1,048,575 Hz (655350 Hz for older versions).
* '''LOOPSTART''': The start of the sample loop in frames. This tag is only read, not written.
* '''LOOPLENGTH''': The length of the sample loop in frames. This tag is only read, not written.

[[Category:Development|OpenMPT Format Extensions]]

Development: OpenMPT Format Extensions

2024-05-08T07:38:13Z

CS127: /* FX00, ... FX99, F100, ... F255 */ wrap mix mode formulas in code blocks

ModPlug Tracker and OpenMPT have extended the IT and XM formats in various ways. In general, these hacks are frowned upon, but here is some documentation on those hacks in case you want to support them in your own player. I am really sorry about all this mess, but all of this has grown historically way before I joined OpenMPT development.

Presence of these format extensions in a file does not necessarily imply that it was created with ModPlug Tracker or OpenMPT. Some of the extensions are also used e.g. by BeRoTracker.

Any numeric values are stored in little-endian format, unless noted otherwise.

Data types used in this document:
* uint8, uint16, uint32: Unsigned integers with the given bit width.
* int8, int16, int32: Signed integers with the given bit width.
* char: A single character (i.e. a byte)
* float32: Single precision IEEE float
* VarInt: A MIDI-like variable-length unsigned integer (big-endian value where the highest bit of each byte indicates if another byte follows, and the lower 7 bits containing the actual number).
* Square brackets [] denote an array of values:
** [] is a variable-length array (length is deduced from some other attribute)
** [42] denotes an array with 42 entries.

== ModPlug Song Extensions ==

The following extensions exist since the (closed-source) ModPlug Tracker days. These extensions are found in [https://en.wikipedia.org/wiki/Interchange_File_Format IFF]-like chunks, but without any padding bytes. The chunks are placed right after the header data in the IT format (i.e. after the edit history / MIDI macro block). In the XM format these chunks are placed right at the end of the file (i.e. after the sample data). At the time of writing, these chunks are always written out in the order described here, but if possible you should probably try to read them without expecting a certain order. All chunks are optional.

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint32 || Size of this chunk, excluding the header
|}

=== Chunks ===

==== text (XM only) ====

Contains the song message (CR line endings), its length is determined by the chunk size.

==== MIDI (XM only) ====

Contains the MIDI macro configuration, in the same format as in the IT format.

==== PNAM ====

Contains the pattern names. Each pattern name is 32 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The pattern names are stored continuously, i.e. there are (chunk size / 32) pattern names in the chunk, for pattern 0, pattern 1, ... pattern (chunk size / 32 - 1).

==== CNAM ====

Contains the channel names. Each channel name is 20 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The channel names are stored continuously, i.e. there are (chunk size / 20) channel names in the chunk, for channel 1, channel 2, ... channel (chunk size / 20).

==== CHFX ====

Contains the plugin assignment for each channel. For every channel, there is a 32-bit integer plugin index. 0 means no plugin, 1 is the first plugin, etc...

==== FX00, ... FX99, F100, ... F255 ====

Contains plugin information for each plugin slot. <code>FX00</code> contains the information for the first plugin slot, <code>FX99</code> for the 100th, <code>F100</code> for the 101st, etc...

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Plugin Type
<ul>
<li>VST plugins: <code>PtsV</code></li>
<li>DMO plugins: <code>OMXD</code></li>
<li>Internal plugins use various other IDs.</li>
</ul>
|-
| 4 || char[4] || Unique Plugin ID
|-
| 8 || uint8 || Routing Flags
<ul>
<li>0x01: Apply to master mix</li>
<li>0x02: Bypass</li>
<li>0x04: Dry mix</li>
<li>0x08: Expand mix [0%,100%] → [-100%,100%]</li>
<li>0x10: Auto-suspend on silence</li>
</ul>
|-
| 9 || uint8 || Mix mode
<ul>
<li>0: Default (<code>MIX += DRY * dryRatio + WET * wetRatio</code>)</li>
<li>1: Wet Subtract (<code>MIX += DRY - WET * wetRatio</code>)</li>
<li>2: Dry Subtract (<code>MIX += WET - DRY * dryRatio</code>)</li>
<li>3: Mix Subtract (<code>MIX -= WET - DRY * wetRatio</code>)</li>
<li>4: Middle Subtract (<code>MIX -= middle - WET * wetRatio + middle - DRY</code>)</li>
<li>5: L/R Balance (<code>MIX_L += wetRatio * (WET_L - DRY_L) + dryRatio * (DRY_R - WET_R)</code>)</li>
<li>6: Instrument (<code>MIX += DRY + WET * wetRatio</code>)</li>
</ul>
Prior to OpenMPT 1.32.00.11, instrument plugins behaved like the "Instrument" mix mode regardless of their actual mix mode (mix mode and expand mix options were not available in the GUI for instrument plugins). 
This was fixed in 1.32.00.11, and the "Instrument" mix mode was added to emulate the old behaviour for old modules.
|-
| 10 || uint8 || Gain Factor * 10 (9 = 90%, 10 = 100%, 11 = 110%, etc.). A value of 0 is equal to 10 (i.e. 100%).
|-
| 11 || uint8 || (Reserved)
|-
| 12 || uint32 || Output Routing (0 = send to master 0x80 + x = send to plugin x)
|-
| 16 || uint8[16] || (Reserved)
|-
| 32 || char[32] || User-chosen plugin name (Windows code page)
|-
| 64 || char[64] || Library name (Original DLL name / DMO identifier). UTF-8 (max. 64 bytes) since OpenMPT 1.22.07.01, Windows code page in older versions.
|-
| 128 || uint32 || Size of plugin-specific data in bytes (parameters or opaque chunk)
|-
| 132 || uint8[] || Plugin-specific data
|}

The first four bytes of the plugin-specific data determine the type of data. If they are all 0, then the plugin parameters follow as an array of float32 values. Otherwise, plugin type specific data follows which should be treated as an opaque chunk. For example, for VST plugins that support the effGetChunk / effSetChunk opcodes, the first four bytes will be "fEvN", followed by the data to be sent to the plugin.

After the plugin information described above, more information may follow in OpenMPT modules. This information is again stored in chunks. However, there are two legacy chunks which do not have any size stored alongside the chunk identifier:

{| class="wikitable"
|-
! FOURCC !! Data Type !! Description
|-
| <code>DWRT</code> || float32 || Dry/Wet Ratio of the plugin. This chunk does not denote its size!
|-
| <code>PROG</code> || uint32 || Default plugin program (preset) to restore. This chunk does not denote its size!
|}

Any chunks that will be added in the future will have proper IFF-like chunks with a 32-bit size field.

== ModPlug Instrument Extensions (IT only) ==

To be able to address more than 256 samples in the IT format, ModPlug Tracker has an extension to store the high byte of sample indices for the instrument sample map.

By default, the last four bytes of an IT instrument (right after the pitch envelope) are unused. If they read <code>MPTX</code> or <code>XTPM</code>, 120 extra bytes follow, one for each note in the sample map. These bytes are the high byte of the sample index, i.e. they need to be multiplied by 256 and then added to the already read sample index.

== OpenMPT Extensions (General Information) ==

In the XM format, OpenMPT instrument extensions may follow the ModPlug song extensions and may in return be followed by OpenMPT song extensions.

In the IT format, OpenMPT instrument extensions may follow the sample block and may in return be followed by OpenMPT song extensions.
This is very ugly, because there might not be any samples, in which case the last thing before the extension block would be the last pattern. If there are no patterns, the last thing before the extension block would be a sample header (at least one sample header will be present even if there is no sample data – but you may even want to cover the case where there are no sample headers, for being compatible with possible future changes). So you will somehow have to keep track of the highest offset you have read into the file. If the last sample is IT-compressed, things become even more complicated: There is no way to know the compressed size of a compressed sample, so in case you want to skip sample loading, and the last sample happens to be compressed, you can do the following:
Since we know that the extended instrument and song properties start right after the last sample, and since IT-compressed samples consist of chunks with a prepended 16-bit length field, you can simply read that 16-bit number, skip this amount of bytes, then check if you can read OpenMPT's <code>XTPM</code> or <code>STPM</code> magic bytes, and if not, read the next 16-bit length, skip the bytes, etc...

In pseudo code, finding the OpenMPT extensions in an IT / MPTM file could look somewhat like this:

''offset'' = 0
''lastSampleCompressed'' = false

// In case there are no patterns and no sample data (just empty sample slots):
if(number of samples > 0):
''offset'' = last sample header pointer + sizeof(ITSampleHeader)

for all samples:
if sample is not compressed or if samples are decoded:
''lastSampleCompressed'' = false
''offset'' = max(''offset'', pointer to sample data + sample size)
else if sample is compressed and samples are not decoded:
''lastSampleCompressed'' = true
''offset'' = max(''offset'', pointer to sample data)

// In case there is no sample data:
for all patterns:
''offset'' = max(''offset'', end of pattern data)

if ''lastSampleCompressed'':
while not eof:
if next four bytes are XTPM or STPM:
''chunkID'' = next four bytes
if ''chunkID'' only contains ASCII characters (all bytes are in 32…127)
''offset'' = current position - 4; break
else
skip back 8 bytes
read uint16 value and skip as many bytes

Try reading XTPM and STPM extensions at ''offset''

The provided data types are just for orientation, i.e. the minimum recommended field size for storing the values in memory. You must expect fields to have a different size, since sometimes they do so for historic reasons. Defensive programming is your friend. Most of the FOURCCs also just make sense when read backwards, again for historic reasons. Note that some of these extensions duplicate existing functionality of the IT/XM format. In this case, the extensions take precedence over the value previous found in the file.

== OpenMPT Instrument Extensions ==

Instrument extensions start with the <code>XTPM</code> magic bytes, but there is no size indication of the total size of this block. So you have to read the following chunks and as soon as you read the <code>STPM</code> magic bytes for a chunk, you know you have read to far and can continue with reading OpenMPT Song Extensions instead.

Instrument extensions are stored in a peculiar way: There is one chunk per property, and it contains the values for all instruments at once. The layout is as follows:

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint16 || Size of this chunk's entry '''for one instrument''' (i.e. total chunk content size is this field × number of instruments)
|}

=== Chunk Contents ===

The following instrument properties exist. Some of them are redundant depending on the file type and thus not present in all files. If they are redundant, they overwrite the values that were obtained from the format-specific structures.

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..OF</code> || uint32 || IT, MPTM, XM || Fade-out
|-
| <code>...P</code> || uint32 || IT, MPTM, XM || Panning (0...256)
|-
| <code>..EV</code> || uint32 || MPTM || Number of volume envelope nodes (if ≥ 25 nodes)
|-
| <code>..EP</code> || uint32 || MPTM || Number of pan envelope nodes (if ≥ 25 nodes)
|-
| <code>.EiP</code> || uint32 || MPTM || Number of pitch envelope nodes (if ≥ 25 nodes)
|-
| <code>..BM</code> || uint16 || IT, MPTM, XM || MIDI Bank
|-
| <code>..PM</code> || uint8 || IT, MPTM, XM || MIDI Program
|-
| <code>..CM</code> || uint8 || IT, MPTM, XM || MIDI Channel
|-
| <code>.[PV</code> || uint16[] || MPTM || Volume Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EV</code> || uint8[] || MPTM || Volume Envelope Values (if ≥ 25 nodes)
|-
| <code>.[PP</code> || uint16[] || MPTM || Pan Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EP</code> || uint8[] || MPTM || Pan Envelope Values (if ≥ 25 nodes)
|-
| <code>[PiP</code> || uint16[] || MPTM || Pitch Envelope Ticks (if ≥ 25 nodes)
|-
| <code>[EiP</code> || uint8[] || MPTM || Pitch Envelope Values (if ≥ 25 nodes)
|-
| <code>.PiM</code> || uint8 || IT, MPTM, XM || Plugin, 0 = no plugin, 1 = first plugin, etc.
|-
| <code>..RV</code> || uint16 || IT, MPTM, XM || Ramping / Attack
|-
| <code>...R</code> || uint8 || IT, MPTM, XM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>..SC</code> || uint8 || IT, MPTM, XM || Cutoff Swing
|-
| <code>..SR</code> || uint8 || IT, MPTM, XM || Resonance Swing
|-
| <code>..MF</code> || uint8 || IT, MPTM, XM || Filter Mode
|-
| <code>HEVP</code> || uint8 || IT, MPTM, XM || Plugin Velocity Handling
|-
| <code>HOVP</code> || uint8 || IT, MPTM, XM || Plugin Volume Handling
|-
| <code>NREV</code> || uint8 || IT, MPTM, XM || Volume Envelope Release Node
|-
| <code>NREA</code> || uint8 || IT, MPTM, XM || Pan Envelope Release Node
|-
| <code>NREP</code> || uint8 || IT, MPTM, XM || Pitch Envelope Release Node
|-
| <code>DWPM</code> || uint8 || IT, MPTM || Pitch Wheel Depth
|-
| <code>LTTP</code> || uint16 || IT, MPTM, XM || Integer part of Pitch / Tempo Lock
|-
| <code>PTTF</code> || uint16 || MPTM || Fractional part of Pitch / Tempo Lock (0...9999)
|}

=== Legacy Extension ===

But wait, there is more! Some really old OpenMPT versions (1.17 RC1 and older, but not 1.17 RC2) do not use the instrument extensions described above. However, they also need to store the plugin reference for each instrument, which is done in another modular block following each instrument header (and possibly the <code>MPTX</code> / <code>XTPM</code> extension of that instrument header).
If this legacy extension is present, the instrument header is followed by the magic bytes <code>MSNI</code> and an uint32 containing the modular data size.

Currently there is only one chunk in this modular data block. Its FOURCC is <code>GULP</code>, has no size information and contains an uint8 for the plugin index (0 = no plugin, 1 = first plugin, etc.).

== OpenMPT Song Extensions ==

Song extensions start with the <code>STPM</code> magic bytes, but there is no size indication of the total size of this block. In an IT / XM file, these extensions are the last chunks in the file, so you can continue reading until you are out of data. In the case of MPTM files, some further MPTM-specific data follows. This data starts with the bytes "228" followed by ASCII charater 4 (not the digit), so you can keep reading the song extensions until you read this FOURCC.

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint16 || Size of this chunk, excluding the header
|}

=== Chunk Contents ===

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..TD</code> || uint32 || IT, MPTM, XM || Integer part of the default tempo (required if it is larger than 255 in IT / MPTM, but also found in legacy XM files)
|-
| <code>DTFR</code> || uint32 || MPTM || Fractional part of the default tempo (0...9999)
|-
| <code>.BPR</code> || uint32 || IT, MPTM, XM || Rows Per Beat
|-
| <code>.MPR</code> || uint32 || IT, MPTM, XM || Rows Per Measure
|-
| <code>...C</code> || uint16 || IT, MPTM || Number of channels
|-
| <code>SnhC</code> || - || IT, MPTM || If there are more than 64 channels in the IT / MTPM format, this chunk contains the default panning, volume and flags for channels 65+. They are encoded the same way as in the IT header, except that volume and panning are stored in an interleaved way (i.e. volume for channel 65, pan for channel 65, volume for channel 66, ...)
|-
| <code>..MT</code> || uint32 || IT, MPTM, XM || Tempo Mode <ul> <li>0: classic</li> <li>1: alternative</li> <li>2: modern</li> </ul>
|-
| <code>.MMP</code> || uint32 || IT, MPTM, XM || Mix Levels <ul> <li>0: Original</li> <li>1: 1.17 RC1</li> <li>2: 1.17 RC2</li> <li>3: 1.17 RC3</li> <li>4: Compatible</li> <li>5: Compatible (FT2 Pan Law)</li> </ul>
|-
| <code>.VWC</code> || uint32 || IT, MPTM, XM || OpenMPT "Created With" version (e.g. OpenMPT 1.23.45.67 = 0x01234567)
|-
| <code>VWSL</code> || uint32 || IT, MPTM, XM || OpenMPT "Last Saved With" version
|-
| <code>.APS</code> || uint32 || IT, MPTM, XM || Sample Pre-Amp
|-
| <code>VTSV</code> || uint32 || IT, MPTM, XM || Synth Pre-Amp (VSTi / OPL)
|-
| <code>.VGD</code> || uint32 || XM || Global Volume (0...256)
|-
| <code>..PR</code> || uint16 || IT, MPTM || Restart Position
|-
| <code>RSMP</code> || uint32 || MPTM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>CUES</code> || - || MPTM || Sample cue points for a single sample (only MPTM format). The first uint16 in the chunk indicates for which sample slot the cue points are meant. The rest of the chunk contains all cue points as uint32s. If this chunk is missing for a particular sample slot, OpenMPT assumes the default cue points for this slot. In this case, the i-th cue point can be computed as i × 2048.
|-
| <code>SWNG</code> || - || MPTM || Contains tempo swing factors (only MPTM format). The first uint16 in the chunk indicates the number of swing rows. The rest of the chunk contains all swing factors as uint32s. A factor of 16777216 (224) is considered to be unity, i.e. does not modify the row duration. After loading, the number of swing factors must be resized to the actual number of rows per beat (in case of malformed file) and re-normalized.
|-
| <code>.FSM</code> || - || IT, MPTM, XM || A bit field of generic compatibility flags. For modules made with OpenMPT 1.25 and older, the most important one is 0x01 (first bit set), which is IT-/XM-compatible playback mode. All other flags indicate which [[Manual: Compatible Playback#Playback Compatibility Settings|compatibility settings]] are toggled.
|-
| <code>AUTH</code> || uint8[] || IT, MPTM, XM || Song artist, as UTF-8 string
|-
| <code>AMIM</code> || - || IT, MPTM, XM || MIDI Mapping settings
|-
| <code>CCOL</code> || rgbx[] || IT, MPTM, XM || Channel colors. The chunk size divided by 4 indicates the number of channels present. Format is [R, G, B, 0] for channels that have a color assigned, or [x, x, x, non-zero] for a channel with no color.
|}

== MPTM Extensions ==

=== Detecting an MPTM file ===

There are two types of hacked IT files: In early versions of the MPTM format (used in OpenMPT 1.17.02.4x), the <code>IMPM</code> magic bytes are replaced by <code>tpm.</code>, so they are not backwards compatible. Newer MPTM files use the original magic, but use a <code>cwtv</code> value between 0889h and 0FFFh (inclusive) in the header.

In both cases, the last four bytes of the file point to the start of the MPTM extensions. If the magic bytes "228" can be found at this start position, it is a valid MPTM file.

=== 228 Extensions ===

228 Extensions have been used since OpenMPT 1.17.02.48 r192 for features that are only available in the MPTM format,
such as Custom Tunings, Multiple Sequences, and Parameter Control notes.

They are documented [[Development:_228_Extensions|here]].

=== External Samples ===

MPTM files can reference external samples. If the <code>cvt</code> value in the sample header is 80h, then the sample is external. In this case, the sample pointer does not point to actual sample data but to a filename:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || VarInt || Length of the filename
|-
| ? || char[] || Filename (UTF-8, not null-terminated)
|}

Note that only the sample waveform must be loaded, but not its metadata: Frequency, loop points, volume, panning, auto-vibrato etc. must be read from the IT file. If the sample length according to the IT header is shorter than the actual sample, the sample data must be trimmed, too.

External samples are used exactly the same way in ITI files.

=== OPL Instruments ===

MPTM files can make use of OPL instruments, just like S3M files. Unlike in S3M files, patch data is not stuffed into the sample header but stored as regular sample data. To tell OPL patches apart from regular samples, the <code>cvt</code> value in the sample header is set to 40h. Note that the check for this flag must be an equal comparison (<code>cvt == 40h</code>), not a bitwise AND, due to ModPlug's legacy ADPCM sample <code>cvt</code> type (FFh). Any combination with other <code>cvt</code> flags is also considered to be illegal.

OPL2 patches are stored in the same order as in S3M files, i.e. interleaved modulator and carrier bytes, with the last (12th) byte being unused and set to 0.

=== Order list (old) ===

If the <code>cwtv</code> is between 088Bh and 088Dh (inclusive), the order list at the start of the file is replaced by the following struct:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint16 || Version of the order list. Only version 0 is defined. Reject any other values.
|-
| 2 || uint32 || Number of items in the order list
|-
| 6 || uint32[] || The order list, as a series of uint32 values. The number of values is determined by the previous field.
|}

=== Custom Tunings (old) ===

This section is for OpenMPT versions before 1.17.02.48 r192. For newer versions, check [[Development:_228_Extensions|228 Extensions]].

Before OpenMPT 1.17.02.48 r192, the only feature that was only available in the MPTM format was Custom Tunings.
MPTM files that were made before r192 have a <code>cwtv</code> value between 0x0888 and 0x088C (inclusive).

These MPTM files contain a "Tuning Collection" chunk that contains all the custom tunings that are specific to the song (called "Tune specific tunings" in OpenMPT),
which is right after the OpenMPT song extensions.
It is then followed by a "Tuning Map" that determines which tuning each instrument should use.

A Tuning Collection could also exist separately in a <code>.TC</code> file, that can be exported/imported into an MPTM file in the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In an MPTM file, the last four bytes pointed to the start of the "Tune specific tunings" Tuning Collection,
similar to how they point to the start of 228 extensions in newer (<code>cwtv</code> > 0x088C) MPTM files.

==== Tuning Collection structure ====

The structure of a Tuning Collection is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| char[4]
| Tuning Collection beginning signature: <code>HSCT</code> (4 bytes)
|-
| int32
| Tuning Collection version: Always 1 or 2. 
|-
| uint8 or uint32
| Length of the Tuning Collection's name. 
Data type:
* uint8 if the Tuning Collection version is 2.
* uint32 if the Tuning Collection version is 1.

|-
| char[]
| Tuning Collection name. The current version of OpenMPT reads a maximum of 256 (0x100) characters. 
If the collection is in a TC file, its name is the same as what it was in OpenMPT when the TC file was exported. 
But in MPTM files, only the tune-specific tuning collection is stored, and its name is always <code>Tune specific tunings</code>.
|-
| int16
| Tuning Collection edit mask. 
A set of 16 bits that was used to specify which settings of the tunings can be changed, but is no longer used in newer versions of OpenMPT.

|-
| uint32
| Number of tunings in the collection. The current version of OpenMPT does not load custom tunings at all if the number of tunings in an MPTM file is greater than 50.
|-
| (custom structure)
| The tunings in this collection, stored right after each other. The structure of a tuning is described below.
|-
| char[4]
| Tuning Collection end signature: <code>FSCT</code> (4 bytes)
|}

==== Tuning structure ====

The structure of a Custom Tuning is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| char[8]
| Tuning beginning signature: <code>CTRTI_B.</code> (8 bytes)
|-
| int16
| Tuning version: Always 2 or 3. 
|-
| char[8]
| Tuning SFS chunk beginning signature: <code>CT<sfs>B</code> (8 bytes)
|-
| int16
| Tuning SFS chunk version: Always 3 or 4. 
|-
| uint8 or uint32
| Length of the tuning's name. 
Data type:
* uint8 if the SFS chunk version is 4.
* uint32 if the SFS chunk version is 3.

|-
| char[]
| Tuning name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|-
| int16
| Tuning edit mask. 
A set of 16 bits that was used to specify which settings of the tuning can be changed, but is no longer used in newer versions of OpenMPT.

|-
| int16
| Tuning type.
* 0: Generic
* 1: Group-geometric (originally called "Ratio-periodic")
* 3: Geometric (originally called "TET")
Newer versions of OpenMPT that use the new tuning format will convert old Geometric tunings to Group-geometric for compatibility reasons.
|-
| uint16 or uint32
| Size of the tuning's note name map. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. 
Data type:
* uint16 if the SFS chunk version is 4.
* uint32 if the SFS chunk version is 3.

|-
| (custom structure)
| The tuning's note name map. Contains the names of notes that have custom names. The structure is described in further below.
|-
| char[8]
| Tuning SFS chunk end signature: <code>CT<sfs>E</code> (8 bytes)
|-
| uint16 or uint32
| Size of the tuning's ratio table. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. This value is usually set to 256 (or 0 if the ratio table is unneeded). 
Data type:
* uint16 if the tuning version is 3.
* uint32 if the tuning version is 2.

|-
| float32[]
| The tuning's ratio table. Contains the frequency ratios for every note. If all ratios are 1, the ratio table is unneeded, so its size would be 0. 
Unlike the newer tuning format that uses 228 extensions, this table contains ratios for every note in every group, regardless of the tuning type.
|-
| uint16 or uint32
| Finetune steps. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. 
Data type:
* uint16 if the tuning version is 3.
* uint32 if the tuning version is 2.

|-
| float32[]
| An array of finetune step ratios, containing the same number of values as the finetune steps value. 
The first value is 1, and each value is r(1/finetunesteps) times the previous value, 
where r is the ratio of note 1 (the note after the middle note) to note 0 (the middle note). 
This table no longer exists in the newer tuning format that uses 228 extensions.
|-
| int16
| First note index in the ratio table. Usually set to -128. 
The current version of OpenMPT rejects values smaller than -200 and greater than 200.
|-
| int16
| Group size. 
For generic tunings, this value is 0.
|-
| float32
| Group ratio. 
For generic tunings, this value is 0.
|-
| char[8]
| Tuning end signature: <code>CTRTI_E.</code> (8 bytes)
|}

Many of the values that are stored for each tuning are redundant.
For example, the ratio table contains ratios for every note, regardless of the tuning type, even though it makes sense to
only have ratios for a single group in group-geometric tunings, and to not be stored at all in geometric tunings.
But they still have to be stored for these old versions of OpenMPT to work correctly.
However, these redundancies no longer exist in the newer tuning format that uses 228 extensions.

==== Tuning note name map structure ====

The structure of a single entry in the note name map is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| int16
| Note number.
|-
| uint8 or uint32
| Length of the note name. 
Data type:
* uint8 if the tuning's SFS chunk version is 4.
* uint32 if the tuning's SFS chunk version is 3.

|-
| char[]
| Note name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|}

This structure is stored for every note that has a custom name.

For geometric and group-geometric tunings, only the notes of a single group, where the note numbers are between 0 and groupsize-1 (inclusive).
The note names for that single group are then applied to every group (group/octave numbers are not a part of the note name).

==== Tuning Map structure ====

The structure of a tuning map is identical to that of the new 228 tuning format (documented [[Development:_228_Extensions#Tuning_Map|here]]), but with a difference if the <code>cwtv</code> value is 0x088B or older:

The number of tunings in the map and the length of the tuning names in the map are both stored as uint32 instead of uint16 and uint8 respectively.

== RIFF WAVE ==

OpenMPT uses its own <code>xtra</code> chunk in RIFF WAVE files to store some sample properties which could otherwise not be represented in the format.

Its layout is as follows:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint32 || Sample flags (0x20: Default panning is enabled)
|-
| 4 || uint16 || Default panning (0...256)
|-
| 6 || uint16 || Default volume (0...256)
|-
| 8 || uint16 || Global volume (0...64)
|-
| 10 || uint16 || (Reserved, must be 0)
|-
| 12 || uint8 || Auto-vibrato type 
|-
| 13 || uint8 || Auto-vibrato sweep
|-
| 14 || uint8 || Auto-vibrato depth
|-
| 15 || uint8 || Auto-vibrato rate
|}

Optionally, when copying a sample to the system clipboard, the sample name (32 characters, null-padded) and filename (22 characters, null-padded) follow.

== FLAC ==

Since the FLAC format has no native and standardized way to store loop information, OpenMPT follows Renoise′s way of storing loop information: FLAC supports application-defined metadata, so OpenMPT writes a metadata block with application ID <code>riff</code>. The block contains a <code>smpl</code> chunk (as defined in the [https://www.mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/RIFFNEW.pdf RIFF specification]). Similarly, extended sample properties are stored in another <code>riff</code> application block contaning the OpenMPT-specific <code>[[#RIFF WAVE|xtra]]</code> chunk, and sample cue points are stored in a <code>cue </code> chunk.

OpenMPT also reads and writes the following non-standard Vorbis comments:
* '''SAMPLERATE''': Contains the sample rate (as text) in case it would exceed the maximum sample rate supported by the FLAC format, 1,048,575 Hz (655350 Hz for older versions).
* '''LOOPSTART''': The start of the sample loop in frames. This tag is only read, not written.
* '''LOOPLENGTH''': The length of the sample loop in frames. This tag is only read, not written.

[[Category:Development|OpenMPT Format Extensions]]

Manual: General

2024-05-07T23:52:14Z

CS127: /* Mix Settings */ added the Instrument mix mode

[[Image:General Tab.png|thumb|300px|General Tab]]

The General tab holds the general global settings of each song and is also used to set up the plugins that are used in a song. Many of these settings can be changed using a coarse slider, a text box to enter a precise value or the spin button next to the text boxes to increase or decrease a value. Some options are not available in all module formats; if that is the case, their controls are simply greyed out and cannot be accessed.

The General tab is divided into two halves. They are divided by a splitter bar, which can be dragged vertically to change the size of both views.

== Song Setup ==

=== Miscellaneous ===

* '''Track Name''': In the first text box, you can enter the name of your song. Depending on the module format used, the length of this text field is limited.
* '''Artist''': Contains the name of the track artist.
* '''Song Properties''': Next to the track name, you can see which module format the current song is in, as well as the number of pattern channels. To change either of them (plus some further global settings), click the button to open the [[Manual: Song Properties|Song Properties]] dialog.
* '''Resampling''': In the MPTM format, a default resampling mode can be enforced. If '''Default''' is chosen, the default resampling method as configured in the [[Manual: Setup/Mixer#Resampling|Mixer Settings]] is used. This setting can be further overridden by [[Manual: Instruments#Sample Quality|instruments]]. In other formats, this dropdown list can be used to temporarily override the global resampling method, but its setting is not stored in files.
* '''VU Meters''': The VU Meters show the level of the left and right master output channel during playback. Their colour can be configured in the [[Manual: Setup/Display|Display Setup]].

=== Tempo ===

* '''Initial Tempo''': The track′s initial Tempo value. The effect of this setting is determined by the [[Manual: Song Properties#Tempo Mode|Tempo Mode]], which can be set in the [[Manual: Song Properties|Song Properties]] dialog. This setting can also be changed during playback using the Txx command in MPTM / IT / S3M and the Fxx command (with xx ≥ 20h) in XM / MOD tracks. In the MPTM format, the tempo may be fractional (e.g. 136.46 BPM) and can be incremented / decremented in 0.1 steps by holding <kbd>Shift</kbd> when clicking the spinner buttons, or 0.01 steps by holding <kbd>Ctrl</kbd>.
* '''Ticks / Row''' ('''Initial Speed'''): The track′s initial ticks per row (Speed) value. The effect of this setting is determined by the [[Manual: Song Properties#Tempo Mode|Tempo Mode]], which can be set in the [[Manual: Song Properties|Song Properties]] dialog. This setting can also be changed during playback using the Axx command in MPTM / IT / S3M and the Fxx command (with xx < 20h) in XM / MOD tracks.
* '''Tempo Tap''': Use the '''Tap''' button to tap in the beats per minute. Click the button or hit enter while the button is focussed to signal a beat. The more beats you tap in, the more precise the tempo is estimated. Wait for about two seconds to reset the estimation.

=== Restart / Loop ===

* '''Restart''': If '''Loop Song''' is enabled, playback will resume at this [[Manual: Patterns#Order List|order list]] position when the song end is reached. If there is more than one sequence (order list), this value represents the restart position of the currently selected sequence.
* '''Loop Song''': If this box is checked, your song will restart from the restart position and loop if the end is reached. This is a global setting rather than a per-song setting and is applied to all tracks you play in OpenMPT.

=== Volume Settings ===

* '''Initial Global Volume''': The track′s initial Global Volume value, which is the global amplification of a song. The exact effect of this setting depends on the [[Manual: Song Properties#Mix Levels|Mix Levels]], which can be set in the [[Manual: Song Properties|Song Properties]] dialog. Global volume can be changed during playback using the Vxx command in MPTM / IT / S3M (with xx ranging from 00h to 80h in MPTM / IT and from 00h to 40h in S3M) or Gxx in the XM format (with xx ranging from 00h to 40h).
* '''Synth Volume''': This setting determines the overall amplification of the output of all VST instruments and FM synthesis. This setting cannot be changed using pattern effects.
* '''Sample Volume''': This setting determines the overall amplification of samples. Too high amplification will saturate or overdrive sample output. This setting cannot be changed using pattern effects. It is the only volume slider available for ProTracker MOD files, but the value is actually not stored in such files.

When using [[Manual:_Song_Properties#Mix_Levels|modern or compatible mix levels]], hovering the volume sliders reveals a tooltip that translates the current attenuation setting into dB units. For the VSTi volume, this means how much every single instrument plugin is attenuated, and for the sample volume, it means how much every single sample voice is attenuated.

== Channel Setup ==

In the middle of the page is the Channel Setup section, which displays four channels at a time, and allows for editing each channel’s initial settings. To browse through all available channels, use the tab control.
The track format determines what settings can be modified both initially and during output. The following properties can be set for each channel:

* '''Colour''': Clicking on the coloured button next to the channel number allows you to pick the colour of this channel, which is shown at the top of the pattern editor.
* '''Channel Name''': You can assign a name to your channels which is shown in the [[Manual: Patterns|Pattern Editor]] and the [[Manual: Channel Manager|Channel Manager]], to keep your module tidy and help distinguish channels.
* '''Initial Channel Volume''': The global volume of a channel. All note volumes are multiplied with this. Channel volume is only applied to samples, not to VST instruments, but since it is applied to samples, it can affect the input of an effect plugin. XM and MOD files do not have a channel volume setting. S3M files can make use of channel volume, but they have no initial channel volume, so this control is greyed out. You can use the Mxx command (with xx ranging from 00h to 40h) in patterns to set the channel volume.
* '''Initial Panning''': The channel’s initial stereo panning. Unlike the channel volume, this setting is not “global”; panning commands, sample panning and instrument ''override'' the initial panning. In MOD files, the initial panning is fixed to a Left/Right/Right/Left scheme; XM files do not support initial channel panning due to the fact that every sample in XM files has a forced default panning. Panning can be changed in the patterns by using the 8xx or E8x command in XM and MOD files and the Xxx or S8x command in MPTM / IT / S3M files.
* '''Mute''': Clicking on this button enables / disables all audio output from this channel. Notes played in a channel are always processed, but if “Ignore Muted Channels” is set in the [[Manual: Setup/General|General Options]] page, unmuting a channel will not play a currently running note, instead picking up when a new note is called. Keep in mind that no effects are processed on muted channels in S3M files, so e.g. tempo changes or pattern breaks are not handled on muted channels in S3M files. Also, the channel mute status is only saved in MPTM / IT / S3M files.
* '''Surround''': This button toggles the surround panning setting for the current channel. Surround and initial panning are mutually exclusive; if surround is enabled, the initial panning is forced to center. Surround can be reset in the pattern using a panning command (unless quad surround panning is enabled). In MPTM and IT files, surround can be enabled using the command S91; in the S3M format, the command XA4 shall be used.
* '''Channel Effect''': Here you can assign an effect plugin to the current channel. All sample output on this channel is then routed through the effect plugin. To apply more than one plugin to the channel, you can use the plugin’s “Output To” property to route its output to another plugin. Note: While instrument plugins override channel plugins (i.e. if an instrument has a plugin assigned, the sample output of this instrument is '''not''' routed through the channel′s effect plugin), channel plugins are always preferred over instrument plugins when using [[Manual: Zxx Macros#Plugin Parameter Control|MIDI Macros]].

The channel properties can also be edited directly from the pattern editor by using the [[Manual: Quick Channel Settings|Quick Channel Settings dialog]].

== Plugin Setup ==

The bottom part of this tab is dedicated to the plugin setup. Here, you can load plugins into your song, configure them, move them, and so on.

=== General ===

* '''Plugin Slot''': Shows the currently edited plugin; all parameters shown in this section apply to this plugin. Clicking in the field opens a list where you can switch to a different plugin. Clicking on the left / right arrows next to the field changes the current plugin to the previous / next one in the Plugin List. There are 250 available slots where plugins can be placed, and they do not need to be placed sequentially. However, if an output chain is set up, a VST can only output to one farther down the list (with a higher slot number). So for example, a chain can route its audio from slots 1 to 3 to 5, but not 1 to 5 to 3.
* '''Move Plugin''': This allows you to move the current plugin to another slot. When moving, you will be shown a dialog box which will allow you to choose an empty slot to move the plugin to. References to this plugin (for example from instruments or channel setup) are updated automatically when moving. If the moved plugin is part of a chain, and the plugin is moved to a slot ''after'' its output plugin, the “move plugin chain” must remain enabled, or otherwise the chain will be broken and the Output field (see below) will revert to Default.
* '''Clone Plugin''': Creates a new instance of the same plugin in another slot. If the plugin is part of the chain, it is possible to clone the entire chain starting from this plugin by enabling the “move plugin chain” option.
* '''Insert Slot''': Creates an empty slot ''before'' the current plugin’s place in the list. This will effectively push the current plugin and all those after it in the list down one slot. If a plugin occupies the last slot (with the highest number), it is deleted; '''this cannot be undone''', but you are prompted to confirm the insertion in that case.
* '''Remove''': Removes this plugin instance from the module.
* '''Select Plugin''': Opens the [[Manual: Plugin Manager|Plugin Manager]], where you can select a plugin to put into the current slot, replacing the current plugin if there is one. You can also '''remove''' the current plugin by choosing “No Plugin” in the Plugin Manager.
* '''Editor''': This button opens the [[Manual: Plugin Window|Plugin Window]] where you can edit the plugin′s properties. <kbd>Shift</kbd>-clicking the button closes all other open plugin editors.
* '''Display Name''': An text field where you can provide a custom name for the plugin. This label will appear in the Channel Header if the plugin is assigned to a channel, or the Plugin Select field in the Instruments page if it is assigned to an instrument, so it can be useful to choose a custom name here if you are using several instances of the same plugin.
* '''Input / Output Type''': A description of the type of audio signal going in and out of the plugin (none, mono, or stereo).

=== Factory Preset ===

Here you can quickly change some parameters. Usually, the more comfortable way to do this is using the [[Manual: Plugin Window|Plugin Window]], but some plugins might not expose all parameters through their window. So in that case, you can still edit them here.

* '''Preset''': The currently loaded plugin preset, or “patch”. The number of available preset slots varies from plugin to plugin; some do not have any presets at all.
* '''Load Preset''': Use this to load an existing plugin preset or bank (.fxp or .fxb file).
* '''Save Preset''': Use this to save the current plugin parameters to a plugin preset or bank file.
* '''Parameter''': Pick a parameter from this list to edit it using the slider below. You can either drag the slider to adjust the value, or input a parameter using the text box next to it. Use the '''Set''' button to apply the value you typed into the text box.

[[Image: Plugin Dry Wet Ratio.png|thumb|300px|The “Expand” option changes the behaviour of the Dry / Wet ratio setting.]]

=== Mix Settings ===

This option group is used to set up the inputs and outputs of the plugin.

* '''Master''': When enabled, this plugin is applied to the master audio output.
* '''Bypass''': If checked, the plugin is not processed anymore. An instrument plugin will cease to make sound and effect plugins will stop having an effect on the audio that is routed through them.
* '''Expand''': This option affects the Dry / Wet setting. Normally, the Dry / Wet ratio ranges from 100% Wet / 0% Dry to 0% Wet / 100% Dry, but with this setting, it ranges from 100% Wet / -100% Dry to -100% Wet / 100% Dry. A negative value means that the phase of the signal is inverted. So if the slider is full left, you get to hear the wet signal as well as an inverted copy of the dry signal, at the middle you get no output at all (0% Wet / 0% Dry) and if the slider is full right, you get the original signal plus an inverted copy of the wet signal. While being potentially interesting conceptually, this setting is unlikely to be useful musically. This setting is not available for plugins with no inputs.
* '''Dry Mix''': If enabled, the dry (incoming) signal is added to the output signal of a plugin, in addition to the dry amount of the Dry / Wet slider. This is most commonly used for plugins that have no Dry / Wet mix settings built in. For example, in a delay plugin with no dry signal, all you get is the later echoes with no original sound, which is not what you normally want. In that case, you can enable Dry Mix to add the original signal.
* '''Auto-Suspend''': If enabled, the plugin will be suspended temporarily if it has not received any input (MIDI or audio) and also not produced any output for several seconds. If a plugin gets confused by the observed discontinuity in time, or if its output contains long intentional passages of silences that do not correlate with any input, this option can be turned off.
* '''Mix Mode''': This determines how the Wet / Dry ratio affects the output signal. Several options are available:
** '''Default''': No special processing.
** '''Wet Subtract''': The Dry signal is added to the mix, the Wet signal (multiplied by the Wet ratio) is subtracted from the mix.
** '''Dry Subtract''': The Wet signal is added to the mix, the Dry signal (multiplied by the Dry ratio) is subtracted from the mix.
** '''Mix Subtract''': The Wet signal is subtracted from the mix, the Dry signal (multiplied by the Wet ratio) is added to the mix.
** '''Middle Subtract''': The Middle channel is subtracted from the mix, then the dry and wet signal are added normally.
** '''LR Balance''': The Wet / Dry ratio is treated as a panning ratio for the signal.
** '''Instrument''': Same as default, but the dry ratio is forced to 1 (old behaviour of instrument plugins prior to OpenMPT 1.32.00.11, regardless of their mix mode).
* '''Gain''': This adjusts the volume of the plugin from 0.1 - 8.0 in increments of 0.1. This is used to reduce or boost the volume of plugins that are quieter or louder than desired. The default gain is 1.0 (no change in volume).
* '''Output To''': Specifies where the plugin′s audio and MIDI output is routed to. By default it is combined into the Master Audio route, but you can create a plugin chain by routing it to another plugin as long as its slot number is higher than the current plugin′s slot. Note that MIDI events are only routed if an output plugin is specified, i.e. they are not routed to the master.
* '''Dry / Wet Slider''': Controls the Dry / Wet ratio of the plugin. The exact meaning of the ratio is determined by the “Expand”, “Dry Mix” and “Mix Mode” options described above.

[[Category:Manual|General Tab]]
[[Category:Tabs|General Tab]]
[[de:Handbuch: General]]

Development: OpenMPT Format Extensions

2024-05-07T23:47:41Z

CS127: /* FX00, ... FX99, F100, ... F255 */ fixed a few mistakes, changed mix mode descriptions, and added the new Instrument mix mode

ModPlug Tracker and OpenMPT have extended the IT and XM formats in various ways. In general, these hacks are frowned upon, but here is some documentation on those hacks in case you want to support them in your own player. I am really sorry about all this mess, but all of this has grown historically way before I joined OpenMPT development.

Presence of these format extensions in a file does not necessarily imply that it was created with ModPlug Tracker or OpenMPT. Some of the extensions are also used e.g. by BeRoTracker.

Any numeric values are stored in little-endian format, unless noted otherwise.

Data types used in this document:
* uint8, uint16, uint32: Unsigned integers with the given bit width.
* int8, int16, int32: Signed integers with the given bit width.
* char: A single character (i.e. a byte)
* float32: Single precision IEEE float
* VarInt: A MIDI-like variable-length unsigned integer (big-endian value where the highest bit of each byte indicates if another byte follows, and the lower 7 bits containing the actual number).
* Square brackets [] denote an array of values:
** [] is a variable-length array (length is deduced from some other attribute)
** [42] denotes an array with 42 entries.

== ModPlug Song Extensions ==

The following extensions exist since the (closed-source) ModPlug Tracker days. These extensions are found in [https://en.wikipedia.org/wiki/Interchange_File_Format IFF]-like chunks, but without any padding bytes. The chunks are placed right after the header data in the IT format (i.e. after the edit history / MIDI macro block). In the XM format these chunks are placed right at the end of the file (i.e. after the sample data). At the time of writing, these chunks are always written out in the order described here, but if possible you should probably try to read them without expecting a certain order. All chunks are optional.

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint32 || Size of this chunk, excluding the header
|}

=== Chunks ===

==== text (XM only) ====

Contains the song message (CR line endings), its length is determined by the chunk size.

==== MIDI (XM only) ====

Contains the MIDI macro configuration, in the same format as in the IT format.

==== PNAM ====

Contains the pattern names. Each pattern name is 32 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The pattern names are stored continuously, i.e. there are (chunk size / 32) pattern names in the chunk, for pattern 0, pattern 1, ... pattern (chunk size / 32 - 1).

==== CNAM ====

Contains the channel names. Each channel name is 20 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The channel names are stored continuously, i.e. there are (chunk size / 20) channel names in the chunk, for channel 1, channel 2, ... channel (chunk size / 20).

==== CHFX ====

Contains the plugin assignment for each channel. For every channel, there is a 32-bit integer plugin index. 0 means no plugin, 1 is the first plugin, etc...

==== FX00, ... FX99, F100, ... F255 ====

Contains plugin information for each plugin slot. <code>FX00</code> contains the information for the first plugin slot, <code>FX99</code> for the 100th, <code>F100</code> for the 101st, etc...

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Plugin Type
<ul>
<li>VST plugins: <code>PtsV</code></li>
<li>DMO plugins: <code>OMXD</code></li>
<li>Internal plugins use various other IDs.</li>
</ul>
|-
| 4 || char[4] || Unique Plugin ID
|-
| 8 || uint8 || Routing Flags
<ul>
<li>0x01: Apply to master mix</li>
<li>0x02: Bypass</li>
<li>0x04: Dry mix</li>
<li>0x08: Expand mix [0%,100%] → [-100%,100%]</li>
<li>0x10: Auto-suspend on silence</li>
</ul>
|-
| 9 || uint8 || Mix mode
<ul>
<li>0: Default</li>
<li>1: Wet Subtract</li>
<li>2: Dry Subtract</li>
<li>3: Mix Subtract</li>
<li>4: Middle Subtract</li>
<li>5: L/R Balance</li>
<li>6: Instrument (same as default, but forces dry ratio to 1)</li>
</ul>
Prior to OpenMPT 1.32.00.11, instrument plugins behaved like the "Instrument" mix mode regardless of their actual mix mode. 
This was fixed in 1.32.00.11, and the "Instrument" mix mode was added to emulate the old behaviour for old modules.
|-
| 10 || uint8 || Gain Factor * 10 (9 = 90%, 10 = 100%, 11 = 110%, etc.). A value of 0 is equal to 10 (i.e. 100%).
|-
| 11 || uint8 || (Reserved)
|-
| 12 || uint32 || Output Routing (0 = send to master 0x80 + x = send to plugin x)
|-
| 16 || uint8[16] || (Reserved)
|-
| 32 || char[32] || User-chosen plugin name (Windows code page)
|-
| 64 || char[64] || Library name (Original DLL name / DMO identifier). UTF-8 (max. 64 bytes) since OpenMPT 1.22.07.01, Windows code page in older versions.
|-
| 128 || uint32 || Size of plugin-specific data in bytes (parameters or opaque chunk)
|-
| 132 || uint8[] || Plugin-specific data
|}

The first four bytes of the plugin-specific data determine the type of data. If they are all 0, then the plugin parameters follow as an array of float32 values. Otherwise, plugin type specific data follows which should be treated as an opaque chunk. For example, for VST plugins that support the effGetChunk / effSetChunk opcodes, the first four bytes will be "fEvN", followed by the data to be sent to the plugin.

After the plugin information described above, more information may follow in OpenMPT modules. This information is again stored in chunks. However, there are two legacy chunks which do not have any size stored alongside the chunk identifier:

{| class="wikitable"
|-
! FOURCC !! Data Type !! Description
|-
| <code>DWRT</code> || float32 || Dry/Wet Ratio of the plugin. This chunk does not denote its size!
|-
| <code>PROG</code> || uint32 || Default plugin program (preset) to restore. This chunk does not denote its size!
|}

Any chunks that will be added in the future will have proper IFF-like chunks with a 32-bit size field.

== ModPlug Instrument Extensions (IT only) ==

To be able to address more than 256 samples in the IT format, ModPlug Tracker has an extension to store the high byte of sample indices for the instrument sample map.

By default, the last four bytes of an IT instrument (right after the pitch envelope) are unused. If they read <code>MPTX</code> or <code>XTPM</code>, 120 extra bytes follow, one for each note in the sample map. These bytes are the high byte of the sample index, i.e. they need to be multiplied by 256 and then added to the already read sample index.

== OpenMPT Extensions (General Information) ==

In the XM format, OpenMPT instrument extensions may follow the ModPlug song extensions and may in return be followed by OpenMPT song extensions.

In the IT format, OpenMPT instrument extensions may follow the sample block and may in return be followed by OpenMPT song extensions.
This is very ugly, because there might not be any samples, in which case the last thing before the extension block would be the last pattern. If there are no patterns, the last thing before the extension block would be a sample header (at least one sample header will be present even if there is no sample data – but you may even want to cover the case where there are no sample headers, for being compatible with possible future changes). So you will somehow have to keep track of the highest offset you have read into the file. If the last sample is IT-compressed, things become even more complicated: There is no way to know the compressed size of a compressed sample, so in case you want to skip sample loading, and the last sample happens to be compressed, you can do the following:
Since we know that the extended instrument and song properties start right after the last sample, and since IT-compressed samples consist of chunks with a prepended 16-bit length field, you can simply read that 16-bit number, skip this amount of bytes, then check if you can read OpenMPT's <code>XTPM</code> or <code>STPM</code> magic bytes, and if not, read the next 16-bit length, skip the bytes, etc...

In pseudo code, finding the OpenMPT extensions in an IT / MPTM file could look somewhat like this:

''offset'' = 0
''lastSampleCompressed'' = false

// In case there are no patterns and no sample data (just empty sample slots):
if(number of samples > 0):
''offset'' = last sample header pointer + sizeof(ITSampleHeader)

for all samples:
if sample is not compressed or if samples are decoded:
''lastSampleCompressed'' = false
''offset'' = max(''offset'', pointer to sample data + sample size)
else if sample is compressed and samples are not decoded:
''lastSampleCompressed'' = true
''offset'' = max(''offset'', pointer to sample data)

// In case there is no sample data:
for all patterns:
''offset'' = max(''offset'', end of pattern data)

if ''lastSampleCompressed'':
while not eof:
if next four bytes are XTPM or STPM:
''chunkID'' = next four bytes
if ''chunkID'' only contains ASCII characters (all bytes are in 32…127)
''offset'' = current position - 4; break
else
skip back 8 bytes
read uint16 value and skip as many bytes

Try reading XTPM and STPM extensions at ''offset''

The provided data types are just for orientation, i.e. the minimum recommended field size for storing the values in memory. You must expect fields to have a different size, since sometimes they do so for historic reasons. Defensive programming is your friend. Most of the FOURCCs also just make sense when read backwards, again for historic reasons. Note that some of these extensions duplicate existing functionality of the IT/XM format. In this case, the extensions take precedence over the value previous found in the file.

== OpenMPT Instrument Extensions ==

Instrument extensions start with the <code>XTPM</code> magic bytes, but there is no size indication of the total size of this block. So you have to read the following chunks and as soon as you read the <code>STPM</code> magic bytes for a chunk, you know you have read to far and can continue with reading OpenMPT Song Extensions instead.

Instrument extensions are stored in a peculiar way: There is one chunk per property, and it contains the values for all instruments at once. The layout is as follows:

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint16 || Size of this chunk's entry '''for one instrument''' (i.e. total chunk content size is this field × number of instruments)
|}

=== Chunk Contents ===

The following instrument properties exist. Some of them are redundant depending on the file type and thus not present in all files. If they are redundant, they overwrite the values that were obtained from the format-specific structures.

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..OF</code> || uint32 || IT, MPTM, XM || Fade-out
|-
| <code>...P</code> || uint32 || IT, MPTM, XM || Panning (0...256)
|-
| <code>..EV</code> || uint32 || MPTM || Number of volume envelope nodes (if ≥ 25 nodes)
|-
| <code>..EP</code> || uint32 || MPTM || Number of pan envelope nodes (if ≥ 25 nodes)
|-
| <code>.EiP</code> || uint32 || MPTM || Number of pitch envelope nodes (if ≥ 25 nodes)
|-
| <code>..BM</code> || uint16 || IT, MPTM, XM || MIDI Bank
|-
| <code>..PM</code> || uint8 || IT, MPTM, XM || MIDI Program
|-
| <code>..CM</code> || uint8 || IT, MPTM, XM || MIDI Channel
|-
| <code>.[PV</code> || uint16[] || MPTM || Volume Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EV</code> || uint8[] || MPTM || Volume Envelope Values (if ≥ 25 nodes)
|-
| <code>.[PP</code> || uint16[] || MPTM || Pan Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EP</code> || uint8[] || MPTM || Pan Envelope Values (if ≥ 25 nodes)
|-
| <code>[PiP</code> || uint16[] || MPTM || Pitch Envelope Ticks (if ≥ 25 nodes)
|-
| <code>[EiP</code> || uint8[] || MPTM || Pitch Envelope Values (if ≥ 25 nodes)
|-
| <code>.PiM</code> || uint8 || IT, MPTM, XM || Plugin, 0 = no plugin, 1 = first plugin, etc.
|-
| <code>..RV</code> || uint16 || IT, MPTM, XM || Ramping / Attack
|-
| <code>...R</code> || uint8 || IT, MPTM, XM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>..SC</code> || uint8 || IT, MPTM, XM || Cutoff Swing
|-
| <code>..SR</code> || uint8 || IT, MPTM, XM || Resonance Swing
|-
| <code>..MF</code> || uint8 || IT, MPTM, XM || Filter Mode
|-
| <code>HEVP</code> || uint8 || IT, MPTM, XM || Plugin Velocity Handling
|-
| <code>HOVP</code> || uint8 || IT, MPTM, XM || Plugin Volume Handling
|-
| <code>NREV</code> || uint8 || IT, MPTM, XM || Volume Envelope Release Node
|-
| <code>NREA</code> || uint8 || IT, MPTM, XM || Pan Envelope Release Node
|-
| <code>NREP</code> || uint8 || IT, MPTM, XM || Pitch Envelope Release Node
|-
| <code>DWPM</code> || uint8 || IT, MPTM || Pitch Wheel Depth
|-
| <code>LTTP</code> || uint16 || IT, MPTM, XM || Integer part of Pitch / Tempo Lock
|-
| <code>PTTF</code> || uint16 || MPTM || Fractional part of Pitch / Tempo Lock (0...9999)
|}

=== Legacy Extension ===

But wait, there is more! Some really old OpenMPT versions (1.17 RC1 and older, but not 1.17 RC2) do not use the instrument extensions described above. However, they also need to store the plugin reference for each instrument, which is done in another modular block following each instrument header (and possibly the <code>MPTX</code> / <code>XTPM</code> extension of that instrument header).
If this legacy extension is present, the instrument header is followed by the magic bytes <code>MSNI</code> and an uint32 containing the modular data size.

Currently there is only one chunk in this modular data block. Its FOURCC is <code>GULP</code>, has no size information and contains an uint8 for the plugin index (0 = no plugin, 1 = first plugin, etc.).

== OpenMPT Song Extensions ==

Song extensions start with the <code>STPM</code> magic bytes, but there is no size indication of the total size of this block. In an IT / XM file, these extensions are the last chunks in the file, so you can continue reading until you are out of data. In the case of MPTM files, some further MPTM-specific data follows. This data starts with the bytes "228" followed by ASCII charater 4 (not the digit), so you can keep reading the song extensions until you read this FOURCC.

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint16 || Size of this chunk, excluding the header
|}

=== Chunk Contents ===

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..TD</code> || uint32 || IT, MPTM, XM || Integer part of the default tempo (required if it is larger than 255 in IT / MPTM, but also found in legacy XM files)
|-
| <code>DTFR</code> || uint32 || MPTM || Fractional part of the default tempo (0...9999)
|-
| <code>.BPR</code> || uint32 || IT, MPTM, XM || Rows Per Beat
|-
| <code>.MPR</code> || uint32 || IT, MPTM, XM || Rows Per Measure
|-
| <code>...C</code> || uint16 || IT, MPTM || Number of channels
|-
| <code>SnhC</code> || - || IT, MPTM || If there are more than 64 channels in the IT / MTPM format, this chunk contains the default panning, volume and flags for channels 65+. They are encoded the same way as in the IT header, except that volume and panning are stored in an interleaved way (i.e. volume for channel 65, pan for channel 65, volume for channel 66, ...)
|-
| <code>..MT</code> || uint32 || IT, MPTM, XM || Tempo Mode <ul> <li>0: classic</li> <li>1: alternative</li> <li>2: modern</li> </ul>
|-
| <code>.MMP</code> || uint32 || IT, MPTM, XM || Mix Levels <ul> <li>0: Original</li> <li>1: 1.17 RC1</li> <li>2: 1.17 RC2</li> <li>3: 1.17 RC3</li> <li>4: Compatible</li> <li>5: Compatible (FT2 Pan Law)</li> </ul>
|-
| <code>.VWC</code> || uint32 || IT, MPTM, XM || OpenMPT "Created With" version (e.g. OpenMPT 1.23.45.67 = 0x01234567)
|-
| <code>VWSL</code> || uint32 || IT, MPTM, XM || OpenMPT "Last Saved With" version
|-
| <code>.APS</code> || uint32 || IT, MPTM, XM || Sample Pre-Amp
|-
| <code>VTSV</code> || uint32 || IT, MPTM, XM || Synth Pre-Amp (VSTi / OPL)
|-
| <code>.VGD</code> || uint32 || XM || Global Volume (0...256)
|-
| <code>..PR</code> || uint16 || IT, MPTM || Restart Position
|-
| <code>RSMP</code> || uint32 || MPTM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>CUES</code> || - || MPTM || Sample cue points for a single sample (only MPTM format). The first uint16 in the chunk indicates for which sample slot the cue points are meant. The rest of the chunk contains all cue points as uint32s. If this chunk is missing for a particular sample slot, OpenMPT assumes the default cue points for this slot. In this case, the i-th cue point can be computed as i × 2048.
|-
| <code>SWNG</code> || - || MPTM || Contains tempo swing factors (only MPTM format). The first uint16 in the chunk indicates the number of swing rows. The rest of the chunk contains all swing factors as uint32s. A factor of 16777216 (224) is considered to be unity, i.e. does not modify the row duration. After loading, the number of swing factors must be resized to the actual number of rows per beat (in case of malformed file) and re-normalized.
|-
| <code>.FSM</code> || - || IT, MPTM, XM || A bit field of generic compatibility flags. For modules made with OpenMPT 1.25 and older, the most important one is 0x01 (first bit set), which is IT-/XM-compatible playback mode. All other flags indicate which [[Manual: Compatible Playback#Playback Compatibility Settings|compatibility settings]] are toggled.
|-
| <code>AUTH</code> || uint8[] || IT, MPTM, XM || Song artist, as UTF-8 string
|-
| <code>AMIM</code> || - || IT, MPTM, XM || MIDI Mapping settings
|-
| <code>CCOL</code> || rgbx[] || IT, MPTM, XM || Channel colors. The chunk size divided by 4 indicates the number of channels present. Format is [R, G, B, 0] for channels that have a color assigned, or [x, x, x, non-zero] for a channel with no color.
|}

== MPTM Extensions ==

=== Detecting an MPTM file ===

There are two types of hacked IT files: In early versions of the MPTM format (used in OpenMPT 1.17.02.4x), the <code>IMPM</code> magic bytes are replaced by <code>tpm.</code>, so they are not backwards compatible. Newer MPTM files use the original magic, but use a <code>cwtv</code> value between 0889h and 0FFFh (inclusive) in the header.

In both cases, the last four bytes of the file point to the start of the MPTM extensions. If the magic bytes "228" can be found at this start position, it is a valid MPTM file.

=== 228 Extensions ===

228 Extensions have been used since OpenMPT 1.17.02.48 r192 for features that are only available in the MPTM format,
such as Custom Tunings, Multiple Sequences, and Parameter Control notes.

They are documented [[Development:_228_Extensions|here]].

=== External Samples ===

MPTM files can reference external samples. If the <code>cvt</code> value in the sample header is 80h, then the sample is external. In this case, the sample pointer does not point to actual sample data but to a filename:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || VarInt || Length of the filename
|-
| ? || char[] || Filename (UTF-8, not null-terminated)
|}

Note that only the sample waveform must be loaded, but not its metadata: Frequency, loop points, volume, panning, auto-vibrato etc. must be read from the IT file. If the sample length according to the IT header is shorter than the actual sample, the sample data must be trimmed, too.

External samples are used exactly the same way in ITI files.

=== OPL Instruments ===

MPTM files can make use of OPL instruments, just like S3M files. Unlike in S3M files, patch data is not stuffed into the sample header but stored as regular sample data. To tell OPL patches apart from regular samples, the <code>cvt</code> value in the sample header is set to 40h. Note that the check for this flag must be an equal comparison (<code>cvt == 40h</code>), not a bitwise AND, due to ModPlug's legacy ADPCM sample <code>cvt</code> type (FFh). Any combination with other <code>cvt</code> flags is also considered to be illegal.

OPL2 patches are stored in the same order as in S3M files, i.e. interleaved modulator and carrier bytes, with the last (12th) byte being unused and set to 0.

=== Order list (old) ===

If the <code>cwtv</code> is between 088Bh and 088Dh (inclusive), the order list at the start of the file is replaced by the following struct:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint16 || Version of the order list. Only version 0 is defined. Reject any other values.
|-
| 2 || uint32 || Number of items in the order list
|-
| 6 || uint32[] || The order list, as a series of uint32 values. The number of values is determined by the previous field.
|}

=== Custom Tunings (old) ===

This section is for OpenMPT versions before 1.17.02.48 r192. For newer versions, check [[Development:_228_Extensions|228 Extensions]].

Before OpenMPT 1.17.02.48 r192, the only feature that was only available in the MPTM format was Custom Tunings.
MPTM files that were made before r192 have a <code>cwtv</code> value between 0x0888 and 0x088C (inclusive).

These MPTM files contain a "Tuning Collection" chunk that contains all the custom tunings that are specific to the song (called "Tune specific tunings" in OpenMPT),
which is right after the OpenMPT song extensions.
It is then followed by a "Tuning Map" that determines which tuning each instrument should use.

A Tuning Collection could also exist separately in a <code>.TC</code> file, that can be exported/imported into an MPTM file in the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In an MPTM file, the last four bytes pointed to the start of the "Tune specific tunings" Tuning Collection,
similar to how they point to the start of 228 extensions in newer (<code>cwtv</code> > 0x088C) MPTM files.

==== Tuning Collection structure ====

The structure of a Tuning Collection is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| char[4]
| Tuning Collection beginning signature: <code>HSCT</code> (4 bytes)
|-
| int32
| Tuning Collection version: Always 1 or 2. 
|-
| uint8 or uint32
| Length of the Tuning Collection's name. 
Data type:
* uint8 if the Tuning Collection version is 2.
* uint32 if the Tuning Collection version is 1.

|-
| char[]
| Tuning Collection name. The current version of OpenMPT reads a maximum of 256 (0x100) characters. 
If the collection is in a TC file, its name is the same as what it was in OpenMPT when the TC file was exported. 
But in MPTM files, only the tune-specific tuning collection is stored, and its name is always <code>Tune specific tunings</code>.
|-
| int16
| Tuning Collection edit mask. 
A set of 16 bits that was used to specify which settings of the tunings can be changed, but is no longer used in newer versions of OpenMPT.

|-
| uint32
| Number of tunings in the collection. The current version of OpenMPT does not load custom tunings at all if the number of tunings in an MPTM file is greater than 50.
|-
| (custom structure)
| The tunings in this collection, stored right after each other. The structure of a tuning is described below.
|-
| char[4]
| Tuning Collection end signature: <code>FSCT</code> (4 bytes)
|}

==== Tuning structure ====

The structure of a Custom Tuning is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| char[8]
| Tuning beginning signature: <code>CTRTI_B.</code> (8 bytes)
|-
| int16
| Tuning version: Always 2 or 3. 
|-
| char[8]
| Tuning SFS chunk beginning signature: <code>CT<sfs>B</code> (8 bytes)
|-
| int16
| Tuning SFS chunk version: Always 3 or 4. 
|-
| uint8 or uint32
| Length of the tuning's name. 
Data type:
* uint8 if the SFS chunk version is 4.
* uint32 if the SFS chunk version is 3.

|-
| char[]
| Tuning name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|-
| int16
| Tuning edit mask. 
A set of 16 bits that was used to specify which settings of the tuning can be changed, but is no longer used in newer versions of OpenMPT.

|-
| int16
| Tuning type.
* 0: Generic
* 1: Group-geometric (originally called "Ratio-periodic")
* 3: Geometric (originally called "TET")
Newer versions of OpenMPT that use the new tuning format will convert old Geometric tunings to Group-geometric for compatibility reasons.
|-
| uint16 or uint32
| Size of the tuning's note name map. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. 
Data type:
* uint16 if the SFS chunk version is 4.
* uint32 if the SFS chunk version is 3.

|-
| (custom structure)
| The tuning's note name map. Contains the names of notes that have custom names. The structure is described in further below.
|-
| char[8]
| Tuning SFS chunk end signature: <code>CT<sfs>E</code> (8 bytes)
|-
| uint16 or uint32
| Size of the tuning's ratio table. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. This value is usually set to 256 (or 0 if the ratio table is unneeded). 
Data type:
* uint16 if the tuning version is 3.
* uint32 if the tuning version is 2.

|-
| float32[]
| The tuning's ratio table. Contains the frequency ratios for every note. If all ratios are 1, the ratio table is unneeded, so its size would be 0. 
Unlike the newer tuning format that uses 228 extensions, this table contains ratios for every note in every group, regardless of the tuning type.
|-
| uint16 or uint32
| Finetune steps. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. 
Data type:
* uint16 if the tuning version is 3.
* uint32 if the tuning version is 2.

|-
| float32[]
| An array of finetune step ratios, containing the same number of values as the finetune steps value. 
The first value is 1, and each value is r(1/finetunesteps) times the previous value, 
where r is the ratio of note 1 (the note after the middle note) to note 0 (the middle note). 
This table no longer exists in the newer tuning format that uses 228 extensions.
|-
| int16
| First note index in the ratio table. Usually set to -128. 
The current version of OpenMPT rejects values smaller than -200 and greater than 200.
|-
| int16
| Group size. 
For generic tunings, this value is 0.
|-
| float32
| Group ratio. 
For generic tunings, this value is 0.
|-
| char[8]
| Tuning end signature: <code>CTRTI_E.</code> (8 bytes)
|}

Many of the values that are stored for each tuning are redundant.
For example, the ratio table contains ratios for every note, regardless of the tuning type, even though it makes sense to
only have ratios for a single group in group-geometric tunings, and to not be stored at all in geometric tunings.
But they still have to be stored for these old versions of OpenMPT to work correctly.
However, these redundancies no longer exist in the newer tuning format that uses 228 extensions.

==== Tuning note name map structure ====

The structure of a single entry in the note name map is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| int16
| Note number.
|-
| uint8 or uint32
| Length of the note name. 
Data type:
* uint8 if the tuning's SFS chunk version is 4.
* uint32 if the tuning's SFS chunk version is 3.

|-
| char[]
| Note name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|}

This structure is stored for every note that has a custom name.

For geometric and group-geometric tunings, only the notes of a single group, where the note numbers are between 0 and groupsize-1 (inclusive).
The note names for that single group are then applied to every group (group/octave numbers are not a part of the note name).

==== Tuning Map structure ====

The structure of a tuning map is identical to that of the new 228 tuning format (documented [[Development:_228_Extensions#Tuning_Map|here]]), but with a difference if the <code>cwtv</code> value is 0x088B or older:

The number of tunings in the map and the length of the tuning names in the map are both stored as uint32 instead of uint16 and uint8 respectively.

== RIFF WAVE ==

OpenMPT uses its own <code>xtra</code> chunk in RIFF WAVE files to store some sample properties which could otherwise not be represented in the format.

Its layout is as follows:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint32 || Sample flags (0x20: Default panning is enabled)
|-
| 4 || uint16 || Default panning (0...256)
|-
| 6 || uint16 || Default volume (0...256)
|-
| 8 || uint16 || Global volume (0...64)
|-
| 10 || uint16 || (Reserved, must be 0)
|-
| 12 || uint8 || Auto-vibrato type 
|-
| 13 || uint8 || Auto-vibrato sweep
|-
| 14 || uint8 || Auto-vibrato depth
|-
| 15 || uint8 || Auto-vibrato rate
|}

Optionally, when copying a sample to the system clipboard, the sample name (32 characters, null-padded) and filename (22 characters, null-padded) follow.

== FLAC ==

Since the FLAC format has no native and standardized way to store loop information, OpenMPT follows Renoise′s way of storing loop information: FLAC supports application-defined metadata, so OpenMPT writes a metadata block with application ID <code>riff</code>. The block contains a <code>smpl</code> chunk (as defined in the [https://www.mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/RIFFNEW.pdf RIFF specification]). Similarly, extended sample properties are stored in another <code>riff</code> application block contaning the OpenMPT-specific <code>[[#RIFF WAVE|xtra]]</code> chunk, and sample cue points are stored in a <code>cue </code> chunk.

OpenMPT also reads and writes the following non-standard Vorbis comments:
* '''SAMPLERATE''': Contains the sample rate (as text) in case it would exceed the maximum sample rate supported by the FLAC format, 1,048,575 Hz (655350 Hz for older versions).
* '''LOOPSTART''': The start of the sample loop in frames. This tag is only read, not written.
* '''LOOPLENGTH''': The length of the sample loop in frames. This tag is only read, not written.

[[Category:Development|OpenMPT Format Extensions]]

Development: Formats/IT

2024-05-02T19:48:40Z

CS127: /* ModPlug Tracker */ fix another typo

General information concerning the IT file format. Any variable names in this document refer to the original variable names from [https://github.com/schismtracker/schismtracker/wiki/ITTECH.TXT ITTECH.TXT]. Variable names and hexadecimal numbers (in little-endian formats) are indicated by a <tt>monospace font</tt>.

Note: Impulse tracker is now open source! You can grab the [https://github.com/sagamusix/impulsetracker source code] at GitHub.

== Tracker IDs ==

The IT header contains a field, <tt>Cwt/v</tt>, which is used to identify the application that was used to create the file.
The following custom tracker IDs (read as little-endian hexadecimal numbers) are known to be found in the <tt>Cwt/v</tt> field:

* <tt>0xyy</tt> - Impulse Tracker x.yy - Many other trackers, like ModPlug Tracker, disguise as various versions of Impulse Tracker, so this is not a reliable way to tell if a file was really made with Impulse Tracker. See [[#Detecting other trackers|below]] for detecting such trackers.
* <tt>1xyy</tt> - Schism Tracker x.yy up to Schism Tracker v0.50, later versions encode a timestamp in the version number - see Schism Tracker’s <tt>[https://github.com/schismtracker/schismtracker/blob/master/schism/version.c version.c]</tt> or OpenMPT’s <tt>[https://source.openmpt.org/browse/openmpt/trunk/OpenMPT/soundlib/Load_it.cpp Load_it.cpp]</tt> for a version not relying on the C runtime library (since <tt>localtime</tt> is not guaranteed to be thread-safe).
* <tt>4xyy</tt> - pyIT x.yy
* <tt>5xyy</tt> - OpenMPT x.yy - lower two bytes of version number are stored in the "reserved" header field starting from OpenMPT 1.29.10.00 in compatible mode (otherwise OpenMPT song extensions are used as before).
* <tt>6xyy</tt> - BeRoTracker x.yy
* <tt>7xyz</tt> - ITMCK x.y.z (N.B. the user can override the value of the <tt>Cwt/v</tt> header by the <tt>-w</tt> command-line switch or the <tt>#TRACKER-VERSION</tt> command in the input file)
* <tt>7FFF</tt>, <tt>Cmwt = 0215</tt>: munch.py
* <tt>8xyy</tt> - Tralala x.yy; prealpha versions, built from svn, before the first release identify as version 0.00 (i.e. Cwt/v=8000)
* <tt>Cxyy</tt> - ChickDune ChipTune Tracker x.yy (currently non-public alpha version)
* <tt>DAEB</tt> - spc2it (after commit d3d1b524032f668be8ee20d25339e1c635fb9bcf)

Are you a tracker developer and your tracker can save IT files? Please add your Tracker ID to this list!

Once we run out of tracker IDs, a more sophisticated approach will have to be found. For example, the ID <tt>0FFF</tt> could be reserved, and a pointer to extended tracker information could be placed in the <tt>reserved</tt> header field.

== Detecting other trackers ==

Some trackers disguise as Impulse Tracker 2, but there are ways to uncover this diguise:

=== BeRoTracker ===

Earlier versions of BeRoTracker, which did not use the tracker ID described above, can be identified by the four byte <tt>MODU</tt> magic which can be found after the Edit History / MIDI Macro / ModPlug extension block. <tt>Cwt/v</tt> is <tt>0217</tt> and <tt>Cmwt</tt> is <tt>0214</tt> or <tt>0200</tt> (overlaps with ModPlug Tracker). The edit history flag is set and there are always 0 entries in the edit history.

=== CheeseTracker ===

* <tt>Cwt/v</tt> and <tt>Cmwt</tt> are both <tt>0214</tt>
* Instrument mode flag is always set. The only other flags that can be optionally set are: Stereo Mode, Linear Slides, Old Effects, Compatible Gxx.
* The only <tt>special</tt> flag ever set is the song message flag (even though row highlights are always written).
* <tt>reserved</tt> is <tt>0</tt>
* All sample and instrument filenames read <tt>XXXXXXXX.YYY</tt> (obviously this should not be used as a stand-alone detection criterion, as files re-saved with other trackers will still use these filenames).

=== ChibiTracker ===

<tt>Cwt/v</tt> and <tt>Cmwt</tt> are both <tt>0214</tt>, <tt>reserved</tt> reads <tt>CHBI</tt>.

Further interesting criteria: Sample data is stored directly after header. All sample and instrument filenames read <tt>-DEPRECATED-</tt> (obviously this should not be used as a stand-alone detection criterion, as files re-saved with other trackers will still use these filenames). ChibiTracker also uses a line feed character (<tt>0A</tt> or <tt>\n</tt>) instead of a carriage return (<tt>0D</tt> or <tt>\r</tt>) in the song message.

=== ModPlug Tracker ===

* '''ModPlug Tracker 1.0 pre-alpha 4 (and possibly earlier) - 1.0 alpha 4''': <tt>Cwt/v</tt> is <tt>0202</tt>, <tt>Cmwt</tt> is <tt>0200</tt>, <tt>reserved</tt> is <tt>0</tt>, row highlights are both 0. These attributes alone are not enough to fingerprint these ModPlug Tracker versions, but luckily it also stores the remaining data in a very peculiar order: patterns first, then instrument headers, and then interleaves sample headers and their corresponding sample data. These versions also do not optimize empty 64-row patterns with a 0 parapointer, so they can be identified by checking if the first pattern parapointer is not 0 and less than the first sample parapointer.
* '''ModPlug Tracker 1.0 alpha 5''': <tt>Cwt/v</tt> is <tt>0214</tt>, <tt>Cmwt</tt> is <tt>0200</tt>, <tt>reserved</tt> is <tt>0</tt>. Pattern highlights and edit history flags are not set. Instruments are 560 bytes apart.
* '''ModPlug Tracker 1.0 alpha 6 / beta 1 / beta 2''': <tt>Cwt/v</tt> is <tt>0214</tt>, <tt>Cmwt</tt> is <tt>0200</tt>, <tt>reserved</tt> is <tt>0</tt>. Pattern highlights and edit history flags are set. Instruments are 560 bytes apart up to and including beta 1, in beta 2 they are 557 bytes apart.
* '''ModPlug Tracker 1.0 beta 3.2 - 1.07''': <tt>Cwt/v</tt> is <tt>0214</tt>, <tt>Cmwt</tt> is <tt>0202</tt>, <tt>reserved</tt> is <tt>0</tt>. Instruments are 557 bytes apart.
* Newer versions of '''ModPlug Tracker''', '''OpenMPT 1.17 in compatible mode''': <tt>Cwt/v</tt> is <tt>0217</tt>, <tt>Cmwt</tt> is <tt>0200</tt>, <tt>reserved</tt> is <tt>0</tt>. If there are any instruments in the file, the instrument <tt>TrkVers</tt> field is <tt>0211</tt> for ModPlug Tracker and <tt>0220</tt> for OpenMPT. ModPlug Tracker writes <tt>FF</tt> for unused channels in the panning map, OpenMPT never does this. When an IT file uses all 64 channels (so the panning map cannot be used for distinction), the presence of ModPlug extensions (channel names, plugin chunks, etc.) can help telling MPT 1.16 and OpenMPT 1.17 compatibility export apart. The latter also does not save a final "---" order list item, while MPT 1.16 does.

=== OpenMPT ===

* OpenMPT 1.17.02.20 to OpenMPT 1.17.02.25 wrote the value <tt>0300</tt> in both the <tt>Cwt/v</tt> and <tt>Cmwt</tt> fields.
* OpenMPT 1.17.02.26 to OpenMPT 1.18 wrote the value <tt>0888</tt> in both the <tt>Cwt/v</tt> and <tt>Cmwt</tt> fields.
* Later versions of OpenMPT use the tracker ID provided above. In that case, the <tt>reserved</tt> field reads <tt>OMPT</tt> if the file was saved in normal mode, and is <tt>0</tt> (or the lower two bytes of version information starting from OpenMPT 1.29.10.00) if it was saved in compatible mode.

=== OpenSPC conversions ===

OpenSPC is a tool to convert SNES music from the SPC format to the IT format. If all the following conditions are true, you can be fairly sure that a module was written with OpenSPC:
* <tt>Cwt/v</tt> is <tt>0214</tt>.
* <tt>Cmwt</tt> is <tt>0200</tt>.
* <tt>Flags</tt> is <tt>09</tt> (Linear Slides, Stereo Playback).
* <tt>Special</tt> is <tt>0</tt>.
* Both pattern highlight values are <tt>00</tt>.
* No instruments are used.
* <tt>PatNum</tt> + 1 == <tt>OrdNum</tt>.
* Global volume is 128 decimal.
* Master volume is 100 decimal.
* Initial Speed is 1.
* Pan Separation is 128 decimal.
* Pitch wheel depth is 0.
* There is no song message, i.e. message length and offset are 0.
* <tt>reserved</tt> is 0.

Earlier versions of spc2it (before commit d3d1b524032f668be8ee20d25339e1c635fb9bcf) will be mis-identified as OpenSPC, as the tool closely follows the way its predecessor writes out IT files.

=== Unknown XM to IT conversion tool ===

There is a currently unknown XM to IT conversion tool which can be identified easily by the fact that it writes unsigned samples (which was the default only until Impulse Tracker 2.01). However, only sample slots with actual sample data should be considered for this test, as re-saving such a file in Impulse Tracker will not reset the unsigned flag for empty slots. If the following conditions are true, you can be fairly sure that a module was written with the unknown converter:
* <tt>Cwt/v</tt> is <tt>0204</tt>.
* <tt>Cmwt</tt> is <tt>0200</tt>.
* <tt>Flags</tt>: Stereo Playback, Instrument Mode, Old Effects are always set, Linear Slides are optional.
* <tt>Special</tt> is <tt>0</tt>.
* Both pattern highlight values are <tt>0</tt>.
* Global volume is 128 decimal.
* Master volume is 48 decimal.
* Pan Separation is 128 decimal.
* Pitch wheel depth is 0.
* There is no song message, i.e. message length and offset are 0.
* <tt>reserved</tt> is 0.
* Song title is no longer than 20 characters.
* All channels are panned centre (32) or muted, and their volume is 64 decimal.

To be extra sure, you can check all of these properties, but just checking <tt>Cwt/v</tt>, <tt>Cmwt</tt> and unsigned sample data is probably enough.

=== UNMO3 ===

UNMO3 is a tool to convert an MO3-compressed module file back into its original format.

In IT files created with UNMO3, the following are always true:

* <tt>Cwt/v</tt> and <tt>Cmwt</tt> are <tt>0214</tt>
* <tt>reserved</tt> is <tt>0</tt>
* <tt>pwd</tt> is 0
* Both row highlights are 0
* Flags: Use MIDI Pitch Controller (bit 6) and Request embedded MIDI configuration (bit 7) are never set

This partially overlaps with Impulse Tracker 2.14 and CheeseTracker fingerprints, however:
* CheeseTracker should write non-zero row highlights, even when resaving an UNMO3-ed file.
* It is highly unlikely that Impulse Tracker 2.14 writes a <tt>reserved</tt> value of <tt>0</tt>. If it writes zero row highlights, the row highlight <tt>special</tt> flag is set.
* Impulse Tracker 2.14 never writes an empty edit history (see below).
* CheeseTracker always uses instrument mode.

Some older versions of UNMO3 write out IT files that are malformed in some way or another, but it is easy to detect and work around. Some UNMO3-ed IT files are floating around in the wild, so it may be worthwile to implement those work-arounds:

==== Special flags prior UNMO3 2.4.0.2 ====

* UNMO3 2.4 (released in 2008) and older sets the <tt>special</tt> flag bits 1 (edit history) and 2 (row highlights) whenever bit 3 (MIDI macros) is set as well.
* UNMO3 2.4.0.1 (January 2011) always sets the <tt>special</tt> flag bit 1 (edit history), but the behaviour for bit 2 (row highlights) remains as in previous versions.
* UNMO3 2.4.0.2 (July 2011) never sets the row highlights flag.

==== Sample mode prior to UNMO3 2.4.0.1 ====

UNMO3 2.4 and older reserves space for the instrument parapointers (as many as there are samples) even when the IT file is in sample mode. This can be detected by the fact that 4 * <tt>SmpNum</tt> zero bytes follow after the pattern parapointers. These bytes need to be skipped in order to be able to read MIDI macros and ModPlug plugin settings which may potentially follow.

UNMO3 2.4.0.1 fixes this problem.

==== Edit History prior to UNMO3 2.4.0.1 ====

As mentioned above, UNMO3 older than version 2.4.0.1 may or may not set the edit history flag, but they always write two edit history length bytes (zeroes) in the file anyway. Keep this in mind, as MIDI Macros and ModPlug plugin settings will not load properly if you don’t.

* '''Edit history flag is set''': Nothing needs to be done. We can still use this for identifying UNMO3-saved IT files, because Impulse Tracker never writes an edit history of length 0.
* '''Edit history flag is not set''': This is the troublesome case due to MIDI macros and plugin settings. However, a reliable way to detect such malformed IT files would be to try to read the edit history length if all of the above detection criteria for UNMO3 are fulfilled. For those old UNMO3 versions, you should read two zero bytes. If that is the case, it means that the first MIDI macro would be empty (if MIDI macros are embedded) or the first plugin chunk ID starts with two zero bytes (impossible). Since UNMO3 writes out default values for the nine global MIDI macros, the first MIDI macro would have to start with “FF” (MIDI Start) and not be empty, so it is clear that the two zero bytes belong to the (empty) edit history.

Later version of UNMO3 set the correct header flag for the edit history and write the two zero length bytes.

== Special Header Flags ==

The following "Special" flags are not documented:

* Bit 1 (<tt>02</tt>): If set, edit history information (see [[#Edit History|below]]) is present.
* Bit 2 (<tt>04</tt>): If set, the row highlights (at offset <tt>1E</tt> - <tt>1F</tt>) should be read. If not set, they should be ignored.

== Edit History ==

It is little known that the latest versions of Impulse Tracker keep track of when an IT file is opened and how long it is left open.
The edit history can be found directly after the IT header and before the possibly present MIDI macro configuration.

A 16-Bit integer <tt>num</tt> tells how many edit history blocks are present. Every block is 8 bytes long, so the 16-bit integer is followed by <tt>8 * num</tt> bytes of edit history information.

Each history block consists of a 16-Bit FAT date, a 16-Bit FAT time and a 32-Bit DOS timer, which contains the time how long the file was open in the editor, in 1/18.2th seconds.
Information on how to decode the FAT date and time stamps can be found on the [https://msdn.microsoft.com/en-us/library/windows/desktop/ms724247%28v=vs.85%29.aspx MSDN].

Note: Many programs don’t write an edit history, but they set the edit history flag in the header and write the two zero bytes for the history length. Many of them also ignore the edit history flag when loading files and always read the two <tt>num</tt> num bytes (ignoring the special flag), so if you want to write out an IT file that does not have an edit history and do not mind about the two extra bytes, the safest (most compatible) way is to set the edit history flag and write two zero bytes for <tt>num</tt>.

Also note that none of this is really relevant if you are sure that you never write out the MIDI macro configuration or ModPlug extensions, since these are the only two things that could normally follow the edit history. So if you have no MIDI macros and no ModPlug extensions, it is always safe to not set the special flag and not write the two extra bytes.

== Edit Timer ==

Before the addition of the full Edit History, a simple Edit Timer was stored in the <tt>reserved</tt> field of the file header. Starting from Impulse Tracker 2.07, this field contains the total edit time as a 32-Bit DOS timer (same resolution as in the Edit History). Starting from Impulse Tracker 2.08, the timer is encrypted. To decrypt:

editTime = editTime XOR 'ITRK'
editTime = editTime RoR 7
editTime = -editTime
editTime = editTime RoL 4
editTime = editTime XOR 'JTHL'

== Proposed way to store compressed stereo samples ==

Since Impulse Tracker itself does not support stereo samples, a common way of how to decode compressed stereo samples had to be found - After all, it is possible to just treat them as one continuous stream (not stopping the encoding / decoding process after the end of the left channel), or to treat them as two separate, consecutive streams. XMPlay was probably the only player that could handle compressed stereo samples even before there was a single implementation for saving compressed stereo samples. GreaseMonkey has decided to follow [https://www.un4seen.com/forum/?topic=12448.msg86479#msg86479 XMPlay's way] of decoding compressed stereo samples by treating them as two streams of the same length, so OpenMPT follows this example. If you intend to add IT sample compression support in your application, you should do the same to ensure compatibility across as many applications as possible.

== OpenMPT Hacks ==

For a list of all the file format hacks that ModPlug Tracker / OpenMPT added to the IT format over the years, see the [[Development: OpenMPT Format Extensions|OpenMPT Format Extensions]] article.

[[Category:Development|Formats/IT]]
[[Category:IT Format|Format Specification]]

Development: Formats/IT

2024-05-02T19:45:40Z

CS127: fix typo

General information concerning the IT file format. Any variable names in this document refer to the original variable names from [https://github.com/schismtracker/schismtracker/wiki/ITTECH.TXT ITTECH.TXT]. Variable names and hexadecimal numbers (in little-endian formats) are indicated by a <tt>monospace font</tt>.

Note: Impulse tracker is now open source! You can grab the [https://github.com/sagamusix/impulsetracker source code] at GitHub.

== Tracker IDs ==

The IT header contains a field, <tt>Cwt/v</tt>, which is used to identify the application that was used to create the file.
The following custom tracker IDs (read as little-endian hexadecimal numbers) are known to be found in the <tt>Cwt/v</tt> field:

* <tt>0xyy</tt> - Impulse Tracker x.yy - Many other trackers, like ModPlug Tracker, disguise as various versions of Impulse Tracker, so this is not a reliable way to tell if a file was really made with Impulse Tracker. See [[#Detecting other trackers|below]] for detecting such trackers.
* <tt>1xyy</tt> - Schism Tracker x.yy up to Schism Tracker v0.50, later versions encode a timestamp in the version number - see Schism Tracker’s <tt>[https://github.com/schismtracker/schismtracker/blob/master/schism/version.c version.c]</tt> or OpenMPT’s <tt>[https://source.openmpt.org/browse/openmpt/trunk/OpenMPT/soundlib/Load_it.cpp Load_it.cpp]</tt> for a version not relying on the C runtime library (since <tt>localtime</tt> is not guaranteed to be thread-safe).
* <tt>4xyy</tt> - pyIT x.yy
* <tt>5xyy</tt> - OpenMPT x.yy - lower two bytes of version number are stored in the "reserved" header field starting from OpenMPT 1.29.10.00 in compatible mode (otherwise OpenMPT song extensions are used as before).
* <tt>6xyy</tt> - BeRoTracker x.yy
* <tt>7xyz</tt> - ITMCK x.y.z (N.B. the user can override the value of the <tt>Cwt/v</tt> header by the <tt>-w</tt> command-line switch or the <tt>#TRACKER-VERSION</tt> command in the input file)
* <tt>7FFF</tt>, <tt>Cmwt = 0215</tt>: munch.py
* <tt>8xyy</tt> - Tralala x.yy; prealpha versions, built from svn, before the first release identify as version 0.00 (i.e. Cwt/v=8000)
* <tt>Cxyy</tt> - ChickDune ChipTune Tracker x.yy (currently non-public alpha version)
* <tt>DAEB</tt> - spc2it (after commit d3d1b524032f668be8ee20d25339e1c635fb9bcf)

Are you a tracker developer and your tracker can save IT files? Please add your Tracker ID to this list!

Once we run out of tracker IDs, a more sophisticated approach will have to be found. For example, the ID <tt>0FFF</tt> could be reserved, and a pointer to extended tracker information could be placed in the <tt>reserved</tt> header field.

== Detecting other trackers ==

Some trackers disguise as Impulse Tracker 2, but there are ways to uncover this diguise:

=== BeRoTracker ===

Earlier versions of BeRoTracker, which did not use the tracker ID described above, can be identified by the four byte <tt>MODU</tt> magic which can be found after the Edit History / MIDI Macro / ModPlug extension block. <tt>Cwt/v</tt> is <tt>0217</tt> and <tt>Cmwt</tt> is <tt>0214</tt> or <tt>0200</tt> (overlaps with ModPlug Tracker). The edit history flag is set and there are always 0 entries in the edit history.

=== CheeseTracker ===

* <tt>Cwt/v</tt> and <tt>Cmwt</tt> are both <tt>0214</tt>
* Instrument mode flag is always set. The only other flags that can be optionally set are: Stereo Mode, Linear Slides, Old Effects, Compatible Gxx.
* The only <tt>special</tt> flag ever set is the song message flag (even though row highlights are always written).
* <tt>reserved</tt> is <tt>0</tt>
* All sample and instrument filenames read <tt>XXXXXXXX.YYY</tt> (obviously this should not be used as a stand-alone detection criterion, as files re-saved with other trackers will still use these filenames).

=== ChibiTracker ===

<tt>Cwt/v</tt> and <tt>Cmwt</tt> are both <tt>0214</tt>, <tt>reserved</tt> reads <tt>CHBI</tt>.

Further interesting criteria: Sample data is stored directly after header. All sample and instrument filenames read <tt>-DEPRECATED-</tt> (obviously this should not be used as a stand-alone detection criterion, as files re-saved with other trackers will still use these filenames). ChibiTracker also uses a line feed character (<tt>0A</tt> or <tt>\n</tt>) instead of a carriage return (<tt>0D</tt> or <tt>\r</tt>) in the song message.

=== ModPlug Tracker ===

* '''ModPlug Tracker 1.0 pre-alpha 4 (and possibly earlier) - 1.0 alpha 4''': <tt>Cwt/v</tt> is <tt>0202</tt>, <tt>Cmwt</tt> is <tt>0200</tt>, <tt>reserved</tt> is <tt>0</tt>, row highlights are both 0. These attributes alone are not enough to fingerprint these ModPlug Tracker versions, but luckily it also stores the remaining data in a very peculiar order: patterns first, then instrument headers, and then interleaves sample headers and their corresponding sample data. These versions also do not optimize empty 64-row patterns with a 0 parapointer, so they can be identified by checking if the first pattern parapointer is not 0 and less than the first sample parapointer.
* '''ModPlug Tracker 1.0 alpha 5''': <tt>Cwt/v</tt> is <tt>0214</tt>, <tt>Cmwt</tt> is <tt>0200</tt>, <tt>reserved</tt> is <tt>0</tt>. Pattern highlights and edit history flags are not set. Instruments are 560 bytes apart.
* '''ModPlug Tracker 1.0 alpha 6 / beta 1 / beta 2''': <tt>Cwt/v</tt> is <tt>0214</tt>, <tt>Cmwt</tt> is <tt>0200</tt>, <tt>reserved</tt> is <tt>0</tt>. Pattern highlights and edit history flags are set. Instruments are 560 bytes apart up to and including beta 1, in beta 2 they are 557 bytes apart.
* '''ModPlug Tracker 1.0 beta 3.2 - 1.07''': <tt>Cwt/v</tt> is <tt>0214</tt>, <tt>Cmwt</tt> is <tt>0202</tt>, <tt>reserved</tt> is <tt>0</tt>. Instruments are 557 bytes apart.
* Newer versions of '''ModPlug Tracker''', '''OpenMPT 1.17 in compatible mode''': <tt>Cwt/v</tt> is <tt>0217</tt>, <tt>Cmwt</tt> is <tt>0200</tt>, <tt>reserved</tt> is <tt>0</tt>. If there are any instruments in the file, the instrument <tt>TrkVers</tt> field is <tt>0211</tt> for ModPlug Tracker and <tt>0220</tt> for OpenMPT. ModPlug Tracker writes <tt>FF</tt> for unused channels in the panning map, OpenMPT never does this. When an IT file uses all 64 channels (so the panning map cannot be used for distinction), the presence of ModPlug extensions (channel names, plugin chunks, etc.) can help telling MPT 1.16 and OpenMPT 1.17 compatibility export apart. The latter also does not save a final "---" oder list item, while MPT 1.16 does.

=== OpenMPT ===

* OpenMPT 1.17.02.20 to OpenMPT 1.17.02.25 wrote the value <tt>0300</tt> in both the <tt>Cwt/v</tt> and <tt>Cmwt</tt> fields.
* OpenMPT 1.17.02.26 to OpenMPT 1.18 wrote the value <tt>0888</tt> in both the <tt>Cwt/v</tt> and <tt>Cmwt</tt> fields.
* Later versions of OpenMPT use the tracker ID provided above. In that case, the <tt>reserved</tt> field reads <tt>OMPT</tt> if the file was saved in normal mode, and is <tt>0</tt> (or the lower two bytes of version information starting from OpenMPT 1.29.10.00) if it was saved in compatible mode.

=== OpenSPC conversions ===

OpenSPC is a tool to convert SNES music from the SPC format to the IT format. If all the following conditions are true, you can be fairly sure that a module was written with OpenSPC:
* <tt>Cwt/v</tt> is <tt>0214</tt>.
* <tt>Cmwt</tt> is <tt>0200</tt>.
* <tt>Flags</tt> is <tt>09</tt> (Linear Slides, Stereo Playback).
* <tt>Special</tt> is <tt>0</tt>.
* Both pattern highlight values are <tt>00</tt>.
* No instruments are used.
* <tt>PatNum</tt> + 1 == <tt>OrdNum</tt>.
* Global volume is 128 decimal.
* Master volume is 100 decimal.
* Initial Speed is 1.
* Pan Separation is 128 decimal.
* Pitch wheel depth is 0.
* There is no song message, i.e. message length and offset are 0.
* <tt>reserved</tt> is 0.

Earlier versions of spc2it (before commit d3d1b524032f668be8ee20d25339e1c635fb9bcf) will be mis-identified as OpenSPC, as the tool closely follows the way its predecessor writes out IT files.

=== Unknown XM to IT conversion tool ===

There is a currently unknown XM to IT conversion tool which can be identified easily by the fact that it writes unsigned samples (which was the default only until Impulse Tracker 2.01). However, only sample slots with actual sample data should be considered for this test, as re-saving such a file in Impulse Tracker will not reset the unsigned flag for empty slots. If the following conditions are true, you can be fairly sure that a module was written with the unknown converter:
* <tt>Cwt/v</tt> is <tt>0204</tt>.
* <tt>Cmwt</tt> is <tt>0200</tt>.
* <tt>Flags</tt>: Stereo Playback, Instrument Mode, Old Effects are always set, Linear Slides are optional.
* <tt>Special</tt> is <tt>0</tt>.
* Both pattern highlight values are <tt>0</tt>.
* Global volume is 128 decimal.
* Master volume is 48 decimal.
* Pan Separation is 128 decimal.
* Pitch wheel depth is 0.
* There is no song message, i.e. message length and offset are 0.
* <tt>reserved</tt> is 0.
* Song title is no longer than 20 characters.
* All channels are panned centre (32) or muted, and their volume is 64 decimal.

To be extra sure, you can check all of these properties, but just checking <tt>Cwt/v</tt>, <tt>Cmwt</tt> and unsigned sample data is probably enough.

=== UNMO3 ===

UNMO3 is a tool to convert an MO3-compressed module file back into its original format.

In IT files created with UNMO3, the following are always true:

* <tt>Cwt/v</tt> and <tt>Cmwt</tt> are <tt>0214</tt>
* <tt>reserved</tt> is <tt>0</tt>
* <tt>pwd</tt> is 0
* Both row highlights are 0
* Flags: Use MIDI Pitch Controller (bit 6) and Request embedded MIDI configuration (bit 7) are never set

This partially overlaps with Impulse Tracker 2.14 and CheeseTracker fingerprints, however:
* CheeseTracker should write non-zero row highlights, even when resaving an UNMO3-ed file.
* It is highly unlikely that Impulse Tracker 2.14 writes a <tt>reserved</tt> value of <tt>0</tt>. If it writes zero row highlights, the row highlight <tt>special</tt> flag is set.
* Impulse Tracker 2.14 never writes an empty edit history (see below).
* CheeseTracker always uses instrument mode.

Some older versions of UNMO3 write out IT files that are malformed in some way or another, but it is easy to detect and work around. Some UNMO3-ed IT files are floating around in the wild, so it may be worthwile to implement those work-arounds:

==== Special flags prior UNMO3 2.4.0.2 ====

* UNMO3 2.4 (released in 2008) and older sets the <tt>special</tt> flag bits 1 (edit history) and 2 (row highlights) whenever bit 3 (MIDI macros) is set as well.
* UNMO3 2.4.0.1 (January 2011) always sets the <tt>special</tt> flag bit 1 (edit history), but the behaviour for bit 2 (row highlights) remains as in previous versions.
* UNMO3 2.4.0.2 (July 2011) never sets the row highlights flag.

==== Sample mode prior to UNMO3 2.4.0.1 ====

UNMO3 2.4 and older reserves space for the instrument parapointers (as many as there are samples) even when the IT file is in sample mode. This can be detected by the fact that 4 * <tt>SmpNum</tt> zero bytes follow after the pattern parapointers. These bytes need to be skipped in order to be able to read MIDI macros and ModPlug plugin settings which may potentially follow.

UNMO3 2.4.0.1 fixes this problem.

==== Edit History prior to UNMO3 2.4.0.1 ====

As mentioned above, UNMO3 older than version 2.4.0.1 may or may not set the edit history flag, but they always write two edit history length bytes (zeroes) in the file anyway. Keep this in mind, as MIDI Macros and ModPlug plugin settings will not load properly if you don’t.

* '''Edit history flag is set''': Nothing needs to be done. We can still use this for identifying UNMO3-saved IT files, because Impulse Tracker never writes an edit history of length 0.
* '''Edit history flag is not set''': This is the troublesome case due to MIDI macros and plugin settings. However, a reliable way to detect such malformed IT files would be to try to read the edit history length if all of the above detection criteria for UNMO3 are fulfilled. For those old UNMO3 versions, you should read two zero bytes. If that is the case, it means that the first MIDI macro would be empty (if MIDI macros are embedded) or the first plugin chunk ID starts with two zero bytes (impossible). Since UNMO3 writes out default values for the nine global MIDI macros, the first MIDI macro would have to start with “FF” (MIDI Start) and not be empty, so it is clear that the two zero bytes belong to the (empty) edit history.

Later version of UNMO3 set the correct header flag for the edit history and write the two zero length bytes.

== Special Header Flags ==

The following "Special" flags are not documented:

* Bit 1 (<tt>02</tt>): If set, edit history information (see [[#Edit History|below]]) is present.
* Bit 2 (<tt>04</tt>): If set, the row highlights (at offset <tt>1E</tt> - <tt>1F</tt>) should be read. If not set, they should be ignored.

== Edit History ==

It is little known that the latest versions of Impulse Tracker keep track of when an IT file is opened and how long it is left open.
The edit history can be found directly after the IT header and before the possibly present MIDI macro configuration.

A 16-Bit integer <tt>num</tt> tells how many edit history blocks are present. Every block is 8 bytes long, so the 16-bit integer is followed by <tt>8 * num</tt> bytes of edit history information.

Each history block consists of a 16-Bit FAT date, a 16-Bit FAT time and a 32-Bit DOS timer, which contains the time how long the file was open in the editor, in 1/18.2th seconds.
Information on how to decode the FAT date and time stamps can be found on the [https://msdn.microsoft.com/en-us/library/windows/desktop/ms724247%28v=vs.85%29.aspx MSDN].

Note: Many programs don’t write an edit history, but they set the edit history flag in the header and write the two zero bytes for the history length. Many of them also ignore the edit history flag when loading files and always read the two <tt>num</tt> num bytes (ignoring the special flag), so if you want to write out an IT file that does not have an edit history and do not mind about the two extra bytes, the safest (most compatible) way is to set the edit history flag and write two zero bytes for <tt>num</tt>.

Also note that none of this is really relevant if you are sure that you never write out the MIDI macro configuration or ModPlug extensions, since these are the only two things that could normally follow the edit history. So if you have no MIDI macros and no ModPlug extensions, it is always safe to not set the special flag and not write the two extra bytes.

== Edit Timer ==

Before the addition of the full Edit History, a simple Edit Timer was stored in the <tt>reserved</tt> field of the file header. Starting from Impulse Tracker 2.07, this field contains the total edit time as a 32-Bit DOS timer (same resolution as in the Edit History). Starting from Impulse Tracker 2.08, the timer is encrypted. To decrypt:

editTime = editTime XOR 'ITRK'
editTime = editTime RoR 7
editTime = -editTime
editTime = editTime RoL 4
editTime = editTime XOR 'JTHL'

== Proposed way to store compressed stereo samples ==

Since Impulse Tracker itself does not support stereo samples, a common way of how to decode compressed stereo samples had to be found - After all, it is possible to just treat them as one continuous stream (not stopping the encoding / decoding process after the end of the left channel), or to treat them as two separate, consecutive streams. XMPlay was probably the only player that could handle compressed stereo samples even before there was a single implementation for saving compressed stereo samples. GreaseMonkey has decided to follow [https://www.un4seen.com/forum/?topic=12448.msg86479#msg86479 XMPlay's way] of decoding compressed stereo samples by treating them as two streams of the same length, so OpenMPT follows this example. If you intend to add IT sample compression support in your application, you should do the same to ensure compatibility across as many applications as possible.

== OpenMPT Hacks ==

For a list of all the file format hacks that ModPlug Tracker / OpenMPT added to the IT format over the years, see the [[Development: OpenMPT Format Extensions|OpenMPT Format Extensions]] article.

[[Category:Development|Formats/IT]]
[[Category:IT Format|Format Specification]]

Development: 228 Extensions

2023-02-28T18:14:13Z

CS127:

This document is for OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). For older versions, check [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

The MPTM format is nearly identical to the IT format. The only difference is that OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings, and to specify that a file is in the MPTM format in the first place (otherwise it would be detected as IT).

This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions).

The chunk contains settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

Other MPTM features (e.g. fractional tempos) use [[Development:_OpenMPT_Format_Extensions|regular OpenMPT extensions]].

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format, '''even floating-point numbers'''):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit (single-precision) IEEE-754 floating-point number.
* <code>char</code>: a text character (text encoding may vary, so a single character is not necessarily one byte).
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned little-endian integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit width (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the least significant bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length ('''in bytes, not characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, "Windows codepage" refers to the user's selected ACP codepage in Windows (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to [[Wikipedia:Windows-1252|1252]], but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and a map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specify what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, unless the chunk has a "flag byte" (explained later) and its bit 0 is set.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether this chunk's descriptions (explained later) use a fixed 16-bit encoding (e.g. [[Wikipedia:Universal_Coded_Character_Set|UCS-2]]) instead of a fixed 8-bit encoding (e.g. [[Wikipedia:ISO/IEC_8859-1|ISO-8859-1]] / [[Wikipedia:Windows-1252|Windows-1252]]).
* Bit 7: whether this chunk's map contains descriptions for each entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, the string uses use a fixed 16-bit encoding (e.g. [[Wikipedia:Universal_Coded_Character_Set|UCS-2]]) instead of a fixed 8-bit encoding (e.g. [[Wikipedia:ISO/IEC_8859-1|ISO-8859-1]] / [[Wikipedia:Windows-1252|Windows-1252]]). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk. 
The current version of OpenMPT always writes this adaptive integer in two bytes, even if it only needs one. 
Additionally, this causes OpenMPT to be unable to write chunks with more than 16383 entries.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not). 
The current version of OpenMPT always writes this adaptive integer in eight bytes, even if it needs fewer bytes.
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''. Otherwise, they have to be stored in the same order that OpenMPT reads them.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, the string uses a fixed 16-bit encoding (e.g. [[Wikipedia:Universal_Coded_Character_Set|UCS-2]]) instead of a fixed 8-bit encoding (e.g. [[Wikipedia:ISO/IEC_8859-1|ISO-8859-1]] / [[Wikipedia:Windows-1252|Windows-1252]]). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to a 228 chunk with an ID of <code>mptm</code>, which contains all the settings for MPTM features (like custom tunings) in its entries. OpenMPT writes this chunk after the OpenMPT song extensions, and before the last four bytes of the file that specify its position.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the 8-bit Windows codepage.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code>, stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: Windows codepage.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk.

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code>.
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code>.

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>UTF8</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code>.

==== Tuning ====

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>.
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code>.

The chunk's version number is 67108868 (<code>0x04000004</code>).

These custom tuning chunks can also exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>UTF8</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name ('''in bytes, not characters''').
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the <code>mptm</code> chunk, is <code>1</code>.

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>uint8</code>
| Length of the tuning's name ('''in bytes, not characters''').
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection (or "pattern container" according to the source code) is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code>.
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code>.

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is not readable as a string, but instead, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code>.

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>data</code>
| (custom structure)
| The extended pattern data, which will be merged onto the IT pattern data when the file is read. 
Technically, it can be used for storing any pattern data, but OpenMPT uses it for storing only the Parameter Control notes of each pattern.
The data is stored in the same format as the [https://github.com/schismtracker/schismtracker/wiki/ITTECH.TXT#impulse-pattern-format IT pattern format], but without the first 8 bytes, and with a different format for mask bytes: 
* Bit 0: Include note (OpenMPT only writes PC and PCs)
* Bit 1: Include plugin number (instrument number if not a PC/PCs note)
* Bit 2: Include high byte of controller ID (volume command type if not a PC/PCs note)
* Bit 3: Include low byte of controller ID (volume command parameter if not a PC/PCs note)
* Bit 4: Include high byte of parameter (effect command type if not a PC/PCs note)
* Bit 5: Include low byte of parameter (effect command parameter if not a PC/PCs note)
* Bit 6: Include extra data
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this entry, OpenMPT will read the order list from it, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code>.
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code>.

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>n</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code>.

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>u</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: Windows codepage.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code>.

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2023-02-23T10:52:23Z

CS127: /* Extended Pattern */ fix hyperlink

This document is for OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). For older versions, check [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

The MPTM format is nearly identical to the IT format. The only difference is that OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings, and to specify that a file is in the MPTM format in the first place (otherwise it would be detected as IT).

This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions).

The chunk contains settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

Other MPTM features (e.g. fractional tempos) use [[Development:_OpenMPT_Format_Extensions|regular OpenMPT extensions]].

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character (text encoding may vary, so a single character is not necessarily one byte).
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned little-endian integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit width (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the least significant bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length ('''in bytes, not characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, "Windows codepage" refers to the user's selected ACP codepage in Windows (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to [[Wikipedia:Windows-1252|1252]], but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and a map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specify what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, unless the chunk has a "flag byte" (explained later) and its bit 0 is set.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether this chunk's descriptions (explained later) use a fixed 16-bit encoding (e.g. [[Wikipedia:Universal_Coded_Character_Set|UCS-2]]) instead of a fixed 8-bit encoding (e.g. [[Wikipedia:ISO/IEC_8859-1|ISO-8859-1]] / [[Wikipedia:Windows-1252|Windows-1252]]).
* Bit 7: whether this chunk's map contains descriptions for each entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, the string uses use a fixed 16-bit encoding (e.g. [[Wikipedia:Universal_Coded_Character_Set|UCS-2]]) instead of a fixed 8-bit encoding (e.g. [[Wikipedia:ISO/IEC_8859-1|ISO-8859-1]] / [[Wikipedia:Windows-1252|Windows-1252]]). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk. 
The current version of OpenMPT always writes this adaptive integer in two bytes, even if it only needs one. 
Additionally, this causes OpenMPT to be unable to write chunks with more than 16383 entries.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not). 
The current version of OpenMPT always writes this adaptive integer in eight bytes, even if it needs fewer bytes.
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, the string uses a fixed 16-bit encoding (e.g. [[Wikipedia:Universal_Coded_Character_Set|UCS-2]]) instead of a fixed 8-bit encoding (e.g. [[Wikipedia:ISO/IEC_8859-1|ISO-8859-1]] / [[Wikipedia:Windows-1252|Windows-1252]]). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to a 228 chunk with an ID of <code>mptm</code>, which contains all the settings for MPTM features (like custom tunings) in its entries. OpenMPT writes this chunk after the OpenMPT song extensions, and before the last four bytes of the file that specify its position.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the 8-bit Windows codepage.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code>, stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: Windows codepage.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk.

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code>.
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code>.

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>UTF8</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code>.

==== Tuning ====

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>.
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code>.

The chunk's version number is 67108868 (<code>0x04000004</code>).

These custom tuning chunks can also exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>UTF8</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name ('''in bytes, not characters''').
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the <code>mptm</code> chunk, is <code>1</code>.

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>uint8</code>
| Length of the tuning's name ('''in bytes, not characters''').
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection (or "pattern container" according to the source code) is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code>.
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code>.

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is not readable as a string, but instead, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code>.

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>data</code>
| (custom structure)
| The extended pattern data, which will be merged onto the IT pattern data when the file is read. 
Technically, it can be used for storing any pattern data, but OpenMPT uses it for storing only the Parameter Control notes of each pattern.
The data is stored in the same format as the [https://github.com/schismtracker/schismtracker/wiki/ITTECH.TXT#impulse-pattern-format IT pattern format], but without the first 8 bytes, and with a different format for mask bytes: 
* Bit 0: Include note (OpenMPT only writes PC and PCs)
* Bit 1: Include plugin number (instrument number if not a PC/PCs note)
* Bit 2: Include high byte of controller ID (volume command type if not a PC/PCs note)
* Bit 3: Include low byte of controller ID (volume command parameter if not a PC/PCs note)
* Bit 4: Include high byte of parameter (effect command type if not a PC/PCs note)
* Bit 5: Include low byte of parameter (effect command parameter if not a PC/PCs note)
* Bit 6: Include extra data
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this entry, OpenMPT will read the order list from it, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code>.
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code>.

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>n</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code>.

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>u</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: Windows codepage.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code>.

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2023-02-23T10:42:30Z

CS127: small improvements

This document is for OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). For older versions, check [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

The MPTM format is nearly identical to the IT format. The only difference is that OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings, and to specify that a file is in the MPTM format in the first place (otherwise it would be detected as IT).

This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions).

The chunk contains settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

Other MPTM features (e.g. fractional tempos) use [[Development:_OpenMPT_Format_Extensions|regular OpenMPT extensions]].

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character (text encoding may vary, so a single character is not necessarily one byte).
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned little-endian integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit width (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the least significant bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length ('''in bytes, not characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, "Windows codepage" refers to the user's selected ACP codepage in Windows (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to [[Wikipedia:Windows-1252|1252]], but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and a map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specify what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, unless the chunk has a "flag byte" (explained later) and its bit 0 is set.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether this chunk's descriptions (explained later) use a fixed 16-bit encoding (e.g. [[Wikipedia:Universal_Coded_Character_Set|UCS-2]]) instead of a fixed 8-bit encoding (e.g. [[Wikipedia:ISO/IEC_8859-1|ISO-8859-1]] / [[Wikipedia:Windows-1252|Windows-1252]]).
* Bit 7: whether this chunk's map contains descriptions for each entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, the string uses use a fixed 16-bit encoding (e.g. [[Wikipedia:Universal_Coded_Character_Set|UCS-2]]) instead of a fixed 8-bit encoding (e.g. [[Wikipedia:ISO/IEC_8859-1|ISO-8859-1]] / [[Wikipedia:Windows-1252|Windows-1252]]). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk. 
The current version of OpenMPT always writes this adaptive integer in two bytes, even if it only needs one. 
Additionally, this causes OpenMPT to be unable to write chunks with more than 16383 entries.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not). 
The current version of OpenMPT always writes this adaptive integer in eight bytes, even if it needs fewer bytes.
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, the string uses a fixed 16-bit encoding (e.g. [[Wikipedia:Universal_Coded_Character_Set|UCS-2]]) instead of a fixed 8-bit encoding (e.g. [[Wikipedia:ISO/IEC_8859-1|ISO-8859-1]] / [[Wikipedia:Windows-1252|Windows-1252]]). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to a 228 chunk with an ID of <code>mptm</code>, which contains all the settings for MPTM features (like custom tunings) in its entries. OpenMPT writes this chunk after the OpenMPT song extensions, and before the last four bytes of the file that specify its position.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the 8-bit Windows codepage.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code>, stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: Windows codepage.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk.

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code>.
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code>.

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>UTF8</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code>.

==== Tuning ====

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>.
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code>.

The chunk's version number is 67108868 (<code>0x04000004</code>).

These custom tuning chunks can also exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>UTF8</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name ('''in bytes, not characters''').
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the <code>mptm</code> chunk, is <code>1</code>.

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>uint8</code>
| Length of the tuning's name ('''in bytes, not characters''').
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection (or "pattern container" according to the source code) is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code>.
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code>.

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is not readable as a string, but instead, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code>.

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>data</code>
| (custom structure)
| The extended pattern data, which will be merged onto the IT pattern data when the file is read. 
Technically, it can be used for storing any pattern data, but OpenMPT uses it for storing only the Parameter Control notes of each pattern.
The data is stored in the same format as the [[https://github.com/schismtracker/schismtracker/wiki/ITTECH.TXT#impulse-pattern-format|IT pattern format]], but without the first 8 bytes, and with a different format for mask bytes: 
* Bit 0: Include note (OpenMPT only writes PC and PCs)
* Bit 1: Include plugin number (instrument number if not a PC/PCs note)
* Bit 2: Include high byte of controller ID (volume command type if not a PC/PCs note)
* Bit 3: Include low byte of controller ID (volume command parameter if not a PC/PCs note)
* Bit 4: Include high byte of parameter (effect command type if not a PC/PCs note)
* Bit 5: Include low byte of parameter (effect command parameter if not a PC/PCs note)
* Bit 6: Include extra data
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this entry, OpenMPT will read the order list from it, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code>.
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code>.

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>n</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code>.

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Datatype
! Content
|-
| <code>u</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: Windows codepage.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code>.

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-10-15T13:11:54Z

CS127: fixed some issues

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character (text encoding may vary, so a single character is not necessarily one byte).
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned little-endian integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit width (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the least significant bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length ('''in bytes, not characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and a map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specify what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, unless the chunk has a "flag byte" (explained later) and its bit 0 is set.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for each entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk. 
The current version of OpenMPT always writes this adaptive integer in two bytes, even if it only needs one. 
Additionally, this causes OpenMPT to be unable to write chunks with more than 16383 entries.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not). 
The current version of OpenMPT always writes this adaptive integer in eight bytes, even if it needs fewer bytes.
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to a 228 chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries. OpenMPT writes this chunk after the OpenMPT song extensions, and before the last four bytes of the file that specify its position.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk.

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name ('''in bytes, not characters''').
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the <code>mptm</code> chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name ('''in bytes, not characters''').
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (<code>6E 75 6D</code> in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this entry, OpenMPT will read the order list from it, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the <code>mptSeqC</code> chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Manual: Hidden Settings

2022-08-12T17:04:48Z

CS127: /* [Broken Plugin Workarounds] */ fixed a typo

[[Image:Settings Advanced.png|thumb|300px|Advanced tab of the settings dialog]]

Some settings for advanced users cannot be changed directly in OpenMPT, however they can be changed by modifying OpenMPT’s configuration file, mptrack.ini, or from the [[Manual:_Setup/Advanced|Advanced Settings]]. When using the latter method, it might be necessary to restart OpenMPT for some options to take effect.

== [Broken Plugin Workarounds] ==
* '''VSTMaskAllCrashes''': Determines whether crashes in VST plugins should be reported to the user (1) or passed on to the system, i.e. OpenMPT crashes (0). Note that if a plugin crashed, its internal state or even OpenMPT’s state may be inconsistent, so in this situation it is best to close and reopen the tracker anyway.
* '''VSTNeverUnloadAnyPlugin''': If set to 1, VST plugins are not fully unloaded when closing them. This may help with some buggy plugins (e.g. made with older versions of SynthEdit 1.4). Do not enable this setting unless you have issues when unloading plugins that cannot be solved by using the plugin bridge.

== [Components] ==
* '''BlockASIO''', '''BlockPortAudio''', '''BlockRtAudio''', '''BlockWaveOut''': If set to 1, the respective sound device types do not get initialized or queried by OpenMPT. You should not need to disable any of these unless told to do so by the OpenMPT developers in order to diagnose problems.
* '''BlockMediaFoundation''': If set to 1, OpenMPT will not load any samples using MediaFoundation codecs.
* '''BlockWineWrapper''': If set to 1, OpenMPT will not load the Wine native audio wrapper.
* '''KeepLoaded''': If set to 0, optional OpenMPT components (e.g. MP3 codecs) are unloaded after usage. This frees up memory used by these components but slows down subsequent uses.
* '''LoadOnStartUp''': If set to 1, some optional components are loaded right on statup instead of when they are first used.

== [Debug] ==
Options in this section should generally only be changed if you are advised by an OpenMPT developer to do so.
* '''DelegateToWindowsHandler''': If set to 1, OpenMPT will invoke the Windows default crash handler after its own crash handler has finished generating the crash report which had been the behaviour in OpenMPT before 1.27.
* '''StopSoundDeviceBeforeDump''': By default, the sound device is closed after writing out a crash dump. Setting this option to 1 inverts the behaviour.
* '''StopSoundDeviceOnCrash''': If set to 0, OpenMPT will not close or otherwise touch the state of the sound device when writing out a crash dump. Only change this setting when asked by the OpenMPT developers to do so in order to diagnose sound device related crashes.
* '''TraceAlwaysDump''': If set to 1 and '''TraceEnable''' is also set to 1, OpenMPT will always write out the trace log on program exit even if no crash happened. Do not enable this setting unless you are advised by the developers to do so.
* '''TraceEnable''': If set to 1, a trace logging system is enabled which can be used by the OpenMPT developers to debug certain problems. Do not enable this setting unless you are advised by the developers to do so.
* '''TraceSize''': Configures the tracer buffer size. By default, it contains 1,000,000 entries.

== [Display] ==
* '''FSUpdateInterval''': OpenMPT watches the '''f'''ile '''s'''ystem in order to update the [[Manual:_Tree_View#Instrument_Library|instrument library]] tree view when files get added or removed to the directory while OpenMPT is running. This setting limits the rate of the GUI updates in these cases to the given value in milliseconds. The default is 500ms.
* '''GUIUpdateInterval''': Defines the update interval of the GUI in milliseconds (default: depends on the period value found in the sound card settings).
* '''HighResUI''': If enabled, OpenMPT reports itself to Windows as a DPI-aware application. This setting might have to be disabled if you are using a high-DPI screen in combination with VST plugins that do not have a DPI-aware user interface.
* '''ShowSplashScreen''': If set to 0, no splash screen is shown when starting the program (same effect as [[Manual: Command-line Parameters|command line option]] /NoLogo).
* '''VuMeterUpdateInterval''': Defines the update interval of the VU meters in milliseconds (default: 15ms).
* '''VuMeterDecaySpeedDecibelPerSecond ''': Sets the VU meter's decay speed The default value is 88 dB/s.

== [Export] ==
* '''DefaultToSoundcardSamplerate''': By default, the [[Manual: Saving and exporting#Exporting tracks|export dialog]] presets the export frequency to the tracker’s currently selected sample rate. One reason for this behaviour is that some plugins do not like it when the sample rate is changed between normal playback and export. If you do not like this behaviour, you can set this value to 0. In this case, OpenMPT remembers the previously selected sample rate instead.
* '''FLACCompressionLevel''': When [[Manual: Saving and exporting#Exporting tracks|exporting]] to FLAC format, this value sets the FLAC compression level. Higher values mean better compression ratio and require more CPU time. For details, please refer to the FLAC documentation.
* '''MP3ID3v2MinPadding''': This value is the minimum amount of padding bytes to add to ID3v2 tags.
* '''MP3ID3v2PaddingAlignHint''': This aligns the MP3 data after the ID3v2 tag in addition to the minimum padding to a multiple of the configured value. Set to 0 to disable additional aligning.
* '''MP3ID3v2WriteReplayGainTXXX''': Write ReplayGain information (if calculated, see '''MP3LameCalculateReplayGain''' and '''MP3LameCalculatePeakSample''') to the ID3v2 tag. This setting defaults to 1.
* '''MP3LameCalculateReplayGain''' and '''MP3LameCalculatePeakSample''': When [[Manual: Saving and exporting#Exporting tracks|exporting]] to MP3 format, calculate the ReplayGain track gain adjustment and the peak sample value (as require by ReplaGain) respectively. The calculated values get written to the VBR/Lame info header automatically in VBR mode. Additionally, the values can be written to the ID3v2 tags when enabled (see '''MP3ID3v2WriteReplayGainTXXX'''). Both settings default to 1.
* '''MP3LameID3v2UseLame''': If set to 1, when [[Manual: Saving and exporting#Exporting tracks|exporting]] to MP3 format, uses the libmp3lame ID3v2.3 implementation instead of the OpenMPT ID3v2.4 implementation. ID3v2.3 is more widely supported by older player software.
* '''MP3LameQuality''': When [[Manual: Saving and exporting#Exporting tracks|exporting]] to MP3 format using libmp3lame, this value selects the internal algorithm quality used by LAME. Lower values mean better quality and require more CPU time. This is the same as the -q command line parameter for LAME. More details can be found e.g. on [http://wiki.hydrogenaud.io/index.php?title=LAME_-q_switch Hydrogenaudio].
* '''OpusComplexity''': When [[Manual: Saving and exporting#Exporting tracks|exporting]] to Opus format, this value selects the internal complexity used by libopus. Higher values mean better encoding efficiency and require more CPU time. Value -1 uses the libopus default value. For details, please refer to the [https://opus-codec.org/docs/ libopus documentation].

== [MIDI Input Ports] ==
In this section, you can set “friendly names” for all MIDI input ports. If you have lots of MIDI ports with undescriptive names (such as “MIDI Device Port 1”, “MIDI Device Port 2”, …), it can be useful to replace those names with more suitable names, e.g. to describe which device is connected to a specific port. To replace a name, add a pair like <code>MIDI Device Port 1=Synthesizer 1</code> to this section.

Friendly names are also recognized by the MIDI Input / Output plugin: If the selected ports have friendly names assigned when the module is saved, the next time is opened it will try to find the correct device by its friendly name. So if a MIDI device is connected to a different MIDI port, you can rename the ports and OpenMPT will automatically choose the correct port.

== [MIDI Output Ports] ==
Same as [[#.5BMIDI Input Ports.5D|[MIDI Input Ports]]], but for MIDI output ports.

== [Misc] ==
* '''AllowMultipleCommandsPerKey''': By default, a key combination can be used by only one command. Setting this to 1 allows you to bind more than one command to a key combination. Beware that this might lead to problems with existing keyboard mappings with overlapping commands!
* '''CacheCompleteFileBeforeLoading''': If set to 1, OpenMPT caches entire (module, instrument, etc.) files in memory, which may improve file reading performance at the expense of more memory being used.
* '''DistinguishModifiers''': Enable this option to distinguish between left and right <kbd>Ctrl</kbd> / <kbd>Alt</kbd> / <kbd>Shift</kbd> modifiers, e.g. to create FastTracker 2-like pattern play shortcuts.
* '''FlushFileBuffersOnSave''': Disabling this option avoids flushing of file buffers after saving modules, samples and other files on disk. This can speed up the write operation but increases the risk of data loss e.g. in case of a power failure.
* '''ITCompressionMono''': Enables IT-compressed mono samples when saving IT/MPTM files, depending on the value. To enable saving for normal IT files, add 1 to the value, for IT files saved through Compatibility Export, add 2, and for MPTM files add 4. So to enable saving of compressed samples in compatible ITs and MPTMs only, you would use the value 6. Some caveats regarding the usage of compressed samples have been written down on the [https://forum.openmpt.org/index.php?topic=4961.0 forum].
* '''ITCompressionStereo''': Enables IT-compressed stereo samples when saving IT/MPTM files, depending on the value (see above).
* '''MRUListLength''': Sets the maximum length of the most recently used file list in the file menu. Allowed values are between 0 (no list) and 15 entries.
* '''ProcessPriorityClass''': Set the Windows process priority class for OpenMPT. Possible values are: "idle", "below", "normal", "above", "high", "realtime". The default is "normal". See further discussion on the [https://forum.openmpt.org/index.php?topic=5655.0 forum]. '''Warning''': Changing this setting can cause system lockups requiring hard system reset.
* '''SaveChannelMuteStatus''': If set to 0, OpenMPT will not save the channel mute status in IT, MPTM and S3M files.
* '''SmoothFT2Ramping''': If set to 1, XM files made with Fasttracker 2 will automatically use [[Manual:_Compatible_Playback#XM_compatibility_settings|very smooth sample ramping]] settings (like Fasttracker 2 did).
* '''UseSingleInstance''': Always forces OpenMPT to only use a single program instance, even when the '''/shared''' command line switch is not specified.

== [Paths] ==
* '''Export_Directory''': The default export directory for lossless and lossy audio export. OpenMPT always uses the last used directory for exporting, so changing this setting does not make a lot of sense.
* '''UseAppDataDirectory''': This is a legacy setting imported from portable OpenMPT installations prior to version 1.29. If <code>mptrack.ini</code> is found next to <code>OpenMPT.exe</code> and this value is to 0, portable mode is assumed and all other configuration files are searched directly in the same directory as OpenMPT’s executable (by default they are placed in %APPDATA%\OpenMPT). When upgrading to a newer OpenMPT version, this setting is automatically converted to the new way of enabling portability. See also: [[Manual: System Setup#Portability|System Setup]].

== [Pattern Editor] ==
* '''AccessibilityFormat''': Defines the description of the pattern editor that can be obtained by screen readers. The string may contain the following variables: <code>%sequence%</code>, <code>%order%</code>, <code>%pattern%</code>, <code>%row%</code>, <code>%channel%</code>, <code>%channel_name%</code>, <code>%column_type%</code>, <code>%column_description%</code>.
* '''AlwaysDrawWholePatternOnScrollSlow''': If set to 1, OpenMPT will always repaint the whole pattern display instead of re-using parts of the window that have only moved and not changed. This will be measurably slower, however in some situation the display will look broken otherwise (like jittering play cursor, not updating regions of the pattern display properly when switching to and from the window, or generally sluggish/jerky display). The problem is related to certain graphics drivers (known examples are systems with multiple AMD GPUs in Windows 7, Windows XP in VirtualBox, and all Wine systems). By default, this setting is 0. On Wine, this setting has no effect and is treated as always 1, regardless of its actual value.
* '''DefaultSequenceMargins''': Defines how many order items are shown at least before and after the currently selected order item (0 by default).
* '''EditStepAppliesToCommands''': When set to 1, the edit step setting is also applied when entering a command into the volume or effect column.
* '''FontDot''': Overriding this setting allows to specify a custom character to be used for empty cells with user-configured pattern fonts.
* '''NoEditPopup''': Disables the reminder popup when trying to edit patterns while editing is disabled and treats all channel columns like the note column to simplify jamming (keyjazz).
* '''OrderListOldDropBehaviour''': Restores pre-OpenMPT 1.29 drag & drop behaviour in the order list editor. That is, patterns are always dropped left of the drop position, even if the drop position is right of the source.
* '''RowDisplayOffset''': Defines the displayed number of the first pattern row; by default, it is 0. This does not affect the Goto dialog or break commands in patterns.

== [Sound Settings] ==
* '''AllowDeferredProcessing''': If set to 0, deferred processing is never used for ASIO drivers.
* '''BoostedThreadPriority''': Set the priority (for Windows XP) used for sound devices which have "Boost thread priority" set. Possible values are -15,-2,-1,0,1,2,15 (or the full range -15..15 if [Misc]ProcessPriorityClass is set to "realtime"). Default value is 2. See further discussion on the [https://forum.openmpt.org/index.php?topic=5655.0 forum]. '''Warning''': Changing this setting can cause system lockups requiring hard system reset.
* '''BoostedThreadMMCSSClass''': Set the Multimedia Class Scheduler Service (MMCSS) class used for sound devices which have "Boost thread priority" set. Possible values are "Pro Audio", "Games", "Audio" or anything else that may be configured on your systems MMCSS. Default value is "Pro Audio". See further discussion on the [https://forum.openmpt.org/index.php?topic=5655.0 forum]. '''Warning''': Changing this setting can cause system lockups requiring hard system reset.
* '''MaskDriverCrashes''': If set to 1, OpenMPT will try ignore crashes in ASIO drivers.
* '''MixChannels''': Default is 256. The maximum number of sound channels that OpenMPT will use to render. In other words, Polyphony is the allowable number of notes that OpenMPT will process at once. Any computer that has been built in the last ten years should be able to handle the maximum amount of channels for most modules, but while older, low-end computers you will want to decrease the number of channels. Note that reducing the maximum polyphony only reduces the CPU load if those extra channels were actually used — if you play a 10-channel MOD file, it does matter little, if at all, whether the maximum polyphony is set to 16 or 256.
* '''ResamplerWFIRCutoff''': Configures the bandwidth of the audio signal that is retained by the 8-tap Sinc filter (without low-pass) in percent. The default of 97% offers a good compromise between “freshness” and quality of the resampled sound.
* '''SampleRates''': A comma-separated list of sample rates that OpenMPT will show in the sound device settings (if supported by the device) and when exporting a WAVE or FLAC file.
* '''XMMSModplugResamplerWFIRType''': Configures the windowing function of the 8-tap Sinc filter (without low-pass). The windowing functions, from 0 to 7, are: Hann, Hamming, Blackman Exact, Blackman 3-Tap 61, Blackman 3-Tap 67, Blackman-Harris, Blackman 4-Tap 74, Kaiser α=7.5

== [Update] ==
* '''SuggestDifferentBuildVariants''': By default, if the currently installed OpenMPT version is not optimal for the computer, it will suggest to install a different build variant. This check can be disabled by setting this variable to 0.

== [VST Plugins] ==
* '''BridgeAllPlugins''': All plugins are forced to be used through the integrated plugin bridge.
* '''EnableAutoSuspend''': Enables auto-suspend for all plugins newly added to modules after this setting is turned on. If a plugin did not emit any sound during the last four seconds, it is suspended until new notes or sound data are fed into the plugin.
* '''EnableMidiMappingInEditor''': If set to 0, holding <kbd>Shift</kbd> while modifying a plugin parameter does not open the [[Manual: MIDI Mapping|MIDI Mapping dialog]].
* '''HostProductString''': Here you can enter a custom host name that is sent to VST plugins. This can be useful if a plugin claims to only run in certain hosts and refuses to run in others.
* '''HostVendorString''': Here you can enter the host vendor name for the same reasons as above.
* '''HostVendorVersion''': Here you can enter the host version as a 32-Bit integer for the same reasons as above.
* '''ProjectPath''': Some plugins can store extra data alongside the module file. This behaviour can be overridden so that plugins use a different path. This setting can be either a normal absolute path or use the variables <code>%1</code> (module path) and <code>%2</code> (module filename) to build a path relative to the module location. So if all external plugin data should be stored in the folder <code>module.mptm-data</code> (assuming module.mptm is the module filename) next to the module, this value should be set to <code>%1%2-data</code>. Due to restrictions posed by the VST architecture, this path must not contain characters outside the current [https://en.wikipedia.org/wiki/Windows_code_page#ANSI Windows ANSI code page].

[[Category:Manual|Hidden Settings]]
[[de:Handbuch: Versteckte Optionen]]

Development: OpenMPT Format Extensions

2022-08-01T21:57:09Z

CS127: /* Tuning structure */ fixed code block

ModPlug Tracker and OpenMPT have extended the IT and XM formats in various ways. In general, these hacks are frowned upon, but here is some documentation on those hacks in case you want to support them in your own player. I am really sorry about all this mess, but all of this has grown historically way before I joined OpenMPT development.

Presence of these format extensions in a file does not necessarily imply that it was created with ModPlug Tracker or OpenMPT. Some of the extensions are also used e.g. by BeRoTracker.

Any numeric values are stored in little-endian format, unless noted otherwise.

Data types used in this document:
* uint8, uint16, uint32: Unsigned integers with the given bit width.
* int8, int16, int32: Signed integers with the given bit width.
* char: A single character (i.e. a byte)
* float32: Single precision IEEE float
* VarInt: A MIDI-like variable-length unsigned integer (big-endian value where the highest bit of each byte indicates if another byte follows, and the lower 7 bits containing the actual number).
* Square brackets [] denote an array of values:
** [] is a variable-length array (length is deduced from some other attribute)
** [42] denotes an array with 42 entries.

== ModPlug Song Extensions ==

The following extensions exist since the (closed-source) ModPlug Tracker days. These extensions are found in [https://en.wikipedia.org/wiki/Interchange_File_Format IFF]-like chunks, but without any padding bytes. The chunks are placed right after the header data in the IT format (i.e. after the edit history / MIDI macro block). In the XM format these chunks are placed right at the end of the file (i.e. after the sample data). At the time of writing, these chunks are always written out in the order described here, but if possible you should probably try to read them without expecting a certain order. All chunks are optional.

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint32 || Size of this chunk, excluding the header
|}

=== Chunks ===

==== text (XM only) ====

Contains the song message (CR line endings), its length is determined by the chunk size.

==== MIDI (XM only) ====

Contains the MIDI macro configuration, in the same format as in the IT format.

==== PNAM ====

Contains the pattern names. Each pattern name is 32 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The pattern names are stored continuously, i.e. there are (chunk size / 32) pattern names in the chunk, for pattern 0, pattern 1, ... pattern (chunk size / 32 - 1).

==== CNAM ====

Contains the channel names. Each channel name is 20 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The channel names are stored continuously, i.e. there are (chunk size / 20) channel names in the chunk, for channel 1, channel 2, ... channel (chunk size / 20).

==== CHFX ====

Contains the plugin assignment for each channel. For every channel, there is a 32-bit integer plugin index. 0 means no plugin, 1 is the first plugin, etc...

==== FX00, ... FX99, F100, ... F255 ====

Contains plugin information for each plugin slot. <code>FX00</code> contains the information for the first plugin slot, <code>FX99</code> for the 100th, <code>F100</code> for the 101st, etc...

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Plugin Type
<ul>
<li>VST plugins: <code>PtsV</code></li>
<li>DMO plugins: <code>OMXD</code></li>
</ul>
|-
| 4 || char[4] || Unique Plugin ID
|-
| 8 || uint8 || Routing Flags
<ul>
<li>0x01: Apply to master mix</li>
<li>0x02: Bypass effect</li>
<li>0x04: Wet Mix (dry added)</li>
<li>0x08: Expand Mix [0%,100%] → [-200%,200%]</li>
<li>0x10: Plugin will automatically suspend on silence</li>
</ul>
|-
| 9 || uint8 || Mix mode
<ul>
<li>0: normal processing</li>
<li>1: MIX += DRY - WET * wetRatio</li>
<li>2: MIX += WET - DRY * dryRatio</li>
<li>3: MIX -= WET - DRY * wetRatio</li>
<li>4: MIX -= middle - WET * wetRatio + middle - DRY</li>
<li>5: MIX_L += wetRatio * (WET_L - DRY_L) + dryRatio * (DRY_R - WET_R) MIX_R += dryRatio * (WET_L - DRY_L) + wetRatio * (DRY_R - WET_R)</li>
</ul>
|-
| 10 || uint8 || Gain Factor * 10 (9 = 90%, 10 = 100%, 11 = 110%, etc.). A value of 0 is equal to 10 (i.e. 100%).
|-
| 11 || uint8 || (Reserved)
|-
| 12 || uint32 || Output Routing (0 = send to master 0x80 + x = send to plugin x)
|-
| 16 || uint8[16] || (Reserved)
|-
| 32 || char[32] || User-chosen plugin name (Windows code page)
|-
| 64 || char[64] || Library name (Original DLL name / DMO identifier). UTF-8 (max. 64 bytes) since OpenMPT 1.22.07.01, Windows code page in older versions.
|-
| 128 || uint32 || Size of plugin-specific data in bytes (parameters or opaque chunk)
|-
| 132 || uint8 || Plugin-specific data
|}

The first four bytes of the plugin-specific data determine the type of data. If they are all 0, then the plugin parameters follow as an array of float32 values. Otherwise, plugin type specific data follows which should be treated as an opaque chunk. For example, for VST plugins that support the effGetChunk / effSetChunk chunk, the first four bytes will be "fEvN", followed by the data to be sent to the plugin.

After the plugin information described above, more information may follow in OpenMPT modules. This information is again stored in chunks. However, there are two legacy chunks which do not have any size stored alongside the chunk identifier:

{| class="wikitable"
|-
! FOURCC !! Data Type !! Description
|-
| <code>DWRT</code> || float32 || Dry/Wet Ratio of the plugin. This chunk does not denote its size!
|-
| <code>PROG</code> || uint32 || Default plugin program (preset) to restore. This chunk does not denote its size!
|}

Any chunks that will be added in the future will have proper IFF-like chunks with a 32-bit size field.

== ModPlug Instrument Extensions (IT only) ==

To be able to address more than 256 samples in the IT format, ModPlug Tracker has an extension to store the high byte of sample indices for the instrument sample map.

By default, the last four bytes of an IT instrument (right after the pitch envelope) are unused. If they read <code>MPTX</code> or <code>XTPM</code>, 120 extra bytes follow, one for each note in the sample map. These bytes are the high byte of the sample index, i.e. they need to be multiplied by 256 and then added to the already read sample index.

== OpenMPT Extensions (General Information) ==

In the XM format, OpenMPT instrument extensions may follow the ModPlug song extensions and may in return be followed by OpenMPT song extensions.

In the IT format, OpenMPT instrument extensions may follow the sample block and may in return be followed by OpenMPT song extensions.
This is very ugly, because there might not be any samples, in which case the last thing before the extension block would be the last pattern. If there are no patterns, the last thing before the extension block would be a sample header (at least one sample header will be present even if there is no sample data – but you may even want to cover the case where there are no sample headers, for being compatible with possible future changes). So you will somehow have to keep track of the highest offset you have read into the file. If the last sample is IT-compressed, things become even more complicated: There is no way to know the compressed size of a compressed sample, so in case you want to skip sample loading, and the last sample happens to be compressed, you can do the following:
Since we know that the extended instrument and song properties start right after the last sample, and since IT-compressed samples consist of chunks with a prepended 16-bit length field, you can simply read that 16-bit number, skip this amount of bytes, then check if you can read OpenMPT's <code>XTPM</code> or <code>STPM</code> magic bytes, and if not, read the next 16-bit length, skip the bytes, etc...

In pseudo code, finding the OpenMPT extensions in an IT / MPTM file could look somewhat like this:

''offset'' = 0
''lastSampleCompressed'' = false

// In case there are no patterns and no sample data (just empty sample slots):
if(number of samples > 0):
''offset'' = last sample header pointer + sizeof(ITSampleHeader)

for all samples:
if sample is not compressed or if samples are decoded:
''lastSampleCompressed'' = false
''offset'' = max(''offset'', pointer to sample data + sample size)
else if sample is compressed and samples are not decoded:
''lastSampleCompressed'' = true
''offset'' = max(''offset'', pointer to sample data)

// In case there is no sample data:
for all patterns:
''offset'' = max(''offset'', end of pattern data)

if ''lastSampleCompressed'':
while not eof:
if next four bytes are XTPM or STPM:
''chunkID'' = next four bytes
if ''chunkID'' only contains ASCII characters (all bytes are in 32…127)
''offset'' = current position - 4; break
else
skip back 8 bytes
read uint16 value and skip as many bytes

Try reading XTPM and STPM extensions at ''offset''

The provided data types are just for orientation, i.e. the minimum recommended field size for storing the values in memory. You must expect fields to have a different size, since sometimes they do so for historic reasons. Defensive programming is your friend. Most of the FOURCCs also just make sense when read backwards, again for historic reasons. Note that some of these extensions duplicate existing functionality of the IT/XM format. In this case, the extensions take precedence over the value previous found in the file.

== OpenMPT Instrument Extensions ==

Instrument extensions start with the <code>XTPM</code> magic bytes, but there is no size indication of the total size of this block. So you have to read the following chunks and as soon as you read the <code>STPM</code> magic bytes for a chunk, you know you have read to far and can continue with reading OpenMPT Song Extensions instead.

Instrument extensions are stored in a peculiar way: There is one chunk per property, and it contains the values for all instruments at once. The layout is as follows:

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint16 || Size of this chunk's entry '''for one instrument''' (i.e. total chunk content size is this field × number of instruments)
|}

=== Chunk Contents ===

The following instrument properties exist. Some of them are redundant depending on the file type and thus not present in all files. If they are redundant, they overwrite the values that were obtained from the format-specific structures.

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..OF</code> || uint32 || IT, MPTM, XM || Fade-out
|-
| <code>...P</code> || uint32 || IT, MPTM, XM || Panning (0...256)
|-
| <code>..EV</code> || uint32 || MPTM || Number of volume envelope nodes (if ≥ 25 nodes)
|-
| <code>..EP</code> || uint32 || MPTM || Number of pan envelope nodes (if ≥ 25 nodes)
|-
| <code>.EiP</code> || uint32 || MPTM || Number of pitch envelope nodes (if ≥ 25 nodes)
|-
| <code>..BM</code> || uint16 || IT, MPTM, XM || MIDI Bank
|-
| <code>..PM</code> || uint8 || IT, MPTM, XM || MIDI Program
|-
| <code>..CM</code> || uint8 || IT, MPTM, XM || MIDI Channel
|-
| <code>.[PV</code> || uint16[] || MPTM || Volume Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EV</code> || uint8[] || MPTM || Volume Envelope Values (if ≥ 25 nodes)
|-
| <code>.[PP</code> || uint16[] || MPTM || Pan Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EP</code> || uint8[] || MPTM || Pan Envelope Values (if ≥ 25 nodes)
|-
| <code>[PiP</code> || uint16[] || MPTM || Pitch Envelope Ticks (if ≥ 25 nodes)
|-
| <code>[EiP</code> || uint8[] || MPTM || Pitch Envelope Values (if ≥ 25 nodes)
|-
| <code>.PiM</code> || uint8 || IT, MPTM, XM || Plugin, 0 = no plugin, 1 = first plugin, etc.
|-
| <code>..RV</code> || uint16 || IT, MPTM, XM || Ramping / Attack
|-
| <code>...R</code> || uint8 || IT, MPTM, XM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>..SC</code> || uint8 || IT, MPTM, XM || Cutoff Swing
|-
| <code>..SR</code> || uint8 || IT, MPTM, XM || Resonance Swing
|-
| <code>..MF</code> || uint8 || IT, MPTM, XM || Filter Mode
|-
| <code>HEVP</code> || uint8 || IT, MPTM, XM || Plugin Velocity Handling
|-
| <code>HOVP</code> || uint8 || IT, MPTM, XM || Plugin Volume Handling
|-
| <code>NREV</code> || uint8 || IT, MPTM, XM || Volume Envelope Release Node
|-
| <code>NREA</code> || uint8 || IT, MPTM, XM || Pan Envelope Release Node
|-
| <code>NREP</code> || uint8 || IT, MPTM, XM || Pitch Envelope Release Node
|-
| <code>DWPM</code> || uint8 || IT, MPTM || Pitch Wheel Depth
|-
| <code>LTTP</code> || uint16 || IT, MPTM, XM || Integer part of Pitch / Tempo Lock
|-
| <code>PTTF</code> || uint16 || MPTM || Fractional part of Pitch / Tempo Lock (0...9999)
|}

=== Legacy Extension ===

But wait, there is more! Some really old OpenMPT versions (1.17 RC1 and older, but not 1.17 RC2) do not use the instrument extensions described above. However, they also need to store the plugin reference for each instrument, which is done in another modular block following each instrument header (and possibly the <code>MPTX</code> / <code>XTPM</code> extension of that instrument header).
If this legacy extension is present, the instrument header is followed by the magic bytes <code>MSNI</code> and an uint32 containing the modular data size.

Currently there is only one chunk in this modular data block. Its FOURCC is <code>GULP</code>, has no size information and contains an uint8 for the plugin index (0 = no plugin, 1 = first plugin, etc.).

== OpenMPT Song Extensions ==

Song extensions start with the <code>STPM</code> magic bytes, but there is no size indication of the total size of this block. In an IT / XM file, these extensions are the last chunks in the file, so you can continue reading until you are out of data. In the case of MPTM files, some further MPTM-specific data follows. This data starts with the bytes "228" followed by ASCII charater 4 (not the digit), so you can keep reading the song extensions until you read this FOURCC.

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint16 || Size of this chunk, excluding the header
|}

=== Chunk Contents ===

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..TD</code> || uint32 || IT, MPTM, XM || Integer part of the default tempo (required if it is larger than 255 in IT / MPTM, but also found in legacy XM files)
|-
| <code>DTFR</code> || uint32 || MPTM || Fractional part of the default tempo (0...9999)
|-
| <code>.BPR</code> || uint32 || IT, MPTM, XM || Rows Per Beat
|-
| <code>.MPR</code> || uint32 || IT, MPTM, XM || Rows Per Measure
|-
| <code>...C</code> || uint16 || IT, MPTM || Number of channels
|-
| <code>SnhC</code> || - || IT, MPTM || If there are more than 64 channels in the IT / MTPM format, this chunk contains the default panning, volume and flags for channels 65+. They are encoded the same way as in the IT header, except that volume and panning are stored in an interleaved way (i.e. volume for channel 65, pan for channel 65, volume for channel 66, ...)
|-
| <code>..MT</code> || uint32 || IT, MPTM, XM || Tempo Mode <ul> <li>0: classic</li> <li>1: alternative</li> <li>2: modern</li> </ul>
|-
| <code>.MMP</code> || uint32 || IT, MPTM, XM || Mix Levels <ul> <li>0: Original</li> <li>1: 1.17 RC1</li> <li>2: 1.17 RC2</li> <li>3: 1.17 RC3</li> <li>4: Compatible</li> <li>5: Compatible (FT2 Pan Law)</li> </ul>
|-
| <code>.VWC</code> || uint32 || IT, MPTM, XM || OpenMPT "Created With" version (e.g. OpenMPT 1.23.45.67 = 0x01234567)
|-
| <code>VWSL</code> || uint32 || IT, MPTM, XM || OpenMPT "Last Saved With" version
|-
| <code>.APS</code> || uint32 || IT, MPTM, XM || Sample Pre-Amp
|-
| <code>VTSV</code> || uint32 || IT, MPTM, XM || VSTi Pre-Amp
|-
| <code>.VGD</code> || uint32 || XM || Global Volume (0...256)
|-
| <code>..PR</code> || uint16 || IT, MPTM || Restart Position
|-
| <code>RSMP</code> || uint32 || MPTM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>CUES</code> || - || MPTM || Sample cue points for a single sample (only MPTM format). The first uint16 in the chunk indicates for which sample slot the cue points are meant. The rest of the chunk contains all cue points as uint32s. If this chunk is missing for a particular sample slot, OpenMPT assumes the default cue points for this slot. The i-th cue point can be computed as i × 2048.
|-
| <code>SWNG</code> || - || MPTM || Contains tempo swing factors (only MPTM format). The first uint16 in the chunk indicates the number of swing rows. The rest of the chunk contains all swing factors as uint32s. A factor of 16777216 (224) is considered to be unity, i.e. does not modify the row duration. After loading, the number of swing factors should be resized to the actual number of rows per beat (in case of malformed file) and re-normalized.
|-
| <code>.FSM</code> || - || IT, MPTM, XM || A bit field of generic compatibility flags. For modules made with OpenMPT 1.25 and older, the most important one is 0x01 (first bit set), which is IT-/XM-compatible playback mode. All other flags indicate which [[Manual: Compatible Playback#Playback Compatibility Settings|compatibility settings]] are toggled.
|-
| <code>AUTH</code> || uint8[] || IT, MPTM, XM || Song artist, as UTF-8 string
|-
| <code>AMIM</code> || - || IT, MPTM, XM || MIDI Mapping settings
|-
| <code>CCOL</code> || rgbx[] || IT, MPTM, XM || Channel colors. The chunk size divided by 4 indicates the number of channels present. Format is [R, G, B, 0] for channels that have a color assigned, or [x, x, x, non-zero] for a channel with no color.
|}

== MPTM Extensions ==

=== Detecting an MPTM file ===

There are two types of hacked IT files: In early versions of the MPTM format (used in OpenMPT 1.17.02.4x), the <code>IMPM</code> magic bytes are replaced by <code>tpm.</code>, so they are not backwards compatible. Newer MPTM files use the original magic, but use a <code>cwtv</code> value between 0889h and 0FFFh (inclusive) in the header.

In both cases, the last four bytes of the file point to the start of the MPTM extensions. If the magic bytes "228" can be found at this start position, it is a valid MPTM file.

=== 228 Extensions ===

228 Extensions have been used since OpenMPT 1.17.02.48 r192 for features that are only available in the MPTM format,
such as Custom Tunings, Multiple Sequences, and Parameter Control notes.

They are documented [[Development:_228_Extensions|here]].

=== External Samples ===

MPTM files can reference external samples. If the <code>cvt</code> value in the sample header is 80h, then the sample is external. In this case, the sample pointer does not point to actual sample data but to a filename:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || VarInt || Length of the filename
|-
| ? || char[] || Filename (UTF-8, not null-terminated)
|}

Note that only the sample waveform should be loaded, but not its metadata: Frequency, loop points, volume, panning, auto-vibrato etc. should be read from the IT file. If the sample length according to the IT header is shorter than the actual sample, the sample data should be trimmed, too.

External samples are used exactly the same way in ITI files.

=== OPL Instruments ===

MPTM files can make use of OPL instruments, just like S3M files. Unlike in S3M files, patch data is not stuffed into the sample header but stored as regular sample data. To tell OPL patches apart from regular samples, the <code>cvt</code> value in the sample header is set to 40h. Note that the check for this flag should be an equal comparison (<code>cvt == 40h</code>), not a bitwise AND, due to ModPlug's legacy ADPCM sample <code>cvt</code> type (FFh). Any combination with other <code>cvt</code> flags is also considered to be illegal.

OPL2 patches are stored in the same order as in S3M files, i.e. interleaved modulator and carrier bytes, with the last (12th) byte being unused and set to 0.

=== Order list (old) ===

If the <code>cwtv</code> is between 088Bh and 088Dh (inclusive), the order list at the start of the file is replaced by the following struct:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint16 || Version of the order list. Only version 0 is defined. Reject any other values.
|-
| 2 || uint32 || Number of items in the order list
|-
| 6 || uint32[] || The order list, as a series of uint32 values. The number of values is determined by the previous field.
|}

=== Custom Tunings (old) ===

This section is for OpenMPT versions before 1.17.02.48 r192. For newer versions, check [[Development:_228_Extensions|228 Extensions]].

Before OpenMPT 1.17.02.48 r192, the only feature that was only available in the MPTM format was Custom Tunings.
MPTM files that were made before r192 have a <code>cwtv</code> value between 0x0888 and 0x088C (inclusive).

These MPTM files contain a "Tuning Collection" chunk that contains all the custom tunings that are specific to the song (called "Tune specific tunings" in OpenMPT),
which is right after the OpenMPT song extensions.
It is then followed by a "Tuning Map" that determines which tuning each instrument should use.

A Tuning Collection could also exist separately in a <code>.TC</code> file, that can be exported/imported into an MPTM file in the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In an MPTM file, the last four bytes pointed to the start of the "Tune specific tunings" Tuning Collection,
similar to how they point to the start of 228 extensions in newer (<code>cwtv</code> > 0x088C) MPTM files.

==== Tuning Collection structure ====

The structure of a Tuning Collection is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| char[4]
| Tuning Collection beginning signature: <code>HSCT</code> (4 bytes)
|-
| int32
| Tuning Collection version: Always 1 or 2. 
|-
| uint8 or uint32
| Length of the Tuning Collection's name. 
Data type:
* uint8 if the Tuning Collection version is 2.
* uint32 if the Tuning Collection version is 1.

|-
| char[]
| Tuning Collection name. The current version of OpenMPT reads a maximum of 256 (0x100) characters. 
If the collection is in a TC file, its name is the same as what it was in OpenMPT when the TC file was exported. 
But in MPTM files, only the tune-specific tuning collection is stored, and its name is always <code>Tune specific tunings</code>.
|-
| int16
| Tuning Collection edit mask. 
A set of 16 bits that was used to specify which settings of the tunings can be changed, but is no longer used in newer versions of OpenMPT.

|-
| uint32
| Number of tunings in the collection. The current version of OpenMPT does not load custom tunings at all if the number of tunings in an MPTM file is greater than 50.
|-
| (custom structure)
| The tunings in this collection, stored right after each other. The structure of a tuning is described below.
|-
| char[4]
| Tuning Collection end signature: <code>FSCT</code> (4 bytes)
|}

==== Tuning structure ====

The structure of a Custom Tuning is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| char[8]
| Tuning beginning signature: <code>CTRTI_B.</code> (8 bytes)
|-
| int16
| Tuning version: Always 2 or 3. 
|-
| char[8]
| Tuning SFS chunk beginning signature: <code>CT<sfs>B</code> (8 bytes)
|-
| int16
| Tuning SFS chunk version: Always 3 or 4. 
|-
| uint8 or uint32
| Length of the tuning's name. 
Data type:
* uint8 if the SFS chunk version is 4.
* uint32 if the SFS chunk version is 3.

|-
| char[]
| Tuning name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|-
| int16
| Tuning edit mask. 
A set of 16 bits that was used to specify which settings of the tuning can be changed, but is no longer used in newer versions of OpenMPT.

|-
| int16
| Tuning type.
* 0: Generic
* 1: Group-geometric (originally called "Ratio-periodic")
* 3: Geometric (originally called "TET")
Newer versions of OpenMPT that use the new tuning format will convert old Geometric tunings to Group-geometric for compatibility reasons.
|-
| uint16 or uint32
| Size of the tuning's note name map. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. 
Data type:
* uint16 if the SFS chunk version is 4.
* uint32 if the SFS chunk version is 3.

|-
| (custom structure)
| The tuning's note name map. Contains the names of notes that have custom names. The structure is described in further below.
|-
| char[8]
| Tuning SFS chunk end signature: <code>CT<sfs>E</code> (8 bytes)
|-
| uint16 or uint32
| Size of the tuning's ratio table. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. This value is usually set to 256 (or 0 if the ratio table is unneeded). 
Data type:
* uint16 if the tuning version is 3.
* uint32 if the tuning version is 2.

|-
| float32[]
| The tuning's ratio table. Contains the frequency ratios for every note. If all ratios are 1, the ratio table is unneeded, so its size would be 0. 
Unlike the newer tuning format that uses 228 extensions, this table contains ratios for every note in every group, regardless of the tuning type.
|-
| uint16 or uint32
| Finetune steps. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. 
Data type:
* uint16 if the tuning version is 3.
* uint32 if the tuning version is 2.

|-
| float32[]
| An array of finetune step ratios, containing the same number of values as the finetune steps value. 
The first value is 1, and each value is r(1/finetunesteps) times the previous value, 
where r is the ratio of note 1 (the note after the middle note) to note 0 (the middle note). 
This table no longer exists in the newer tuning format that uses 228 extensions.
|-
| int16
| First note index in the ratio table. Usually set to -128. 
The current version of OpenMPT rejects values smaller than -200 and greater than 200.
|-
| int16
| Group size. 
For generic tunings, this value is 0.
|-
| float32
| Group ratio. 
For generic tunings, this value is 0.
|-
| char[8]
| Tuning end signature: <code>CTRTI_E.</code> (8 bytes)
|}

Many of the values that are stored for each tuning are redundant.
For example, the ratio table contains ratios for every note, regardless of the tuning type, even though it makes sense to
only have ratios for a single group in group-geometric tunings, and to not be stored at all in geometric tunings.
But they still have to be stored for these old versions of OpenMPT to work correctly.
However, these redundancies no longer exist in the newer tuning format that uses 228 extensions.

==== Tuning note name map structure ====

The structure of a single entry in the note name map is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| int16
| Note number.
|-
| uint8 or uint32
| Length of the note name. 
Data type:
* uint8 if the tuning's SFS chunk version is 4.
* uint32 if the tuning's SFS chunk version is 3.

|-
| char[]
| Note name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|}

This structure is stored for every note that has a custom name.

For geometric and group-geometric tunings, only the notes of a single group, where the note numbers are between 0 and groupsize-1 (inclusive).
The note names for that single group are then applied to every group (group/octave numbers are not a part of the note name).

==== Tuning Map structure ====

The structure of a tuning map is identical to that of the new 228 tuning format (documented [[Development:_228_Extensions#Tuning_Map|here]]), but with a difference if the <code>cwtv</code> value is 0x088B or older:

The number of tunings in the map and the length of the tuning names in the map are both stored as uint32 instead of uint16 and uint8 respectively.

== RIFF WAVE ==

OpenMPT uses its own <code>xtra</code> chunk in RIFF WAVE files to store some sample properties which could otherwise not be represented in the format.

Its layout is as follows:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint32 || Sample flags (0x20: Default panning is enabled)
|-
| 4 || uint16 || Default panning (0...256)
|-
| 6 || uint16 || Default volume (0...256)
|-
| 8 || uint16 || Global volume (0...64)
|-
| 10 || uint16 || (Reserved, must be 0)
|-
| 12 || uint8 || Auto-vibrato type 
|-
| 13 || uint8 || Auto-vibrato sweep
|-
| 14 || uint8 || Auto-vibrato depth
|-
| 15 || uint8 || Auto-vibrato rate
|}

Optionally, when copying a sample to the system clipboard, the sample name (32 characters, null-padded) and filename (22 characters, null-padded) follow.

== FLAC ==

Since the FLAC format has no native and standardized way to store loop information, OpenMPT follows Renoise′s way of storing loop information: FLAC supports application-defined metadata, so OpenMPT writes a metadata block with application ID <code>riff</code>. The block contains a <code>smpl</code> chunk (as defined in the [http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/RIFFNEW.pdf RIFF specification]). Similarly, extended sample properties are stored in another <code>riff</code> application block contaning the OpenMPT-specific <code>[[#RIFF WAVE|xtra]]</code> chunk, and sample cue points are stored in a <code>cue </code> chunk.

OpenMPT also reads and writes the following non-standard vorbis comments:
* '''SAMPLERATE''': Contains the sample rate (as text) in case it would exceed the maximum sample rate supported by the FLAC format, 655350 Hz.
* '''LOOPSTART''': The start of the sample loop in frames. This tag is only read, not written.
* '''LOOPLENGTH''': The length of the sample loop in frames. This tag is only read, not written.

[[Category:Development|OpenMPT Format Extensions]]

Development: 228 Extensions

2022-07-07T20:58:17Z

CS127: fixed more typos/mistakes

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character (text encoding may vary, so a single character is not necessarily one byte).
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned little-endian integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit width (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the least significant bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and a map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specify what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, unless the chunk has a "flag byte" (explained later) and its bit 0 is set.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for each entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk. 
The current version of OpenMPT always writes this adaptive integer in two bytes, even if it only needs one. 
Additionally, this causes OpenMPT to be unable to write chunks with more than 16383 entries.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not). 
The current version of OpenMPT always writes this adaptive integer in eight bytes, even if it needs fewer bytes.
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to a 228 chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries. OpenMPT writes this chunk after the OpenMPT song extensions, and before the last four bytes of the file that specify its position.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk.

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the <code>mptm</code> chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (<code>6E 75 6D</code> in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this entry, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the <code>mptSeqC</code> chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-05-27T05:58:41Z

CS127:

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character (text encoding may vary, so a single character is not necessarily one byte).
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned little-endian integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit width (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the least significant bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and a map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specify what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, unless the chunk has a "flag byte" (explained later) and its bit 0 is set.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for each entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk. 
The current version of OpenMPT always writes this adaptive integer in two bytes, even if it only needs one. 
Additionally, this causes OpenMPT to be unable to write chunks with more than 16383 entries.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not). 
The current version of OpenMPT always writes this adaptive integer in eight bytes, even if it needs fewer bytes.
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to a 228 chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries. OpenMPT writes this chunk after the OpenMPT song extensions, and before the last four bytes of the file that specify its position.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk.

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the <code>mptm</code> chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (<code>6E 75 6D</code> in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: OpenMPT Format Extensions

2022-05-27T05:53:49Z

CS127: better tables

ModPlug Tracker and OpenMPT have extended the IT and XM formats in various ways. In general, these hacks are frowned upon, but here is some documentation on those hacks in case you want to support them in your own player. I am really sorry about all this mess, but all of this has grown historically way before I joined OpenMPT development.

Presence of these format extensions in a file does not necessarily imply that it was created with ModPlug Tracker or OpenMPT. Some of the extensions are also used e.g. by BeRoTracker.

Any numeric values are stored in little-endian format, unless noted otherwise.

Data types used in this document:
* uint8, uint16, uint32: Unsigned integers with the given bit width.
* int8, int16, int32: Signed integers with the given bit width.
* char: A single character (i.e. a byte)
* float32: Single precision IEEE float
* VarInt: A MIDI-like variable-length unsigned integer (big-endian value where the highest bit of each byte indicates if another byte follows, and the lower 7 bits containing the actual number).
* Square brackets [] denote an array of values:
** [] is a variable-length array (length is deduced from some other attribute)
** [42] denotes an array with 42 entries.

== ModPlug Song Extensions ==

The following extensions exist since the (closed-source) ModPlug Tracker days. These extensions are found in [https://en.wikipedia.org/wiki/Interchange_File_Format IFF]-like chunks, but without any padding bytes. The chunks are placed right after the header data in the IT format (i.e. after the edit history / MIDI macro block). In the XM format these chunks are placed right at the end of the file (i.e. after the sample data). At the time of writing, these chunks are always written out in the order described here, but if possible you should probably try to read them without expecting a certain order. All chunks are optional.

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint32 || Size of this chunk, excluding the header
|}

=== Chunks ===

==== text (XM only) ====

Contains the song message (CR line endings), its length is determined by the chunk size.

==== MIDI (XM only) ====

Contains the MIDI macro configuration, in the same format as in the IT format.

==== PNAM ====

Contains the pattern names. Each pattern name is 32 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The pattern names are stored continuously, i.e. there are (chunk size / 32) pattern names in the chunk, for pattern 0, pattern 1, ... pattern (chunk size / 32 - 1).

==== CNAM ====

Contains the channel names. Each channel name is 20 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The channel names are stored continuously, i.e. there are (chunk size / 20) channel names in the chunk, for channel 1, channel 2, ... channel (chunk size / 20).

==== CHFX ====

Contains the plugin assignment for each channel. For every channel, there is a 32-bit integer plugin index. 0 means no plugin, 1 is the first plugin, etc...

==== FX00, ... FX99, F100, ... F255 ====

Contains plugin information for each plugin slot. <code>FX00</code> contains the information for the first plugin slot, <code>FX99</code> for the 100th, <code>F100</code> for the 101st, etc...

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Plugin Type
<ul>
<li>VST plugins: <code>PtsV</code></li>
<li>DMO plugins: <code>OMXD</code></li>
</ul>
|-
| 4 || char[4] || Unique Plugin ID
|-
| 8 || uint8 || Routing Flags
<ul>
<li>0x01: Apply to master mix</li>
<li>0x02: Bypass effect</li>
<li>0x04: Wet Mix (dry added)</li>
<li>0x08: Expand Mix [0%,100%] → [-200%,200%]</li>
<li>0x10: Plugin will automatically suspend on silence</li>
</ul>
|-
| 9 || uint8 || Mix mode
<ul>
<li>0: normal processing</li>
<li>1: MIX += DRY - WET * wetRatio</li>
<li>2: MIX += WET - DRY * dryRatio</li>
<li>3: MIX -= WET - DRY * wetRatio</li>
<li>4: MIX -= middle - WET * wetRatio + middle - DRY</li>
<li>5: MIX_L += wetRatio * (WET_L - DRY_L) + dryRatio * (DRY_R - WET_R) MIX_R += dryRatio * (WET_L - DRY_L) + wetRatio * (DRY_R - WET_R)</li>
</ul>
|-
| 10 || uint8 || Gain Factor * 10 (9 = 90%, 10 = 100%, 11 = 110%, etc.). A value of 0 is equal to 10 (i.e. 100%).
|-
| 11 || uint8 || (Reserved)
|-
| 12 || uint32 || Output Routing (0 = send to master 0x80 + x = send to plugin x)
|-
| 16 || uint8[16] || (Reserved)
|-
| 32 || char[32] || User-chosen plugin name (Windows code page)
|-
| 64 || char[64] || Library name (Original DLL name / DMO identifier). UTF-8 (max. 64 bytes) since OpenMPT 1.22.07.01, Windows code page in older versions.
|-
| 128 || uint32 || Size of plugin-specific data in bytes (parameters or opaque chunk)
|-
| 132 || uint8 || Plugin-specific data
|}

The first four bytes of the plugin-specific data determine the type of data. If they are all 0, then the plugin parameters follow as an array of float32 values. Otherwise, plugin type specific data follows which should be treated as an opaque chunk. For example, for VST plugins that support the effGetChunk / effSetChunk chunk, the first four bytes will be "fEvN", followed by the data to be sent to the plugin.

After the plugin information described above, more information may follow in OpenMPT modules. This information is again stored in chunks. However, there are two legacy chunks which do not have any size stored alongside the chunk identifier:

{| class="wikitable"
|-
! FOURCC !! Data Type !! Description
|-
| <code>DWRT</code> || float32 || Dry/Wet Ratio of the plugin. This chunk does not denote its size!
|-
| <code>PROG</code> || uint32 || Default plugin program (preset) to restore. This chunk does not denote its size!
|}

Any chunks that will be added in the future will have proper IFF-like chunks with a 32-bit size field.

== ModPlug Instrument Extensions (IT only) ==

To be able to address more than 256 samples in the IT format, ModPlug Tracker has an extension to store the high byte of sample indices for the instrument sample map.

By default, the last four bytes of an IT instrument (right after the pitch envelope) are unused. If they read <code>MPTX</code> or <code>XTPM</code>, 120 extra bytes follow, one for each note in the sample map. These bytes are the high byte of the sample index, i.e. they need to be multiplied by 256 and then added to the already read sample index.

== OpenMPT Extensions (General Information) ==

In the XM format, OpenMPT instrument extensions may follow the ModPlug song extensions and may in return be followed by OpenMPT song extensions.

In the IT format, OpenMPT instrument extensions may follow the sample block and may in return be followed by OpenMPT song extensions.
This is very ugly, because there might not be any samples, in which case the last thing before the extension block would be the last pattern. If there are no patterns, the last thing before the extension block would be a sample header (at least one sample header will be present even if there is no sample data – but you may even want to cover the case where there are no sample headers, for being compatible with possible future changes). So you will somehow have to keep track of the highest offset you have read into the file. If the last sample is IT-compressed, things become even more complicated: There is no way to know the compressed size of a compressed sample, so in case you want to skip sample loading, and the last sample happens to be compressed, you can do the following:
Since we know that the extended instrument and song properties start right after the last sample, and since IT-compressed samples consist of chunks with a prepended 16-bit length field, you can simply read that 16-bit number, skip this amount of bytes, then check if you can read OpenMPT's <code>XTPM</code> or <code>STPM</code> magic bytes, and if not, read the next 16-bit length, skip the bytes, etc...

In pseudo code, finding the OpenMPT extensions in an IT / MPTM file could look somewhat like this:

''offset'' = 0
''lastSampleCompressed'' = false

// In case there are no patterns and no sample data (just empty sample slots):
if(number of samples > 0):
''offset'' = last sample header pointer + sizeof(ITSampleHeader)

for all samples:
if sample is not compressed or if samples are decoded:
''lastSampleCompressed'' = false
''offset'' = max(''offset'', pointer to sample data + sample size)
else if sample is compressed and samples are not decoded:
''lastSampleCompressed'' = true
''offset'' = max(''offset'', pointer to sample data)

// In case there is no sample data:
for all patterns:
''offset'' = max(''offset'', end of pattern data)

if ''lastSampleCompressed'':
while not eof:
if next four bytes are XTPM or STPM:
''chunkID'' = next four bytes
if ''chunkID'' only contains ASCII characters (all bytes are in 32…127)
''offset'' = current position - 4; break
else
skip back 8 bytes
read uint16 value and skip as many bytes

Try reading XTPM and STPM extensions at ''offset''

The provided data types are just for orientation, i.e. the minimum recommended field size for storing the values in memory. You must expect fields to have a different size, since sometimes they do so for historic reasons. Defensive programming is your friend. Most of the FOURCCs also just make sense when read backwards, again for historic reasons. Note that some of these extensions duplicate existing functionality of the IT/XM format. In this case, the extensions take precedence over the value previous found in the file.

== OpenMPT Instrument Extensions ==

Instrument extensions start with the <code>XTPM</code> magic bytes, but there is no size indication of the total size of this block. So you have to read the following chunks and as soon as you read the <code>STPM</code> magic bytes for a chunk, you know you have read to far and can continue with reading OpenMPT Song Extensions instead.

Instrument extensions are stored in a peculiar way: There is one chunk per property, and it contains the values for all instruments at once. The layout is as follows:

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint16 || Size of this chunk's entry '''for one instrument''' (i.e. total chunk content size is this field × number of instruments)
|}

=== Chunk Contents ===

The following instrument properties exist. Some of them are redundant depending on the file type and thus not present in all files. If they are redundant, they overwrite the values that were obtained from the format-specific structures.

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..OF</code> || uint32 || IT, MPTM, XM || Fade-out
|-
| <code>...P</code> || uint32 || IT, MPTM, XM || Panning (0...256)
|-
| <code>..EV</code> || uint32 || MPTM || Number of volume envelope nodes (if ≥ 25 nodes)
|-
| <code>..EP</code> || uint32 || MPTM || Number of pan envelope nodes (if ≥ 25 nodes)
|-
| <code>.EiP</code> || uint32 || MPTM || Number of pitch envelope nodes (if ≥ 25 nodes)
|-
| <code>..BM</code> || uint16 || IT, MPTM, XM || MIDI Bank
|-
| <code>..PM</code> || uint8 || IT, MPTM, XM || MIDI Program
|-
| <code>..CM</code> || uint8 || IT, MPTM, XM || MIDI Channel
|-
| <code>.[PV</code> || uint16[] || MPTM || Volume Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EV</code> || uint8[] || MPTM || Volume Envelope Values (if ≥ 25 nodes)
|-
| <code>.[PP</code> || uint16[] || MPTM || Pan Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EP</code> || uint8[] || MPTM || Pan Envelope Values (if ≥ 25 nodes)
|-
| <code>[PiP</code> || uint16[] || MPTM || Pitch Envelope Ticks (if ≥ 25 nodes)
|-
| <code>[EiP</code> || uint8[] || MPTM || Pitch Envelope Values (if ≥ 25 nodes)
|-
| <code>.PiM</code> || uint8 || IT, MPTM, XM || Plugin, 0 = no plugin, 1 = first plugin, etc.
|-
| <code>..RV</code> || uint16 || IT, MPTM, XM || Ramping / Attack
|-
| <code>...R</code> || uint8 || IT, MPTM, XM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>..SC</code> || uint8 || IT, MPTM, XM || Cutoff Swing
|-
| <code>..SR</code> || uint8 || IT, MPTM, XM || Resonance Swing
|-
| <code>..MF</code> || uint8 || IT, MPTM, XM || Filter Mode
|-
| <code>HEVP</code> || uint8 || IT, MPTM, XM || Plugin Velocity Handling
|-
| <code>HOVP</code> || uint8 || IT, MPTM, XM || Plugin Volume Handling
|-
| <code>NREV</code> || uint8 || IT, MPTM, XM || Volume Envelope Release Node
|-
| <code>NREA</code> || uint8 || IT, MPTM, XM || Pan Envelope Release Node
|-
| <code>NREP</code> || uint8 || IT, MPTM, XM || Pitch Envelope Release Node
|-
| <code>DWPM</code> || uint8 || IT, MPTM || Pitch Wheel Depth
|-
| <code>LTTP</code> || uint16 || IT, MPTM, XM || Integer part of Pitch / Tempo Lock
|-
| <code>PTTF</code> || uint16 || MPTM || Fractional part of Pitch / Tempo Lock (0...9999)
|}

=== Legacy Extension ===

But wait, there is more! Some really old OpenMPT versions (1.17 RC1 and older, but not 1.17 RC2) do not use the instrument extensions described above. However, they also need to store the plugin reference for each instrument, which is done in another modular block following each instrument header (and possibly the <code>MPTX</code> / <code>XTPM</code> extension of that instrument header).
If this legacy extension is present, the instrument header is followed by the magic bytes <code>MSNI</code> and an uint32 containing the modular data size.

Currently there is only one chunk in this modular data block. Its FOURCC is <code>GULP</code>, has no size information and contains an uint8 for the plugin index (0 = no plugin, 1 = first plugin, etc.).

== OpenMPT Song Extensions ==

Song extensions start with the <code>STPM</code> magic bytes, but there is no size indication of the total size of this block. In an IT / XM file, these extensions are the last chunks in the file, so you can continue reading until you are out of data. In the case of MPTM files, some further MPTM-specific data follows. This data starts with the bytes "228" followed by ASCII charater 4 (not the digit), so you can keep reading the song extensions until you read this FOURCC.

=== Chunk Header Layout ===

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || char[4] || Magic bytes (FOURCC)
|-
| 4 || uint16 || Size of this chunk, excluding the header
|}

=== Chunk Contents ===

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..TD</code> || uint32 || IT, MPTM, XM || Integer part of the default tempo (required if it is larger than 255 in IT / MPTM, but also found in legacy XM files)
|-
| <code>DTFR</code> || uint32 || MPTM || Fractional part of the default tempo (0...9999)
|-
| <code>.BPR</code> || uint32 || IT, MPTM, XM || Rows Per Beat
|-
| <code>.MPR</code> || uint32 || IT, MPTM, XM || Rows Per Measure
|-
| <code>...C</code> || uint16 || IT, MPTM || Number of channels
|-
| <code>SnhC</code> || - || IT, MPTM || If there are more than 64 channels in the IT / MTPM format, this chunk contains the default panning, volume and flags for channels 65+. They are encoded the same way as in the IT header, except that volume and panning are stored in an interleaved way (i.e. volume for channel 65, pan for channel 65, volume for channel 66, ...)
|-
| <code>..MT</code> || uint32 || IT, MPTM, XM || Tempo Mode <ul> <li>0: classic</li> <li>1: alternative</li> <li>2: modern</li> </ul>
|-
| <code>.MMP</code> || uint32 || IT, MPTM, XM || Mix Levels <ul> <li>0: Original</li> <li>1: 1.17 RC1</li> <li>2: 1.17 RC2</li> <li>3: 1.17 RC3</li> <li>4: Compatible</li> <li>5: Compatible (FT2 Pan Law)</li> </ul>
|-
| <code>.VWC</code> || uint32 || IT, MPTM, XM || OpenMPT "Created With" version (e.g. OpenMPT 1.23.45.67 = 0x01234567)
|-
| <code>VWSL</code> || uint32 || IT, MPTM, XM || OpenMPT "Last Saved With" version
|-
| <code>.APS</code> || uint32 || IT, MPTM, XM || Sample Pre-Amp
|-
| <code>VTSV</code> || uint32 || IT, MPTM, XM || VSTi Pre-Amp
|-
| <code>.VGD</code> || uint32 || XM || Global Volume (0...256)
|-
| <code>..PR</code> || uint16 || IT, MPTM || Restart Position
|-
| <code>RSMP</code> || uint32 || MPTM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>CUES</code> || - || MPTM || Sample cue points for a single sample (only MPTM format). The first uint16 in the chunk indicates for which sample slot the cue points are meant. The rest of the chunk contains all cue points as uint32s. If this chunk is missing for a particular sample slot, OpenMPT assumes the default cue points for this slot. The i-th cue point can be computed as i × 2048.
|-
| <code>SWNG</code> || - || MPTM || Contains tempo swing factors (only MPTM format). The first uint16 in the chunk indicates the number of swing rows. The rest of the chunk contains all swing factors as uint32s. A factor of 16777216 (224) is considered to be unity, i.e. does not modify the row duration. After loading, the number of swing factors should be resized to the actual number of rows per beat (in case of malformed file) and re-normalized.
|-
| <code>.FSM</code> || - || IT, MPTM, XM || A bit field of generic compatibility flags. For modules made with OpenMPT 1.25 and older, the most important one is 0x01 (first bit set), which is IT-/XM-compatible playback mode. All other flags indicate which [[Manual: Compatible Playback#Playback Compatibility Settings|compatibility settings]] are toggled.
|-
| <code>AUTH</code> || uint8[] || IT, MPTM, XM || Song artist, as UTF-8 string
|-
| <code>AMIM</code> || - || IT, MPTM, XM || MIDI Mapping settings
|-
| <code>CCOL</code> || rgbx[] || IT, MPTM, XM || Channel colors. The chunk size divided by 4 indicates the number of channels present. Format is [R, G, B, 0] for channels that have a color assigned, or [x, x, x, non-zero] for a channel with no color.
|}

== MPTM Extensions ==

=== Detecting an MPTM file ===

There are two types of hacked IT files: In early versions of the MPTM format (used in OpenMPT 1.17.02.4x), the <code>IMPM</code> magic bytes are replaced by <code>tpm.</code>, so they are not backwards compatible. Newer MPTM files use the original magic, but use a <code>cwtv</code> value between 0889h and 0FFFh (inclusive) in the header.

In both cases, the last four bytes of the file point to the start of the MPTM extensions. If the magic bytes "228" can be found at this start position, it is a valid MPTM file.

=== 228 Extensions ===

228 Extensions have been used since OpenMPT 1.17.02.48 r192 for features that are only available in the MPTM format,
such as Custom Tunings, Multiple Sequences, and Parameter Control notes.

They are documented [[Development:_228_Extensions|here]].

=== External Samples ===

MPTM files can reference external samples. If the <code>cvt</code> value in the sample header is 80h, then the sample is external. In this case, the sample pointer does not point to actual sample data but to a filename:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || VarInt || Length of the filename
|-
| ? || char[] || Filename (UTF-8, not null-terminated)
|}

Note that only the sample waveform should be loaded, but not its metadata: Frequency, loop points, volume, panning, auto-vibrato etc. should be read from the IT file. If the sample length according to the IT header is shorter than the actual sample, the sample data should be trimmed, too.

External samples are used exactly the same way in ITI files.

=== OPL Instruments ===

MPTM files can make use of OPL instruments, just like S3M files. Unlike in S3M files, patch data is not stuffed into the sample header but stored as regular sample data. To tell OPL patches apart from regular samples, the <code>cvt</code> value in the sample header is set to 40h. Note that the check for this flag should be an equal comparison (<code>cvt == 40h</code>), not a bitwise AND, due to ModPlug's legacy ADPCM sample <code>cvt</code> type (FFh). Any combination with other <code>cvt</code> flags is also considered to be illegal.

OPL2 patches are stored in the same order as in S3M files, i.e. interleaved modulator and carrier bytes, with the last (12th) byte being unused and set to 0.

=== Order list (old) ===

If the <code>cwtv</code> is between 088Bh and 088Dh (inclusive), the order list at the start of the file is replaced by the following struct:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint16 || Version of the order list. Only version 0 is defined. Reject any other values.
|-
| 2 || uint32 || Number of items in the order list
|-
| 6 || uint32[] || The order list, as a series of uint32 values. The number of values is determined by the previous field.
|}

=== Custom Tunings (old) ===

This section is for OpenMPT versions before 1.17.02.48 r192. For newer versions, check [[Development:_228_Extensions|228 Extensions]].

Before OpenMPT 1.17.02.48 r192, the only feature that was only available in the MPTM format was Custom Tunings.
MPTM files that were made before r192 have a <code>cwtv</code> value between 0x0888 and 0x088C (inclusive).

These MPTM files contain a "Tuning Collection" chunk that contains all the custom tunings that are specific to the song (called "Tune specific tunings" in OpenMPT),
which is right after the OpenMPT song extensions.
It is then followed by a "Tuning Map" that determines which tuning each instrument should use.

A Tuning Collection could also exist separately in a <code>.TC</code> file, that can be exported/imported into an MPTM file in the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In an MPTM file, the last four bytes pointed to the start of the "Tune specific tunings" Tuning Collection,
similar to how they point to the start of 228 extensions in newer (<code>cwtv</code> > 0x088C) MPTM files.

==== Tuning Collection structure ====

The structure of a Tuning Collection is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| char[4]
| Tuning Collection beginning signature: <code>HSCT</code> (4 bytes)
|-
| int32
| Tuning Collection version: Always 1 or 2. 
|-
| uint8 or uint32
| Length of the Tuning Collection's name. 
Data type:
* uint8 if the Tuning Collection version is 2.
* uint32 if the Tuning Collection version is 1.

|-
| char[]
| Tuning Collection name. The current version of OpenMPT reads a maximum of 256 (0x100) characters. 
If the collection is in a TC file, its name is the same as what it was in OpenMPT when the TC file was exported. 
But in MPTM files, only the tune-specific tuning collection is stored, and its name is always <code>Tune specific tunings</code>.
|-
| int16
| Tuning Collection edit mask. 
A set of 16 bits that was used to specify which settings of the tunings can be changed, but is no longer used in newer versions of OpenMPT.

|-
| uint32
| Number of tunings in the collection. The current version of OpenMPT does not load custom tunings at all if the number of tunings in an MPTM file is greater than 50.
|-
| (custom structure)
| The tunings in this collection, stored right after each other. The structure of a tuning is described below.
|-
| char[4]
| Tuning Collection end signature: <code>FSCT</code> (4 bytes)
|}

==== Tuning structure ====

The structure of a Custom Tuning is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| char[8]
| Tuning beginning signature: <code>CTRTI_B.</code> (8 bytes)
|-
| int16
| Tuning version: Always 2 or 3. 
|-
| char[8]
| Tuning SFS chunk beginning signature: <code>CT<sfs>B</code> (8 bytes)
|-
| int16
| Tuning SFS chunk version: Always 3 or 4. 
|-
| uint8 or uint32
| Length of the tuning's name. 
Data type:
* uint8 if the SFS chunk version is 4.
* uint32 if the SFS chunk version is 3.

|-
| char[]
| Tuning name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|-
| int16
| Tuning edit mask. 
A set of 16 bits that was used to specify which settings of the tuning can be changed, but is no longer used in newer versions of OpenMPT.

|-
| int16
| Tuning type.
* 0: Generic
* 1: Group-geometric (originally called "Ratio-periodic")
* 3: Geometric (originally called "TET")
Newer versions of OpenMPT that use the new tuning format will convert old Geometric tunings to Group-geometric for compatibility reasons.
|-
| uint16 or uint32
| Size of the tuning's note name map. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. 
Data type:
* uint16 if the SFS chunk version is 4.
* uint32 if the SFS chunk version is 3.

|-
| (custom structure)
| The tuning's note name map. Contains the names of notes that have custom names. The structure is described in further below.
|-
| char[8]
| Tuning SFS chunk end signature: CT<sfs>E (8 bytes)
|-
| uint16 or uint32
| Size of the tuning's ratio table. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. This value is usually set to 256 (or 0 if the ratio table is unneeded). 
Data type:
* uint16 if the tuning version is 3.
* uint32 if the tuning version is 2.

|-
| float32[]
| The tuning's ratio table. Contains the frequency ratios for every note. If all ratios are 1, the ratio table is unneeded, so its size would be 0. 
Unlike the newer tuning format that uses 228 extensions, this table contains ratios for every note in every group, regardless of the tuning type.
|-
| uint16 or uint32
| Finetune steps. Maximum value is 65535 (0xFFFF), even if the datatype is uint32. 
Data type:
* uint16 if the tuning version is 3.
* uint32 if the tuning version is 2.

|-
| float32[]
| An array of finetune step ratios, containing the same number of values as the finetune steps value. 
The first value is 1, and each value is r(1/finetunesteps) times the previous value, 
where r is the ratio of note 1 (the note after the middle note) to note 0 (the middle note). 
This table no longer exists in the newer tuning format that uses 228 extensions.
|-
| int16
| First note index in the ratio table. Usually set to -128. 
The current version of OpenMPT rejects values smaller than -200 and greater than 200.
|-
| int16
| Group size. 
For generic tunings, this value is 0.
|-
| float32
| Group ratio. 
For generic tunings, this value is 0.
|-
| char[8]
| Tuning end signature: <code>CTRTI_E.</code> (8 bytes)
|}

Many of the values that are stored for each tuning are redundant.
For example, the ratio table contains ratios for every note, regardless of the tuning type, even though it makes sense to
only have ratios for a single group in group-geometric tunings, and to not be stored at all in geometric tunings.
But they still have to be stored for these old versions of OpenMPT to work correctly.
However, these redundancies no longer exist in the newer tuning format that uses 228 extensions.

==== Tuning note name map structure ====

The structure of a single entry in the note name map is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| int16
| Note number.
|-
| uint8 or uint32
| Length of the note name. 
Data type:
* uint8 if the tuning's SFS chunk version is 4.
* uint32 if the tuning's SFS chunk version is 3.

|-
| char[]
| Note name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|}

This structure is stored for every note that has a custom name.

For geometric and group-geometric tunings, only the notes of a single group, where the note numbers are between 0 and groupsize-1 (inclusive).
The note names for that single group are then applied to every group (group/octave numbers are not a part of the note name).

==== Tuning Map structure ====

The structure of a tuning map is identical to that of the new 228 tuning format (documented [[Development:_228_Extensions#Tuning_Map|here]]), but with a difference if the <code>cwtv</code> value is 0x088B or older:

The number of tunings in the map and the length of the tuning names in the map are both stored as uint32 instead of uint16 and uint8 respectively.

== RIFF WAVE ==

OpenMPT uses its own <code>xtra</code> chunk in RIFF WAVE files to store some sample properties which could otherwise not be represented in the format.

Its layout is as follows:

{| class="wikitable"
|-
! Offset !! Data Type !! Content
|-
| 0 || uint32 || Sample flags (0x20: Default panning is enabled)
|-
| 4 || uint16 || Default panning (0...256)
|-
| 6 || uint16 || Default volume (0...256)
|-
| 8 || uint16 || Global volume (0...64)
|-
| 10 || uint16 || (Reserved, must be 0)
|-
| 12 || uint8 || Auto-vibrato type 
|-
| 13 || uint8 || Auto-vibrato sweep
|-
| 14 || uint8 || Auto-vibrato depth
|-
| 15 || uint8 || Auto-vibrato rate
|}

Optionally, when copying a sample to the system clipboard, the sample name (32 characters, null-padded) and filename (22 characters, null-padded) follow.

== FLAC ==

Since the FLAC format has no native and standardized way to store loop information, OpenMPT follows Renoise′s way of storing loop information: FLAC supports application-defined metadata, so OpenMPT writes a metadata block with application ID <code>riff</code>. The block contains a <code>smpl</code> chunk (as defined in the [http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/RIFFNEW.pdf RIFF specification]). Similarly, extended sample properties are stored in another <code>riff</code> application block contaning the OpenMPT-specific <code>[[#RIFF WAVE|xtra]]</code> chunk, and sample cue points are stored in a <code>cue </code> chunk.

OpenMPT also reads and writes the following non-standard vorbis comments:
* '''SAMPLERATE''': Contains the sample rate (as text) in case it would exceed the maximum sample rate supported by the FLAC format, 655350 Hz.
* '''LOOPSTART''': The start of the sample loop in frames. This tag is only read, not written.
* '''LOOPLENGTH''': The length of the sample loop in frames. This tag is only read, not written.

[[Category:Development|OpenMPT Format Extensions]]

Development: 228 Extensions

2022-05-03T16:47:22Z

CS127: /* Header Structure */ fix typo

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned little-endian integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit width (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the least significant bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and a map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specify what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, unless the chunk has a "flag byte" (explained later) and its bit 0 is set.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for each entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk. 
The current version of OpenMPT always writes this adaptive integer in two bytes, even if it only needs one. 
Additionally, this causes OpenMPT to be unable to write chunks with more than 16383 entries.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not). 
The current version of OpenMPT always writes this adaptive integer in eight bytes, even if it needs fewer bytes.
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to a 228 chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries. OpenMPT writes this chunk after the OpenMPT song extensions, and before the last four bytes of the file that specify its position.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk.

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the <code>mptm</code> chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (<code>6E 75 6D</code> in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-04-09T13:07:50Z

CS127: /* Header Structure */

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned little-endian integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit width (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the least significant bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and a map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specify what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, unless the chunk has a "flag byte" (explained later) and its bit 0 is set.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk. 
The current version of OpenMPT always writes this adaptive integer in two bytes, even if it only needs one. 
Additionally, this causes OpenMPT to be unable to write chunks with more than 16383 entries.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not). 
The current version of OpenMPT always writes this adaptive integer in eight bytes, even if it needs fewer bytes.
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to a 228 chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries. OpenMPT writes this chunk after the OpenMPT song extensions, and before the last four bytes of the file that specify its position.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk.

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the <code>mptm</code> chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (<code>6E 75 6D</code> in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-04-09T13:05:42Z

CS127: typo fixes, more consistency, and some simplification

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned little-endian integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit width (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the least significant bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the least significant two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and a map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specify what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, unless the chunk has a "flag byte" (explained later) and its bit 0 is set.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk. 
The current version of OpenMPT always writes this adaptive integer in two bytes, even if it only needs one.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not). 
The current version of OpenMPT always writes this adaptive integer in eight bytes, even if it needs fewer bytes.
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to a 228 chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries. OpenMPT writes this chunk after the OpenMPT song extensions, and before the last four bytes of the file that specify its position.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk.

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the <code>mptm</code> chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (<code>6E 75 6D</code> in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-03-09T08:57:14Z

CS127: /* Tuning Collection */ removed redundant info that was repeated in the next sentence

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned little-endian integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and a map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specify what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk.

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the <code>mptm</code> chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (<code>6E 75 6D</code> in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-03-02T04:33:13Z

CS127: /* 228 Chunk Structure */

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned little-endian integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and a map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specify what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the <code>mptm</code> chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (<code>6E 75 6D</code> in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: OpenMPT Format Extensions

2022-02-28T12:58:13Z

CS127: /* Tuning Map structure */ added link to tuning map documentation

ModPlug Tracker and OpenMPT have extended the IT and XM formats in various ways. In general, these hacks are frowned upon, but here is some documentation on those hacks in case you want to support them in your own player. I am really sorry about all this mess, but all of this has grown historically way before I joined OpenMPT development.

Presence of these format extensions in a file does not necessarily imply that it was created with ModPlug Tracker or OpenMPT. Some of the extensions are also used e.g. by BeRoTracker.

Any numeric values are stored in little-endian format, unless noted otherwise.

Data types used in this document:
* uint8, uint16, uint32: Unsigned integers with the given bit width.
* int8, int16, int32: Signed integers with the given bit width.
* char: A single character (i.e. a byte)
* float32: Single precision IEEE float
* VarInt: A MIDI-like variable-length unsigned integer (big-endian value where the highest bit of each byte indicates if another byte follows, and the lower 7 bits containing the actual number).
* Square brackets [] denote an array of values:
** [] is a variable-length array (length is deduced from some other attribute)
** [42] denotes an array with 42 entries.

== ModPlug Song Extensions ==

The following extensions exist since the (closed-source) ModPlug Tracker days. These extensions are found in [https://en.wikipedia.org/wiki/Interchange_File_Format IFF]-like chunks, but without any padding bytes. The chunks are placed right after the header data in the IT format (i.e. after the edit history / MIDI macro block). In the XM format these chunks are placed right at the end of the file (i.e. after the sample data). At the time of writing, these chunks are always written out in the order described here, but if possible you should probably try to read them without expecting a certain order. All chunks are optional.

=== Chunk Header Layout ===

Offset Type Content
0 char[4] Magic bytes (FOURCC)
4 uint32 Size of this chunk, excluding the header

=== Chunks ===

==== text (XM only) ====

Contains the song message (CR line endings), its length is determined by the chunk size.

==== MIDI (XM only) ====

Contains the MIDI macro configuration, in the same format as in the IT format.

==== PNAM ====

Contains the pattern names. Each pattern name is 32 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The pattern names are stored continuously, i.e. there are (chunk size / 32) pattern names in the chunk, for pattern 0, pattern 1, ... pattern (chunk size / 32 - 1).

==== CNAM ====

Contains the channel names. Each channel name is 20 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The channel names are stored continuously, i.e. there are (chunk size / 20) channel names in the chunk, for channel 1, channel 2, ... channel (chunk size / 20).

==== CHFX ====

Contains the plugin assignment for each channel. For every channel, there is a 32-bit integer plugin index. 0 means no plugin, 1 is the first plugin, etc...

==== FX00, ... FX99, F100, ... F255 ====

Contains plugin information for each plugin slot. <code>FX00</code> contains the information for the first plugin slot, <code>FX99</code> for the 100th, <code>F100</code> for the 101st, etc...

Offset Type Content
0 char[4] Plugin type ("PtsV" for VST, "OMXD" for DMO plugins)
4 char[4] Plugin unique ID
8 uint8 Routing Flags
9 uint8 Mix Mode
10 uint8 Gain Factor * 10 (9 = 90%, 10 = 100%, 11 = 110%, etc.). A value of 0 is equal to 10 (i.e. 100%).
11 uint8 Reserved
12 uint32 Output Routing (0 = send to master 0x80 + x = send to plugin x)
16 char[16] Reserved
32 char[32] User-chosen plugin name (Windows code page)
64 char[64] Library name (Original DLL name / DMO identifier - UTF-8 starting from OpenMPT 1.22.07.01, Windows code page in older versions)
128 uint32 Length of plugin-specific data (parameters or opaque chunk)
132 char[] Plugin-specific data

'''Routing Flags:'''
* 0x01: Apply to master mix
* 0x02: Bypass effect
* 0x04: Wet Mix (dry added)
* 0x08: Expand Mix [0%,100%] → [-200%,200%]
* 0x10: Plugin will automatically suspend on silence

'''Mix Modes:'''
* 0: normal processing
* 1: MIX += DRY - WET * wetRatio
* 2: MIX += WET - DRY * dryRatio
* 3: MIX -= WET - DRY * wetRatio
* 4: MIX -= middle - WET * wetRatio + middle - DRY
* 5: MIX_L += wetRatio * (WET_L - DRY_L) + dryRatio * (DRY_R - WET_R) MIX_R += dryRatio * (WET_L - DRY_L) + wetRatio * (DRY_R - WET_R)

The first four bytes of the plugin-specific data determine the type of data. If they are all 0, then the plugin parameters follow as an array of float32 values. Otherwise, plugin type specific data follows which should be treated as an opaque chunk. For example, for VST plugins that support the effGetChunk / effSetChunk chunk, the first four bytes will be "fEvN", followed by the data to be sent to the plugin.

After the plugin information described above, more information may follow in OpenMPT modules. This information is again stored in chunks. However, there are two legacy chunks which do not have any size stored alongside the chunk identifier:

{| class="wikitable"
|-
! FOURCC !! Data Type !! Description
|-
| <code>DWRT</code> || float32 || Dry/Wet Ratio of the plugin. This chunk does not denote its size!
|-
| <code>PROG</code> || uint32 || Default plugin program (preset) to restore. This chunk does not denote its size!
|}

Any chunks that will be added in the future will have proper IFF-like chunks with a 32-bit size field.

== ModPlug Instrument Extensions (IT only) ==

To be able to address more than 256 samples in the IT format, ModPlug Tracker has an extension to store the high byte of sample indices for the instrument sample map.

By default, the last four bytes of an IT instrument (right after the pitch envelope) are unused. If they read <code>MPTX</code> or <code>XTPM</code>, 120 extra bytes follow, one for each note in the sample map. These bytes are the high byte of the sample index, i.e. they need to be multiplied by 256 and then added to the already read sample index.

== OpenMPT Extensions (General Information) ==

In the XM format, OpenMPT instrument extensions may follow the ModPlug song extensions and may in return be followed by OpenMPT song extensions.

In the IT format, OpenMPT instrument extensions may follow the sample block and may in return be followed by OpenMPT song extensions.
This is very ugly, because there might not be any samples, in which case the last thing before the extension block would be the last pattern. If there are no patterns, the last thing before the extension block would be a sample header (at least one sample header will be present even if there is no sample data – but you may even want to cover the case where there are no sample headers, for being compatible with possible future changes). So you will somehow have to keep track of the highest offset you have read into the file. If the last sample is IT-compressed, things become even more complicated: There is no way to know the compressed size of a compressed sample, so in case you want to skip sample loading, and the last sample happens to be compressed, you can do the following:
Since we know that the extended instrument and song properties start right after the last sample, and since IT-compressed samples consist of chunks with a prepended 16-bit length field, you can simply read that 16-bit number, skip this amount of bytes, then check if you can read OpenMPT's <code>XTPM</code> or <code>STPM</code> magic bytes, and if not, read the next 16-bit length, skip the bytes, etc...

In pseudo code, finding the OpenMPT extensions in an IT / MPTM file could look somewhat like this:

''offset'' = 0
''lastSampleCompressed'' = false

// In case there are no patterns and no sample data (just empty sample slots):
if(number of samples > 0):
''offset'' = last sample header pointer + sizeof(ITSampleHeader)

for all samples:
if sample is not compressed or if samples are decoded:
''lastSampleCompressed'' = false
''offset'' = max(''offset'', pointer to sample data + sample size)
else if sample is compressed and samples are not decoded:
''lastSampleCompressed'' = true
''offset'' = max(''offset'', pointer to sample data)

// In case there is no sample data:
for all patterns:
''offset'' = max(''offset'', end of pattern data)

if ''lastSampleCompressed'':
while not eof:
if next four bytes are XTPM or STPM:
''chunkID'' = next four bytes
if ''chunkID'' only contains ASCII characters (all bytes are in 32…127)
''offset'' = current position - 4; break
else
skip back 8 bytes
read uint16 value and skip as many bytes

Try reading XTPM and STPM extensions at ''offset''

The provided data types are just for orientation, i.e. the minimum recommended field size for storing the values in memory. You must expect fields to have a different size, since sometimes they do so for historic reasons. Defensive programming is your friend. Most of the FOURCCs also just make sense when read backwards, again for historic reasons. Note that some of these extensions duplicate existing functionality of the IT/XM format. In this case, the extensions take precedence over the value previous found in the file.

== OpenMPT Instrument Extensions ==

Instrument extensions start with the <code>XTPM</code> magic bytes, but there is no size indication of the total size of this block. So you have to read the following chunks and as soon as you read the <code>STPM</code> magic bytes for a chunk, you know you have read to far and can continue with reading OpenMPT Song Extensions instead.

Instrument extensions are stored in a peculiar way: There is one chunk per property, and it contains the values for all instruments at once. The layout is as follows:

=== Chunk Header Layout ===

Offset Type Content
0 char[4] Magic bytes (FOURCC)
4 uint16 Size of this chunk's entry '''for one instrument''' (i.e. total chunk content size is this field × number of instruments)

=== Chunk Contents ===

The following instrument properties exist. Some of them are redundant depending on the file type and thus not present in all files. If they are redundant, they overwrite the values that were obtained from the format-specific structures.

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..OF</code> || uint32 || IT, MPTM, XM || Fade-out
|-
| <code>...P</code> || uint32 || IT, MPTM, XM || Panning (0...256)
|-
| <code>..EV</code> || uint32 || MPTM || Number of volume envelope nodes (if ≥ 25 nodes)
|-
| <code>..EP</code> || uint32 || MPTM || Number of pan envelope nodes (if ≥ 25 nodes)
|-
| <code>.EiP</code> || uint32 || MPTM || Number of pitch envelope nodes (if ≥ 25 nodes)
|-
| <code>..BM</code> || uint16 || IT, MPTM, XM || MIDI Bank
|-
| <code>..PM</code> || uint8 || IT, MPTM, XM || MIDI Program
|-
| <code>..CM</code> || uint8 || IT, MPTM, XM || MIDI Channel
|-
| <code>.[PV</code> || uint16[] || MPTM || Volume Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EV</code> || uint8[] || MPTM || Volume Envelope Values (if ≥ 25 nodes)
|-
| <code>.[PP</code> || uint16[] || MPTM || Pan Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EP</code> || uint8[] || MPTM || Pan Envelope Values (if ≥ 25 nodes)
|-
| <code>[PiP</code> || uint16[] || MPTM || Pitch Envelope Ticks (if ≥ 25 nodes)
|-
| <code>[EiP</code> || uint8[] || MPTM || Pitch Envelope Values (if ≥ 25 nodes)
|-
| <code>.PiM</code> || uint8 || IT, MPTM, XM || Plugin, 0 = no plugin, 1 = first plugin, etc.
|-
| <code>..RV</code> || uint16 || IT, MPTM, XM || Ramping / Attack
|-
| <code>...R</code> || uint8 || IT, MPTM, XM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>..SC</code> || uint8 || IT, MPTM, XM || Cutoff Swing
|-
| <code>..SR</code> || uint8 || IT, MPTM, XM || Resonance Swing
|-
| <code>..MF</code> || uint8 || IT, MPTM, XM || Filter Mode
|-
| <code>HEVP</code> || uint8 || IT, MPTM, XM || Plugin Velocity Handling
|-
| <code>HOVP</code> || uint8 || IT, MPTM, XM || Plugin Volume Handling
|-
| <code>NREV</code> || uint8 || IT, MPTM, XM || Volume Envelope Release Node
|-
| <code>NREA</code> || uint8 || IT, MPTM, XM || Pan Envelope Release Node
|-
| <code>NREP</code> || uint8 || IT, MPTM, XM || Pitch Envelope Release Node
|-
| <code>DWPM</code> || uint8 || IT, MPTM || Pitch Wheel Depth
|-
| <code>LTTP</code> || uint16 || IT, MPTM, XM || Integer part of Pitch / Tempo Lock
|-
| <code>PTTF</code> || uint16 || MPTM || Fractional part of Pitch / Tempo Lock (0...9999)
|}

=== Legacy Extension ===

But wait, there is more! Some really old OpenMPT versions (1.17 RC1 and older, but not 1.17 RC2) do not use the instrument extensions described above. However, they also need to store the plugin reference for each instrument, which is done in another modular block following each instrument header (and possibly the <code>MPTX</code> / <code>XTPM</code> extension of that instrument header).
If this legacy extension is present, the instrument header is followed by the magic bytes <code>MSNI</code> and an uint32 containing the modular data size.

Currently there is only one chunk in this modular data block. Its FOURCC is <code>GULP</code>, has no size information and contains an uint8 for the plugin index (0 = no plugin, 1 = first plugin, etc.).

== OpenMPT Song Extensions ==

Song extensions start with the <code>STPM</code> magic bytes, but there is no size indication of the total size of this block. In an IT / XM file, these extensions are the last chunks in the file, so you can continue reading until you are out of data. In the case of MPTM files, some further MPTM-specific data follows. This data starts with the bytes "228" followed by ASCII charater 4 (not the digit), so you can keep reading the song extensions until you read this FOURCC.

=== Chunk Header Layout ===

Offset Type Content
0 char[4] Magic bytes (FOURCC)
4 uint16 Size of this chunk, excluding the header

=== Chunk Contents ===

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..TD</code> || uint32 || IT, MPTM, XM || Integer part of the default tempo (required if it is larger than 255 in IT / MPTM, but also found in legacy XM files)
|-
| <code>DTFR</code> || uint32 || MPTM || Fractional part of the default tempo (0...9999)
|-
| <code>.BPR</code> || uint32 || IT, MPTM, XM || Rows Per Beat
|-
| <code>.MPR</code> || uint32 || IT, MPTM, XM || Rows Per Measure
|-
| <code>...C</code> || uint16 || IT, MPTM || Number of channels
|-
| <code>SnhC</code> || - || IT, MPTM || If there are more than 64 channels in the IT / MTPM format, this chunk contains the default panning, volume and flags for channels 65+. They are encoded the same way as in the IT header, except that volume and panning are stored in an interleaved way (i.e. volume for channel 65, pan for channel 65, volume for channel 66, ...)
|-
| <code>..MT</code> || uint32 || IT, MPTM, XM || Tempo Mode <ul> <li>0: classic</li> <li>1: alternative</li> <li>2: modern</li> </ul>
|-
| <code>.MMP</code> || uint32 || IT, MPTM, XM || Mix Levels <ul> <li>0: Original</li> <li>1: 1.17 RC1</li> <li>2: 1.17 RC2</li> <li>3: 1.17 RC3</li> <li>4: Compatible</li> <li>5: Compatible (FT2 Pan Law)</li> </ul>
|-
| <code>.VWC</code> || uint32 || IT, MPTM, XM || OpenMPT "Created With" version (e.g. OpenMPT 1.23.45.67 = 0x01234567)
|-
| <code>VWSL</code> || uint32 || IT, MPTM, XM || OpenMPT "Last Saved With" version
|-
| <code>.APS</code> || uint32 || IT, MPTM, XM || Sample Pre-Amp
|-
| <code>VTSV</code> || uint32 || IT, MPTM, XM || VSTi Pre-Amp
|-
| <code>.VGD</code> || uint32 || XM || Global Volume (0...256)
|-
| <code>..PR</code> || uint16 || IT, MPTM || Restart Position
|-
| <code>RSMP</code> || uint32 || MPTM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>CUES</code> || - || MPTM || Sample cue points for a single sample (only MPTM format). The first uint16 in the chunk indicates for which sample slot the cue points are meant. The rest of the chunk contains all cue points as uint32s. If this chunk is missing for a particular sample slot, OpenMPT assumes the default cue points for this slot. The i-th cue point can be computed as i × 2048.
|-
| <code>SWNG</code> || - || MPTM || Contains tempo swing factors (only MPTM format). The first uint16 in the chunk indicates the number of swing rows. The rest of the chunk contains all swing factors as uint32s. A factor of 16777216 (224) is considered to be unity, i.e. does not modify the row duration. After loading, the number of swing factors should be resized to the actual number of rows per beat (in case of malformed file) and re-normalized.
|-
| <code>.FSM</code> || - || IT, MPTM, XM || A bit field of generic compatibility flags. For modules made with OpenMPT 1.25 and older, the most important one is 0x01 (first bit set), which is IT-/XM-compatible playback mode. All other flags indicate which [[Manual: Compatible Playback#Playback Compatibility Settings|compatibility settings]] are toggled.
|-
| <code>AUTH</code> || uint8[] || IT, MPTM, XM || Song artist, as UTF-8 string
|-
| <code>AMIM</code> || - || IT, MPTM, XM || MIDI Mapping settings
|-
| <code>CCOL</code> || rgbx[] || IT, MPTM, XM || Channel colors. The chunk size divided by 4 indicates the number of channels present. Format is [R, G, B, 0] for channels that have a color assigned, or [x, x, x, non-zero] for a channel with no color.
|}

== MPTM Extensions ==

=== Detecting an MPTM file ===

There are two types of hacked IT files: In early versions of the MPTM format (used in OpenMPT 1.17.02.4x), the <code>IMPM</code> magic bytes are replaced by <code>tpm.</code>, so they are not backwards compatible. Newer MPTM files use the original magic, but use a <code>cwtv</code> value between 0889h and 0FFFh (inclusive) in the header.

In both cases, the last four bytes of the file point to the start of the MPTM extensions. If the magic bytes "228" can be found at this start position, it is a valid MPTM file.

=== 228 Extensions ===

228 Extensions have been used since OpenMPT 1.17.02.48 r192 for features that are only available in the MPTM format,
such as Custom Tunings, Multiple Sequences, and Parameter Control notes.

They are documented [[Development:_228_Extensions|here]].

=== External Samples ===

MPTM files can reference external samples. If the <code>cvt</code> value in the sample header is 80h, then the sample is external. In this case, the sample pointer does not point to actual sample data but to a filename:

Offset Type Content
0 VarInt Length of the filename
? char[] Filename as UTF-8 string (not null-terminated)

Note that only the sample waveform should be loaded, but not its metadata: Frequency, loop points, volume, panning, auto-vibrato etc. should be read from the IT file. If the sample length according to the IT header is shorter than the actual sample, the sample data should be trimmed, too.

External samples are used exactly the same way in ITI files.

=== OPL Instruments ===

MPTM files can make use of OPL instruments, just like S3M files. Unlike in S3M files, patch data is not stuffed into the sample header but stored as regular sample data. To tell OPL patches apart from regular samples, the <code>cvt</code> value in the sample header is set to 40h. Note that the check for this flag should be an equal comparison (<code>cvt == 40h</code>), not a bitwise AND, due to ModPlug's legacy ADPCM sample <code>cvt</code> type (FFh). Any combination with other <code>cvt</code> flags is also considered to be illegal.

OPL2 patches are stored in the same order as in S3M files, i.e. interleaved modulator and carrier bytes, with the last (12th) byte being unused and set to 0.

=== Order list (old) ===

If the <code>cwtv</code> is between 088Bh and 088Dh (inclusive), the order list at the start of the file is replaced by the following struct:

Offset Type Content
0 uint16 Version of the order list. Only version 0 is defined. Reject any other values.
2 uint32 Number of items in the order list
6 uint32[] The order list, as a series of uint32 values. The number of values is determined by the previous field.

=== Custom Tunings (old) ===

This section is for OpenMPT versions before 1.17.02.48 r192. For newer versions, check [[Development:_228_Extensions|228 Extensions]].

Before OpenMPT 1.17.02.48 r192, the only feature that was only available in the MPTM format was Custom Tunings.
MPTM files that were made before r192 have a <code>cwtv</code> value between 0x0888 and 0x088C (inclusive).

These MPTM files contain a "Tuning Collection" chunk that contains all the custom tunings that are specific to the song (called "Tune specific tunings" in OpenMPT),
which is right after the OpenMPT song extensions.
It is then followed by a "Tuning Map" that determines which tuning each instrument should use.

A Tuning Collection could also exist separately in a <code>.TC</code> file, that can be exported/imported into an MPTM file in the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In an MPTM file, the last four bytes pointed to the start of the "Tune specific tunings" Tuning Collection,
similar to how they point to the start of 228 extensions in newer (<code>cwtv</code> > 0x088C) MPTM files.

==== Tuning Collection structure ====

The structure of a Tuning Collection is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| <code>char[4]</code>
| Tuning Collection beginning signature: <code>HSCT</code> (4 bytes)
|-
| <code>int32</code>
| Tuning Collection version: Always 1 or 2. 
|-
| <code>uint8</code> or <code>uint32</code>
| Length of the Tuning Collection's name. 
Data type:
* <code>uint8</code> if the Tuning Collection version is 2.
* <code>uint32</code> if the Tuning Collection version is 1.

|-
| <code>char[]</code>
| Tuning Collection name. The current version of OpenMPT reads a maximum of 256 (0x100) characters. 
If the collection is in a TC file, its name is the same as what it was in OpenMPT when the TC file was exported. 
But in MPTM files, only the tune-specific tuning collection is stored, and its name is always <code>Tune specific tunings</code>.
|-
| <code>int16</code>
| Tuning Collection edit mask. 
A set of 16 bits that was used to specify which settings of the tunings can be changed, but is no longer used in newer versions of OpenMPT.

|-
| <code>uint32</code>
| Number of tunings in the collection. The current version of OpenMPT does not load custom tunings at all if the number of tunings in an MPTM file is greater than 50.
|-
| (custom structure)
| The tunings in this collection, stored right after each other. The structure of a tuning is described below.
|-
| <code>char[4]</code>
| Tuning Collection end signature: <code>FSCT</code> (4 bytes)
|}

==== Tuning structure ====

The structure of a Custom Tuning is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| <code>char[8]</code>
| Tuning beginning signature: <code>CTRTI_B.</code> (8 bytes)
|-
| <code>int16</code>
| Tuning version: Always 2 or 3. 
|-
| <code>char[8]</code>
| Tuning SFS chunk beginning signature: <code>CT<sfs>B</code> (8 bytes)
|-
| <code>int16</code>
| Tuning SFS chunk version: Always 3 or 4. 
|-
| <code>uint8</code> or <code>uint32</code>
| Length of the tuning's name. 
Data type:
* <code>uint8</code> if the SFS chunk version is 4.
* <code>uint32</code> if the SFS chunk version is 3.

|-
| <code>char[]</code>
| Tuning name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|-
| <code>int16</code>
| Tuning edit mask. 
A set of 16 bits that was used to specify which settings of the tuning can be changed, but is no longer used in newer versions of OpenMPT.

|-
| <code>int16</code>
| Tuning type.
* 0: Generic
* 1: Group-geometric (originally called "Ratio-periodic")
* 3: Geometric (originally called "TET")
Newer versions of OpenMPT that use the new tuning format will convert old Geometric tunings to Group-geometric for compatibility reasons.
|-
| <code>uint16</code> or <code>uint32</code>
| Size of the tuning's note name map. Maximum value is 65535 (0xFFFF), even if the datatype is <code>uint32</code>. 
Data type:
* <code>uint16</code> if the SFS chunk version is 4.
* <code>uint32</code> if the SFS chunk version is 3.

|-
| (custom structure)
| The tuning's note name map. Contains the names of notes that have custom names. The structure is described in further below.
|-
| <code>char[8]</code>
| Tuning SFS chunk end signature: <code>CT<sfs>E</code> (8 bytes)
|-
| <code>uint16</code> or <code>uint32</code>
| Size of the tuning's ratio table. Maximum value is 65535 (0xFFFF), even if the datatype is <code>uint32</code>. This value is usually set to 256 (or 0 if the ratio table is unneeded). 
Data type:
* <code>uint16</code> if the tuning version is 3.
* <code>uint32</code> if the tuning version is 2.

|-
| <code>float32[]</code>
| The tuning's ratio table. Contains the frequency ratios for every note. If all ratios are 1, the ratio table is unneeded, so its size would be 0. 
Unlike the newer tuning format that uses 228 extensions, this table contains ratios for every note in every group, regardless of the tuning type.
|-
| <code>uint16</code> or <code>uint32</code>
| Finetune steps. Maximum value is 65535 (0xFFFF), even if the datatype is <code>uint32</code>. 
Data type:
* <code>uint16</code> if the tuning version is 3.
* <code>uint32</code> if the tuning version is 2.

|-
| <code>float32[]</code>
| An array of finetune step ratios, containing the same number of values as the finetune steps value. 
The first value is 1, and each value is r(1/finetunesteps) times the previous value, 
where r is the ratio of note 1 (the note after the middle note) to note 0 (the middle note). 
This table no longer exists in the newer tuning format that uses 228 extensions.
|-
| <code>int16</code>
| First note index in the ratio table. Usually set to -128. 
The current version of OpenMPT rejects values smaller than -200 and greater than 200.
|-
| <code>int16</code>
| Group size. 
For generic tunings, this value is 0.
|-
| <code>float32</code>
| Group ratio. 
For generic tunings, this value is 0.
|-
| <code>char[8]</code>
| Tuning end signature: <code>CTRTI_E.</code> (8 bytes)
|}

Many of the values that are stored for each tuning are redundant.
For example, the ratio table contains ratios for every note, regardless of the tuning type, even though it makes sense to
only have ratios for a single group in group-geometric tunings, and to not be stored at all in geometric tunings.
But they still have to be stored for these old versions of OpenMPT to work correctly.
However, these redundancies no longer exist in the newer tuning format that uses 228 extensions.

==== Tuning note name map structure ====

The structure of a single entry in the note name map is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| <code>int16</code>
| Note number.
|-
| <code>uint8</code> or <code>uint32</code>
| Length of the note name. 
Data type:
* <code>uint8</code> if the tuning's SFS chunk version is 4.
* <code>uint32</code> if the tuning's SFS chunk version is 3.

|-
| <code>char[]</code>
| Note name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|}

This structure is stored for every note that has a custom name.

For geometric and group-geometric tunings, only the notes of a single group, where the note numbers are between 0 and groupsize-1 (inclusive).
The note names for that single group are then applied to every group (group/octave numbers are not a part of the note name).

==== Tuning Map structure ====

The structure of a tuning map is identical to that of the new 228 tuning format (documented [[Development:_228_Extensions#Tuning_Map|here]]), but with a difference if the <code>cwtv</code> value is 0x088B or older:

The number of tunings in the map and the length of the tuning names in the map are both stored as <code>uint32</code> instead of <code>uint16</code> and <code>uint8</code> respectively.

== RIFF WAVE ==

OpenMPT uses its own <code>xtra</code> chunk in RIFF WAVE files to store some sample properties which could otherwise not be represented in the format.

Its layout is as follows:

Offset Type Content
0 uint32 Sample flags (0x20: Default panning is enabled)
4 uint16 Default panning (0...256)
6 uint16 Default volume (0...256)
8 uint16 Global volume (0...64)
10 uint16 Reserved (must be 0)
12 uint8 Auto-vibrato type
13 uint8 Auto-vibrato sweep
14 uint8 Auto-vibrato depth
15 uint8 Auto-vibrato rate

Optionally, when copying a sample to the system clipboard, the sample name (32 characters, null-padded) and filename (22 characters, null-padded) follow.

== FLAC ==

Since the FLAC format has no native and standardized way to store loop information, OpenMPT follows Renoise′s way of storing loop information: FLAC supports application-defined metadata, so OpenMPT writes a metadata block with application ID <code>riff</code>. The block contains a <code>smpl</code> chunk (as defined in the [http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/RIFFNEW.pdf RIFF specification]). Similarly, extended sample properties are stored in another <code>riff</code> application block contaning the OpenMPT-specific <code>[[#RIFF WAVE|xtra]]</code> chunk, and sample cue points are stored in a <code>cue </code> chunk.

OpenMPT also reads and writes the following non-standard vorbis comments:
* '''SAMPLERATE''': Contains the sample rate (as text) in case it would exceed the maximum sample rate supported by the FLAC format, 655350 Hz.
* '''LOOPSTART''': The start of the sample loop in frames. This tag is only read, not written.
* '''LOOPLENGTH''': The length of the sample loop in frames. This tag is only read, not written.

[[Category:Development|OpenMPT Format Extensions]]

Development: 228 Extensions

2022-02-28T12:52:54Z

CS127: /* Header Structure */ typo

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned little-endian integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specify what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the <code>mptm</code> chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (<code>6E 75 6D</code> in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-02-28T12:50:03Z

CS127: /* Adaptive Integers */ LE

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned little-endian integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specifies what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the <code>mptm</code> chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (<code>6E 75 6D</code> in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-02-26T12:52:13Z

CS127: /* Tuning Map */ ...

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specifies what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the <code>mptm</code> chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (<code>6E 75 6D</code> in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-02-26T12:50:24Z

CS127: /* Tuning */ hopefully no more typos

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specifies what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the mptm chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (<code>6E 75 6D</code> in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-02-26T12:40:16Z

CS127: /* Sequences */

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specifies what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also be exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the mptm chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (<code>6E 75 6D</code> in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** <code>cwtv</code> changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** <code>cwtv</code> changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-02-26T12:38:09Z

CS127: /* Extended Pattern Collection */ another one

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specifies what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also be exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the mptm chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (<code>6E 75 6D</code> in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** CWTV changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** CWTV changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-02-26T12:36:55Z

CS127: thats a lot of small mistakes and typos!

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specifies what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also be exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the mptm chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (6E 75 6D in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** CWTV changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** CWTV changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-02-26T12:34:58Z

CS127: /* Tuning Map */

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specifies what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also be exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the mptm chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally, there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base mptm chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (6E 75 6D in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** CWTV changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** CWTV changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-02-26T12:30:43Z

CS127:

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specifies what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also be exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the mptm chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the name.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base mptm chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (6E 75 6D in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** CWTV changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** CWTV changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-02-26T12:29:32Z

CS127:

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specifies what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also be exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the string.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the mptm chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading the name if a <code>0x00</code> byte (null character) is present anywhere in the string.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base mptm chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (6E 75 6D in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** CWTV changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** CWTV changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-02-26T12:26:57Z

CS127: /* Tuning */

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specifies what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also be exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the group ratio is greater than 0 and if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the mptm chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base mptm chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (6E 75 6D in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** CWTV changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** CWTV changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-02-26T12:25:08Z

CS127: /* Tuning */

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specifies what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also be exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]).
* For General tunings, the ratio table stores the ratios for all notes.
* For Group-geometric tunings, the ratio table stores the ratios for only the first (lowest pitch) group.
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the mptm chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base mptm chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (6E 75 6D in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** CWTV changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** CWTV changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-02-26T12:17:59Z

CS127: /* Header Structure */

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specifies what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>: all entries in this chunk have IDs with length 1, 2, or 4 respectively.
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also be exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]). 
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the mptm chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base mptm chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (6E 75 6D in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** CWTV changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** CWTV changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-02-26T12:13:33Z

CS127: /* Custom Tunings */

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specifies what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>:
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> ≥ 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also be exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]). 
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the mptm chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base mptm chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (6E 75 6D in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** CWTV changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** CWTV changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-02-26T12:10:26Z

CS127: /* 228 Chunks in MPTM Files */ unsigned integer (probably not that important but whatever)

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specifies what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>:
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain an unsigned 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> &get; 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also be exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]). 
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the mptm chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base mptm chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (6E 75 6D in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** CWTV changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** CWTV changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-02-26T11:02:06Z

CS127:

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specifies what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>:
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain a 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> &get; 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also be exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]). 
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the mptm chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base mptm chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (6E 75 6D in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** CWTV changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** CWTV changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: 228 Extensions

2022-02-26T10:59:07Z

CS127: added the page to development category

Since the OpenMPT MPTM format is based on the Impulse Tracker IT format, OpenMPT stores additional data (besides the ModPlug/OpenMPT song extensions) in MPTM files to store the settings for MPTM features like custom tunings. This additional data is stored in a chunk at the end of MPTM files (after the OpenMPT song extensions), starting with 3 bytes that read <code>228</code> when interpreted as text.

228 extensions contain settings for these features:
* Custom tunings.
* Pattern time signature overrides, and Parameter Control notes in patterns.
* All sequences and their order lists.

== Introduction ==

These are the datatypes used in this document ('''all numbers''' are stored in little-endian format):
* <code>uint8</code>, <code>uint16</code>, <code>uint32</code>, <code>uint40</code>: an unsigned integer with the given bit width.
* <code>int8</code>, <code>int16</code>, <code>int32</code>: a signed integer with the given bit width.
* <code>float32</code>: a 32-bit floating-point number.
* <code>char</code>: a text character.
* Brackets (<code>[]</code>) after a datatype specify an array of that datatype.
** If there is a number between the brackets, it is the number of items in the array.

There are also custom datatypes that are explained below:

=== Adaptive Integers ===

Adaptive integers are unsigned integer datatypes that can take less bytes to be stored (compared to regular integers), by storing their own length in themselves. In this document, the datatype of adaptive integers is written as <code>auint</code> followed by its bit depth (e.g., <code>auint64</code>).
* In a 16-bit adaptive integer, the first bit of the first byte (<code>0</code> or <code>1</code>) specifies whether the integer is stored in 1 or 2 bytes respectively. The remaining 7 or 15 bits store the integer.
* In a 32-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 3, or 4 bytes respectively. The remaining 6, 14, 22, or 30 bits store the integer.
* In a 64-bit adaptive integer, the first two bits of the first byte (<code>00</code>, <code>01</code>, <code>10</code>, or <code>11</code>) specify whether the integer is stored in 1, 2, 4, or 8 bytes respectively. The remaining 6, 14, 30, or 62 bits store the integer.

=== Strings ===

Most text strings are stored as follows: the string's length (in '''characters''') stored as a 64-bit adaptive integer, followed by the string itself. OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string, or the string is longer than 255 characters. In this document, the datatype of this type of strings is written as <code>string</code>. If a string is stored in a different format, it will be specified.

=== Additional Notes ===

* In this document, the word "ANSI" refers to the user's selected ACP codepage (<code>HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage\ACP</code>), which is '''usually''' set to 1252, but may be different depending on the system locale.

== 228 Chunk Structure ==

Each 228 chunk contains a header, a set of entries, and map.

The header contains information about the chunk, such as its number of entries, or the starting position of its map.

The main data section of the chunk can have any number of entries in it. Each entry is a set of bytes that can represent anything, such as an integer, a floating-point number, a string, or even a 228 chunk (a chunk can be an entry of another chunk).

The map contains information about the entries of the chunk, such as the ID, position, and size of each entry.

In the list and table below, features that are never written to files by the current version of OpenMPT are shown in green text (see [[#Default_Chunk_Settings|Default Chunk Settings]] for more information).

This is the general structure of a 228 chunk:

* Header
** Signature bytes (<code>228</code>)
** Chunk ID
** "Header byte"
** Additional header data, including the "flag byte"
** Numeric form of version number
** String form of version number
** Custom ID length for entries
** Fixed entry size
** Chunk description
** Timestamp
** Number of entries in the chunk
** Starting position of the map in this chunk
* Entries
** (Entry 1)
** (Entry 2)
** (Entry 3)
** (etc.)
* Map
** ID of Entry 1
** Start position of Entry 1
** Size of Entry 1
** Description of Entry 1
** ID of Entry 2
** Start position of Entry 2
** Size of Entry 2
** Description of Entry 2
** ID of Entry 3
** Start position of Entry 3
** Size of Entry 3
** Description of Entry 3
** (etc.)

=== Header Structure ===

This is the structure of the header of a chunk:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>char[3]</code>
| 3-byte signature: <code>228</code>. Identifies the start of a 228 chunk.
|-
| <code>uint8</code>
| Length of the chunk's ID (in bytes).
|-
| <code>uint8[]</code>
| The chunk's ID. Usually readable as a string, but can be any set of bytes.
|-
| <code>uint8</code>
| "Header byte". The bits of this byte specifies what is and isn't stored in the chunk.
* Bits 0 and 1 specify the length of the IDs of this chunk's entries, '''only if''' bit 0 of this chunk's "flag byte" (explained later) is '''not set''', or if the chunk does not have a "flag byte" at all.
** <code>00</code>: all entries in this chunk have IDs with length 0 (i.e., they do not have IDs).
** <code>01</code>, <code>10</code>, <code>11</code>:
* Bit 2: whether this chunk's map stores the starting position of each entry.
* Bit 3: whether this chunk's map stores the size of each entry.
* Bit 4: whether this chunk's header stores a numeric form of its version number.
* Bit 5: whether this chunk's header stores a string (text) form of its version number.
* Bit 6: whether each text character used in descriptions (explained later) uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252).
* Bit 7: whether this chunk's map contains descriptions for this entry.
|-
| <code>auint32</code>
| Size of additional header data.
|-
| <code>uint8[]</code>
| Additional header data. 
If the additional header data is at least 2 bytes long, '''and''' the first byte is <code>0x00</code>, the second byte is read as the "flag byte". 
The bits of the flag byte contain additional information about the chunk:
* Bit 0: whether the chunk uses custom ID lengths for its entries.
* Bit 1: whether all entries in this chunk have a fixed size.
* Bit 2: whether the chunk contains a description about itself.
* Bit 3: whether the chunk contains a timestamp.
The flag byte does not need to exist if none of its bits are supposed to be set.
|-
| <code>auint64</code>
| Numeric form of the version number. Usually contains the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions, but there are exceptions. 
This adaptive integer only exists if bit 4 of the header byte is set.
|-
| <code>uint8</code>
| Length of the string form of the version number, in bytes. 
This byte only exists if bit 5 of the header byte is set.
|-
| <code>char[]</code>
| String form of the version number. It was never used in any version of OpenMPT. 
This string only exists if bit 5 of the header byte is set.
|-
| <code>uint8</code>
| Custom ID length for entries.
* If bit 0 is set, the length of the IDs of this chunk's entries are not constant, and are stored next to the IDs in the map. In this case, the remaining 7 bits of this byte are ignored.
* If bit 0 is not set, the length of the IDs of this chunk's entries are stored in the remaining 7 bits of this byte.
This byte only exists if the chunk has a flag byte and its bit 0 is set.
|-
| <code>auint32</code>
| Fixed entry size. Determines the size of all entries in this chunk. 
This adaptive integer only exists if the chunk has a flag byte and its bit 1 is set.
|-
| <code>auint16</code>
| Length of this chunk's description (in characters). 
This adaptive integer only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>char[]</code>
| Chunk description. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one byte (ISO-8859-1 / Windows-1252). 
This string only exists if the chunk has a flag byte and its bit 2 is set.
|-
| <code>uint40</code>
| Timestamp, stored as a little-endian unsigned integer in 5 bytes (40 bits). 
This was originally intended to store the Unix time (number of seconds past 1970-01-01 00:00:00 UTC) at the time of saving the file. 
This integer only exists if the chunk has a flag byte and its bit 3 is set.
|-
| <code>auint64</code>
| Number of entries in this chunk.
|-
| <code>auint64</code>
| Start position of this chunk's map, relative to the start of this chunk (where the <code>228</code> bytes start). 
This adaptive integer does not exist if this chunk does not have a map (see [[#Map_Structure|the section on maps]] for an explanation on whether a map exists or not).
|}

=== Entry Structure ===

The entries in a chunk start right where the header ends. Entries are just sets of bytes, and they are stored right after each other.

Entries of a chunk can be chunks themselves, allowing a chunk to be "nested" in another chunk by being one of the outer chunk's entries. Note that a nested chunk is a chunk on its own, and its header, entries, and map have nothing to do with those of the outer chunk that contains it.

Additionally, each entry can have an ID, and if said entry is a chunk, its entry ID when referred to as an entry of the outer chunk is '''not necessarily related''' to its chunk ID (which is stored in the inner chunk's header). '''It can be the same ID or a different one'''.
That is very important to know, because OpenMPT stores a lot of inner chunks as entries of other chunks, so having to deal with their IDs can be quite confusing.

Note: Entries do '''not''' need to be stored in a specific order, '''as long as the chunk that contains them specifies entry IDs in its map'''.

=== Map Structure ===

Chunks usually have maps. A chunk will not have a map if bits 2, 3, and 7, of the header byte, are not set, and the ID length for entries is fixed to 0. However, chunks written by the current version of OpenMPT do not meet this requirement, so they always have maps. If a chunk, does not have a map, its header will also not store the start position of the map.

This is the structure of a section of a map corresponding to a '''single entry''':
{| class="wikitable
|-
! Datatype
! Content/Description
|-
| <code>auint16</code>
| Length of the entry's ID. 
This adaptive integer only exists if the ID length for entries is not fixed (i.e., bit 0 of the flag byte and bit 0 of the custom ID length byte are both set).
|-
| <code>uint8[]</code>
| The entry's ID. Usually readable as a string, but can be any set of a bytes.
|-
| <code>auint64</code>
| Start position of this entry in the chunk, relative to the start of the chunk itself. 
This adaptive integer only exists if bit 2 of the header byte is set.
|-
| <code>auint64</code>
| Size of this entry in the chunk (in bytes). 
This adaptive integer only exists if bit 3 of the header byte is set, and bit 1 of the flag byte is '''not''' set (or if there is no flag byte).
|-
| <code>auint16</code>
| Length of this entry's description (in characters). 
This adaptive integer only exists if bit 7 of the header byte is set.
|-
| <code>char[]</code>
| Description of the entry. If bit 6 of the header byte is set, each character uses two bytes (Unicode BMP) instead of one (ISO-8859-1 / Windows-1252). 
This string only exists if bit 7 of the header byte is set.
|}

An entire map of a chunk is made of several copies of the structure shown in the table above, each copy corresponding to one of the entries of the chunk.

Note: The sections of a chunk's map which each correspond to an entry, do '''not''' need to be in the same order as the way the entries themselves are stored in the chunk, '''as long as the chunk specifies starting positions and sizes of entries in the map'''.

== 228 Chunks in MPTM Files ==

Reading the previous sections of this document is absolutely necessary to understand the rest of this document!

The last four bytes of a valid MPTM file should contain a 32-bit integer that points to the starting position of the 228 chunks in the file. The 228 chunks are stored after the OpenMPT song extensions, and before the last four bytes of the file.

There is supposed to be at least one chunk with an ID of <code>mptm</code> (<code>6D 70 74 6D</code> in hex bytes), which contains all the settings for MPTM features (like custom tunings) in its entries.

=== Default Chunk Settings ===

'''ALL chunks''' (and their "sub-chunks", a.k.a. the entries that are chunks themselves) that are '''written by the current version of OpenMPT''' have a header byte of <code>00011111</code> (<code>0x1F</code>), an additional header data size of 2 (byte <code>00001000</code> (<code>0x08</code>)), a flag byte of <code>00000001</code> (<code>0x01</code>) and a "custom entry ID length" byte of <code>00000001</code> (<code>0x01</code>).

This means that all chunks written by the current version of OpenMPT:
* Have a map.
* Have variable ID lengths for their entries, so they have to be stored in the map.
* Store the starting position of their entries in their maps.
* Store the size of their entries in their maps.
* Store the numeric form of their version number in their headers.
* Do '''not''' store a string form of their version number in their headers.
* Do '''not''' store a timestamp in their headers.
* Do '''not''' store descriptions about themselves in their headers.
* Do '''not''' store descriptions about their entries in their maps.
* Do '''not''' have fixed sizes for their entries.

However, OpenMPT '''does''' know how to properly read any chunks that were written by older versions of OpenMPT or by modifying a file using some external program, even if the chunks do '''not''' have the properties described above, '''as long as the structure of the chunks are written "correctly"'''.

Files made with really old versions of OpenMPT, especially earlier versions of 1.17, may have differences in their header bytes and flag bytes compared to recent versions, but the chunk structure is always correct.

Additionally, new chunks and entries have been added to many versions, such as the Custom Tuning UTF-8 entry, which specifies that the names of custom tunings are encoded in UTF-8. Files with custom tunings that have been made with OpenMPT 1.29.00.40 or older will not have that entry, causing newer versions of OpenMPT to correctly read the names in the ANSI encoding.

=== Main Chunk ===

As of OpenMPT 1.17.03.01 r323, the <code>mptm</code> chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401). Before r323, the chunk's version number was 1.

=== Custom Tunings ===

This section documents how custom tunings are stored in MPTM files made with OpenMPT 1.17.02.48 r192 and newer (<code>cwtv</code> &get; 0x088D). In older versions, custom tunings are the only MPTM feature, and they do not use 228 chunks. The old format is documented in [[Development:_OpenMPT_Format_Extensions#Custom_Tunings_(old)|OpenMPT Format Extensions § Custom Tunings (old)]].

Entries containing custom tunings are stored in the <code>mptm</code> chunk, and only if the song has (or uses) any custom tunings (the default IT tuning does not count).

==== UTF-8 Text Encoding Indicator ====

This entry is a single byte with an entry ID of <code>UTF8Tuning</code> (<code>55 54 46 38 54 75 6E 69 6E 67</code> in hex bytes), stored as one of the entries of the base <code>mptm</code> chunk. It determines the global text encoding of the names of the tunings (and their note names). However, the tuning collection and each tuning can have their own text encoding indicator that overrides this one.

* If this entry exists and its byte value is not 0: UTF-8.
* If this entry does not exist or its byte value is 0: ANSI.

Currently, OpenMPT always writes this entry with a value of 1 (UTF-8). It will be written if there are any custom tunings, even if no instruments use them.

==== Tuning Collection ====

Tuning collections are chunks that contain custom tunings. They can exist separately in .TC files and can be imported into MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In MPTM files, there is only one tuning collection called the "Tune-specific" tuning collection. For MPTM files made with OpenMPT versions older than 1.27.00.55, although there are "local tunings" and "built-in tunings" (which are now discontinued) besides the "tune-specific" ones, they are '''not''' stored in the MPTM files themselves.

In MPTM files, the "tune-specific tunings" collection is stored as an entry of the base <code>mptm</code> chunk, and its entry ID (stored in the map of the <code>mptm</code> chunk) is <code>0</code> (<code>30</code> in hex bytes).

* The entry ID of the "tune-specific tunings" collection chunk in MPTM files, which is stored in the map of the <code>mptm</code> chunk, is <code>0</code> (<code>30</code> in hex bytes).
* The chunk ID of any tuning collection chunk (regardless of the collection type, or whether it is stored in an MPTM or TC file), which is stored in its own header, is <code>TC</code> (<code>54 43</code> in hex bytes).

The chunk's version number is 3.

These are the entries stored in a tuning collection (<code>TC</code>) chunk:
{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of this collection's name, and the name of its tunings.
* If this entry exists and its byte value is not 0: UTF-8 (override global encoding).
* If this entry does not exist or its byte value is 0: Inherit encoding from global encoding.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The collection's name. 
In TC files, the name would be the same as what it was when the TC file was exported in OpenMPT. 
In MPTM files, the only stored tuning collection is the Tune-specific tunings, and its name is <code>Tune specific tunings</code>.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The collection's edit mask. This value was used to specify which settings of the collection can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|}

In addition to the three entries listed above, the rest of the entries are all chunks, where each one is a custom tuning. They all have an entry ID of <code>2</code> (<code>32</code> in hex bytes).

==== Tuning ====

As described above, each custom tuning is stored as a chunk, as one of the entries of a tuning collection (<code>TC</code>) chunk.

For each custom tuning:
* Its entry ID, which is stored in the map of the <code>TC</code> chunk, is <code>2</code>(<code>32</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is <code>CTB244RTI</code> (<code>43 54 42 32 34 34 52 54 49</code> in hex bytes).

The chunk's version number is 67108868 (<code>0x04000004</code> in hex).

These custom tuning chunks can also be exist separately in .TUN files, and can be exported from / imported to MPTM files using the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

These are the entries stored in a custom tuning (<code>CTB244RTI</code>) chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>UTF8</code>
| <code>55 54 46 38</code>
| <code>uint8</code>
| The text encoding of the tuning's name.
* If this entry exists and its value is not 0: UTF-8 (override collection's encoding).
* If this entry does not exist or its value is 0: Inherit encoding from collection's encoding.
|-
| <code>0</code>
| <code>30</code>
| <code>string</code>
| The custom tuning's name.
|-
| <code>1</code>
| <code>31</code>
| <code>uint16</code>
| The tuning's edit mask. This value was used to specify which settings of the tuning can be changed, but it is no longer used. 
Currently, OpenMPT always writes this entry with a value of 0xFFFF (allow editing everything).
|-
| <code>2</code>
| <code>32</code>
| <code>uint16</code>
| Tuning type.
* 0 = General
* 1 = Group-geometric
* 3 = Geometric
Any other value will result in OpenMPT failing to load the custom tuning data.
|-
| <code>3</code>
| <code>33</code>
| (custom structure)
| Note names (see [[#Tuning_Note_Name_Structure|the Tuning Note Name Structure]]). 
If this entry does not exist, OpenMPT will use the "default" note names (the predefined note names when creating a new tuning in OpenMPT).
|-
| <code>4</code>
| <code>34</code>
| <code>uint32</code>
| Finetune steps.
|-
| <code>RTI0</code>
| <code>52 54 49 30</code>
| (custom structure)
| Ratio table (see [[#Tuning_Ratio_Table_Structure|the Ratio Table Structure]]). 
OpenMPT only writes this entry if the tuning type is General or Group-geometric.
|-
| <code>RTI1</code>
| <code>52 54 49 31</code>
| <code>int16</code>
| First note index. 
OpenMPT writes this entry for all types of tunings, and usually with a value of -64.
|-
| <code>RTI2</code>
| <code>52 54 49 32</code>
| <code>uint16</code>
| Group size. 
OpenMPT only writes this entry if the tuning type is Geometric. 
(For group-geometric tunings, the group size is equal to the size of the ratio table.)
|-
| <code>RTI3</code>
| <code>52 54 49 33</code>
| <code>float32</code>
| Group ratio. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geometric.
|-
| <code>RTI4</code>
| <code>52 54 49 34</code>
| <code>uint16</code>
| Number of ratios in the ratio table. 
OpenMPT only writes this entry if the tuning type is Geometric or Group-geomtric, with a value of 128 for Geometric tunings, and the group size for Group-geometric tunings.
|}

===== Tuning Note Name Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of note names. 
OpenMPT uses the same number as the group size for Geometric and Group-geometric tunings, and 128 for General tunings.
|}

After the adaptive integer above, there are multiple note names that specify the names of notes in the entire table of notes (in Generic tunings) or only the notes of a single group (in Geometric and Group-geometric tunings).

This is the structure of a single note name:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>int16</code>
| Note index. A zero-based index specifying which note this name corresponds to (0=first note, 1=second note, etc.)
|-
| <code>uint8</code>
| Length of the note name.
|-
| <code>char[]</code>
| Note name. The text encoding is inherited from the custom tuning's text encoding entry. 
OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string.
|}

The structure above is repeated for every note (or every note '''in the group''' if the tuning is Geometric or Group-geometric) that has a custom name.

Note: In Geometric and Group-geometric tunings, the group numbers / octave numbers are '''not''' a part of the note names.

===== Tuning Ratio Table Structure =====

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>auint64</code>
| Number of ratios in the ratio table.
OpenMPT writes the same number as the group size for Group-geometric tunings, and 128 for General tunings.
|-
| <code>float32[]</code>
| Ratios. 
For Group-geometric tunings, only the ratios of the first (lowest pitch) group are stored.
|}

==== Tuning Map ====

(Not to be confused with "maps" of chunks!)

The tuning map is one of the entries of the base <code>mptm</code> chunk. It is a structure that stores what tuning each instrument should use. Its entry ID, stored in the map of the mptm chunk, is <code>1</code> (<code>31</code> in hex bytes).

In a file made using OpenMPT 1.27.00.55 or older, local and built-in tunings are also specified in the tuning map, even though they are not written to the tuning collection chunk. If the file is loaded in newer versions, they will be converted to tune-specific ones and will then be stored in the MPTM file's tune-specific tuning collection chunk.

The first item in the structure is a <code>uint16</code>, containing the number of tunings that are used by instruments, including the default IT tuning and non-tune-specific tunings:
{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Number of tunings that are used by instruments, including non-tune-specific tunings.
|}

Following the number of tunings, there are mappings that map each tuning to an index number. This is the structure of a single tuning-to-index mapping:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint8</code>
| Length of the tuning's name (in characters).
|-
| <code>char[]</code>
| The tuning's name.
* The name of the default IT tuning (called <code>OpenMPT IT behaviour</code> in OpenMPT), is written as <code>->MPT_ORIGINAL_IT<-</code>.
* In files made with OpenMPT 1.27.00.55 or older, the names of the built-in tunings are written as <code>12TET</code> and <code>12TET <nowiki>[[fs15 1.17.02.49]]</nowiki></code>.
OpenMPT will stop reading a string if a <code>0x00</code> byte (null character) is present anywhere in the string.
|-
| <code>uint16</code>
| The index that this tuning is mapped to.
|}

The structure shown in the table above is repeated for every tuning.

Finally there is an array of <code>uint16</code>s, each one corresponding to an instrument of the song, where the value of each one is the index that is mapped to the tuning that the corresponding instrument should use.

Note: Due to the way the tunings are located when a file is loaded, if there are multiple tunings with the same name, some instruments might be loaded with the wrong tunings.

=== Extended Pattern Data ===

Extended pattern data is used to store data for patterns that use features exclusive to the MPTM format: Pattern-specific time signature overrides and Parameter Control notes.

All extended pattern data is stored in a "pattern collection" chunk.

==== Extended Pattern Collection ====

The pattern collection is a chunk, stored as one of the entries of the base mptm chunk. It contains extended pattern data.
* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptPc</code> (<code>6D 70 74 50 63</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

The entries stored in the <code>mptPc</code> chunk consist of "extended pattern" chunks, and a <code>uint16</code> with an entry ID of <code>num</code> (6E 75 6D in hex bytes) which specifies how many patterns will have their extended data read when loading the file. Its recommended value is the number of patterns in the song, but the song will still be loaded correctly if the number is at least bigger than the last pattern number that uses extended data.

If any pattern has extended data, OpenMPT writes the extended data for all patterns (not just the required ones), followed by the <code>num</code> entry containing the number of patterns in the song.

==== Extended Pattern ====

As described above, the extended data for each pattern is stored as a chunk, as one of the entries of the <code>mptPc</code> chunk.

For each pattern:
* Its entry ID, which is stored in the map of the <code>mptPc</code> chunk, is a little-endian 16-bit unsigned integer, specifying its pattern number (pattern 0 = 0x0000, pattern 1 = 0x0001, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptP</code> (<code>6D 70 74 50</code> in hex bytes)

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptP</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>data</code>
| <code>64 61 74 61</code>
| (custom structure)
| The extended pattern data. Currently only used for Parameter Control notes. 
Stored in the same format as the IT pattern format, but without the first 8 bytes. 
It is used to only store the pattern's Parameter Control notes, and uses a different format for mask bytes:
* Bit 0: Note included (PC or PCs)
* Bit 1: Plugin number included
* Bit 2: High byte of controller ID included
* Bit 3: Low byte of controller ID included
* Bit 4: High byte of parameter included
* Bit 5: Low byte of parameter included
* Bit 6: Extra data included
The bytes after the mask byte (specifically the ones that need to be written) are written in the same order shown in the list above. 
For the note value:
* PC notes are stored as <code>0xFC</code>
* PCs notes are stored as <code>0xFB</code>
The extra data (enabled via bit 6 of the mask byte) consists of an 8-bit unsigned integer specifying the size, followed by a set of bytes of that size. It is ignored by OpenMPT. 
Any data that is specified by the mask byte to '''not''' be included will have the same data as the previous PC/PCs note in the channel. 
OpenMPT writes this entry for all patterns, even if they do not contain PC/PCs notes.
|-
| <code>RPB.</code>
| <code>52 50 42 2E</code>
| <code>uint32</code>
| Custom "rows per beat" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>RPM.</code>
| <code>52 50 4D 2E</code>
| <code>uint32</code>
| Custom "rows per measure" value for this pattern. 
OpenMPT only writes this entry for patterns that use a custom time signature.
|-
| <code>SWNG</code>
| <code>53 57 4E 47</code>
| (custom structure)
| Custom tempo swing for this pattern. 
Stored in the same format as the <code>SWNG</code> value in the OpenMPT song extensions. 
OpenMPT only writes this entry for patterns that use a custom tempo swing.
|}

=== Sequences ===

Currently, the main way sequences are stored is a "sequence collection" chunk, but there is also an older format that was used when an MPTM file could only have one sequence, which is still used by OpenMPT to make the file somewhat compatible with those old versions.
Here is a history of how order lists were stored throughout different versions:
* 2006-08-20: OpenMPT 1.17.02.45, r166 (MPTM format introduced)
** Only one sequence, order list stored at 0x00C0 (exactly like Impulse Tracker).
* 2006-10-02: OpenMPT 1.17.02.45, r168
** CWTV changed from 0x088A to 0x088B.
** The order list stored at 0x00C0 now uses a custom structure (documented in [[Development:_OpenMPT_Format_Extensions#Order_list_(old)|OpenMPT Format Extensions § Order list (old)]]), and uses 32-bit pattern indices instead of 8-bit, allowing patterns over 253.
* 2008-01-12: OpenMPT 1.17.02.49, r195
** CWTV changed from 0x088D to 0x088E.
** The order list stored at 0x00C0 now stores orders like Impulse Tracker again, which is limited up to pattern 253. However, there is now an entry in the <code>mptm</code> chunk that is used to store the order list if there are patterns over 253. If a file has this chunk, OpenMPT will read the order list from this chunk, and not from 0x00C0.
* 2009-09-16: OpenMPT 1.17.03.01, r366
** MPTM files can now have multiple sequences, where one of them can be the "default sequence". All sequences are now stored in a 228 chunk called the "sequence collection" chunk. A copy of the default sequence will also be stored at 0x00C0, and the old sequence entry if there are patterns over 253. However, in these new files, OpenMPT will ignore the order list at 0x00C0 entirely. This means that if there is no sequence collection or old sequence entry, even if there is an order list at 0x00C0, OpenMPT will load the file without an order list.


In the rest of this document, the new multi-sequence format introduced in r366 is documented first, and after that is the "old" sequence format introduced in r195 (which is still written to files if the default sequence contains patterns beyond 253).

==== Sequence Collection (r366 and newer) ====

The sequence collection is a chunk, stored as one of the entries of the base <code>mptm</code> chunk. It contains the sequences of the MPTM file.

* Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).
* Its chunk ID, which is stored in its own header, is also <code>mptSeqC</code> (<code>6D 70 74 53 65 71 43</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in the <code>mptSeqC</code> chunk:

{| class="wikitable"
|-
! Entry ID
! Entry ID (hex bytes)
! Datatype
! Content/Description
|-
| <code>n</code>
| <code>6E</code>
| <code>uint8</code>
| Number of sequences in the file.
|-
| <code>c</code>
| <code>63</code>
| <code>uint8</code>
| The "default sequence" of the file. 
Uses zero-based numbering. (0=first sequence, 1=second sequence, etc.) 
The "default sequence" is the one that is selected (the one shown in the order list) when the file is loaded, or the last time the file was saved. 
It is also the one that is stored in the IT order list at 0x00C0 (and the old sequence entry if it contains patterns over 253).
|}

In addition to the two entries listed above, the rest of the entries are all chunks, each one representing a sequence. Each one has an entry ID of the corresponding sequence's number, as a byte, with 0-based numbering.

For example, the ID of the entry corresponding to the first sequence is a 0x00 byte. If a second sequence existed, its entry ID would be 0x01, the next would be 0x02, and so on.

Currently, OpenMPT only allows creating up to 50 (0x32 in hex) sequences, so the limit (0xFF) is never reached (at least without editing the file externally).

==== Sequence (r366 and newer) ====

As described above, each sequence is stored as a chunk, as one of the entries of the mptSeqC chunk.
For each sequence:

* Its entry ID, which is stored in the map of the <code>mptSeqC</code> chunk, is a single byte that determines which sequence it is (sequence 1 = 0x00, sequence 2 = 0x01, and so on).
* Its chunk ID, which is stored in its own header, is <code>mptSeq</code> (<code>6D 70 74 53 65 71</code> in hex bytes).

The chunk's version number is the same integer stored in the <code>VWSL</code> value in the OpenMPT song extensions (e.g., 1.29.14.01 would be 0x01291401).

These are the entries stored in an <code>mptSeq</code> chunk:

{| class="wikitable"
|-
| Entry ID
| Entry ID (hex bytes)
| Datatype
| Content/Description
|-
| <code>u</code>
| <code>75</code>
| <code>uint8</code>
| The text encoding of the sequence's name. 
* If this entry exists and its value is not 0: UTF-8.
* If this entry does not exist or its value is 0: ANSI.
The current version of OpenMPT always writes this entry with a value of 1 (UTF-8).
|-
| <code>n</code>
| <code>6E</code>
| (custom structure)
| Sequence name. 
Contains the length of the name ('''in bytes, not characters'''), followed by the name. 
The length is stored similarly to a 32-bit adaptive integer, except that the two bits that specify the size of the adaptive integer are bits 2 and 3 instead of 0 and 1, and bits 0 and 1 are unused.
Depending on bits 2 and 3, the remaining 4, 12, 20, or 28 bits store the integer, which in this case, is the length of the name (in bytes).
|-
| <code>l</code>
| <code>6C</code>
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>a</code>
| <code>61</code>
| <code>uint16[]</code>
| The sequence's order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|-
| <code>r</code>
| <code>72</code>
| <code>uint16</code>
| Restart position. OpenMPT only writes this entry if the sequence's restart position is not 0.
|}

==== "Old" Sequence (r195 and newer) ====

The old r195 sequence, which is used to store the default sequence if it has orders corresponding to patterns over 253, is a simple structure stored as one of the entries of the base <code>mptm</code> chunk. Its entry ID, which is stored in the map of the <code>mptm</code> chunk, is <code>2</code> (<code>32</code> in hex bytes).

The structure of this entry is as follows:

{| class="wikitable"
|-
! Datatype
! Content/Description
|-
| <code>uint16</code>
| Length of the sequence (in orders).
|-
| <code>uint16[]</code>
| The order list. Each order has the pattern number associated with it stored as a <code>uint16</code>. 
For special ("non-pattern") orders:
* <code>+++</code> (separator) orders are stored as 0xFFFE.
* <code>---</code> (end of song) orders are stored as 0xFFFF.
|}

[[Category:Development|228 Extensions]]

Development: OpenMPT Format Extensions

2022-02-26T10:06:08Z

CS127: /* MPTM Extensions */ oops typo

ModPlug Tracker and OpenMPT have extended the IT and XM formats in various ways. In general, these hacks are frowned upon, but here is some documentation on those hacks in case you want to support them in your own player. I am really sorry about all this mess, but all of this has grown historically way before I joined OpenMPT development.

Presence of these format extensions in a file does not necessarily imply that it was created with ModPlug Tracker or OpenMPT. Some of the extensions are also used e.g. by BeRoTracker.

Any numeric values are stored in little-endian format, unless noted otherwise.

Data types used in this document:
* uint8, uint16, uint32: Unsigned integers with the given bit width.
* int8, int16, int32: Signed integers with the given bit width.
* char: A single character (i.e. a byte)
* float32: Single precision IEEE float
* VarInt: A MIDI-like variable-length unsigned integer (big-endian value where the highest bit of each byte indicates if another byte follows, and the lower 7 bits containing the actual number).
* Square brackets [] denote an array of values:
** [] is a variable-length array (length is deduced from some other attribute)
** [42] denotes an array with 42 entries.

== ModPlug Song Extensions ==

The following extensions exist since the (closed-source) ModPlug Tracker days. These extensions are found in [https://en.wikipedia.org/wiki/Interchange_File_Format IFF]-like chunks, but without any padding bytes. The chunks are placed right after the header data in the IT format (i.e. after the edit history / MIDI macro block). In the XM format these chunks are placed right at the end of the file (i.e. after the sample data). At the time of writing, these chunks are always written out in the order described here, but if possible you should probably try to read them without expecting a certain order. All chunks are optional.

=== Chunk Header Layout ===

Offset Type Content
0 char[4] Magic bytes (FOURCC)
4 uint32 Size of this chunk, excluding the header

=== Chunks ===

==== text (XM only) ====

Contains the song message (CR line endings), its length is determined by the chunk size.

==== MIDI (XM only) ====

Contains the MIDI macro configuration, in the same format as in the IT format.

==== PNAM ====

Contains the pattern names. Each pattern name is 32 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The pattern names are stored continuously, i.e. there are (chunk size / 32) pattern names in the chunk, for pattern 0, pattern 1, ... pattern (chunk size / 32 - 1).

==== CNAM ====

Contains the channel names. Each channel name is 20 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The channel names are stored continuously, i.e. there are (chunk size / 20) channel names in the chunk, for channel 1, channel 2, ... channel (chunk size / 20).

==== CHFX ====

Contains the plugin assignment for each channel. For every channel, there is a 32-bit integer plugin index. 0 means no plugin, 1 is the first plugin, etc...

==== FX00, ... FX99, F100, ... F255 ====

Contains plugin information for each plugin slot. <code>FX00</code> contains the information for the first plugin slot, <code>FX99</code> for the 100th, <code>F100</code> for the 101st, etc...

Offset Type Content
0 char[4] Plugin type ("PtsV" for VST, "OMXD" for DMO plugins)
4 char[4] Plugin unique ID
8 uint8 Routing Flags
9 uint8 Mix Mode
10 uint8 Gain Factor * 10 (9 = 90%, 10 = 100%, 11 = 110%, etc.). A value of 0 is equal to 10 (i.e. 100%).
11 uint8 Reserved
12 uint32 Output Routing (0 = send to master 0x80 + x = send to plugin x)
16 char[16] Reserved
32 char[32] User-chosen plugin name (Windows code page)
64 char[64] Library name (Original DLL name / DMO identifier - UTF-8 starting from OpenMPT 1.22.07.01, Windows code page in older versions)
128 uint32 Length of plugin-specific data (parameters or opaque chunk)
132 char[] Plugin-specific data

'''Routing Flags:'''
* 0x01: Apply to master mix
* 0x02: Bypass effect
* 0x04: Wet Mix (dry added)
* 0x08: Expand Mix [0%,100%] → [-200%,200%]
* 0x10: Plugin will automatically suspend on silence

'''Mix Modes:'''
* 0: normal processing
* 1: MIX += DRY - WET * wetRatio
* 2: MIX += WET - DRY * dryRatio
* 3: MIX -= WET - DRY * wetRatio
* 4: MIX -= middle - WET * wetRatio + middle - DRY
* 5: MIX_L += wetRatio * (WET_L - DRY_L) + dryRatio * (DRY_R - WET_R) MIX_R += dryRatio * (WET_L - DRY_L) + wetRatio * (DRY_R - WET_R)

The first four bytes of the plugin-specific data determine the type of data. If they are all 0, then the plugin parameters follow as an array of float32 values. Otherwise, plugin type specific data follows which should be treated as an opaque chunk. For example, for VST plugins that support the effGetChunk / effSetChunk chunk, the first four bytes will be "fEvN", followed by the data to be sent to the plugin.

After the plugin information described above, more information may follow in OpenMPT modules. This information is again stored in chunks. However, there are two legacy chunks which do not have any size stored alongside the chunk identifier:

{| class="wikitable"
|-
! FOURCC !! Data Type !! Description
|-
| <code>DWRT</code> || float32 || Dry/Wet Ratio of the plugin. This chunk does not denote its size!
|-
| <code>PROG</code> || uint32 || Default plugin program (preset) to restore. This chunk does not denote its size!
|}

Any chunks that will be added in the future will have proper IFF-like chunks with a 32-bit size field.

== ModPlug Instrument Extensions (IT only) ==

To be able to address more than 256 samples in the IT format, ModPlug Tracker has an extension to store the high byte of sample indices for the instrument sample map.

By default, the last four bytes of an IT instrument (right after the pitch envelope) are unused. If they read <code>MPTX</code> or <code>XTPM</code>, 120 extra bytes follow, one for each note in the sample map. These bytes are the high byte of the sample index, i.e. they need to be multiplied by 256 and then added to the already read sample index.

== OpenMPT Extensions (General Information) ==

In the XM format, OpenMPT instrument extensions may follow the ModPlug song extensions and may in return be followed by OpenMPT song extensions.

In the IT format, OpenMPT instrument extensions may follow the sample block and may in return be followed by OpenMPT song extensions.
This is very ugly, because there might not be any samples, in which case the last thing before the extension block would be the last pattern. If there are no patterns, the last thing before the extension block would be a sample header (at least one sample header will be present even if there is no sample data – but you may even want to cover the case where there are no sample headers, for being compatible with possible future changes). So you will somehow have to keep track of the highest offset you have read into the file. If the last sample is IT-compressed, things become even more complicated: There is no way to know the compressed size of a compressed sample, so in case you want to skip sample loading, and the last sample happens to be compressed, you can do the following:
Since we know that the extended instrument and song properties start right after the last sample, and since IT-compressed samples consist of chunks with a prepended 16-bit length field, you can simply read that 16-bit number, skip this amount of bytes, then check if you can read OpenMPT's <code>XTPM</code> or <code>STPM</code> magic bytes, and if not, read the next 16-bit length, skip the bytes, etc...

In pseudo code, finding the OpenMPT extensions in an IT / MPTM file could look somewhat like this:

''offset'' = 0
''lastSampleCompressed'' = false

// In case there are no patterns and no sample data (just empty sample slots):
if(number of samples > 0):
''offset'' = last sample header pointer + sizeof(ITSampleHeader)

for all samples:
if sample is not compressed or if samples are decoded:
''lastSampleCompressed'' = false
''offset'' = max(''offset'', pointer to sample data + sample size)
else if sample is compressed and samples are not decoded:
''lastSampleCompressed'' = true
''offset'' = max(''offset'', pointer to sample data)

// In case there is no sample data:
for all patterns:
''offset'' = max(''offset'', end of pattern data)

if ''lastSampleCompressed'':
while not eof:
if next four bytes are XTPM or STPM:
''chunkID'' = next four bytes
if ''chunkID'' only contains ASCII characters (all bytes are in 32…127)
''offset'' = current position - 4; break
else
skip back 8 bytes
read uint16 value and skip as many bytes

Try reading XTPM and STPM extensions at ''offset''

The provided data types are just for orientation, i.e. the minimum recommended field size for storing the values in memory. You must expect fields to have a different size, since sometimes they do so for historic reasons. Defensive programming is your friend. Most of the FOURCCs also just make sense when read backwards, again for historic reasons. Note that some of these extensions duplicate existing functionality of the IT/XM format. In this case, the extensions take precedence over the value previous found in the file.

== OpenMPT Instrument Extensions ==

Instrument extensions start with the <code>XTPM</code> magic bytes, but there is no size indication of the total size of this block. So you have to read the following chunks and as soon as you read the <code>STPM</code> magic bytes for a chunk, you know you have read to far and can continue with reading OpenMPT Song Extensions instead.

Instrument extensions are stored in a peculiar way: There is one chunk per property, and it contains the values for all instruments at once. The layout is as follows:

=== Chunk Header Layout ===

Offset Type Content
0 char[4] Magic bytes (FOURCC)
4 uint16 Size of this chunk's entry '''for one instrument''' (i.e. total chunk content size is this field × number of instruments)

=== Chunk Contents ===

The following instrument properties exist. Some of them are redundant depending on the file type and thus not present in all files. If they are redundant, they overwrite the values that were obtained from the format-specific structures.

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..OF</code> || uint32 || IT, MPTM, XM || Fade-out
|-
| <code>...P</code> || uint32 || IT, MPTM, XM || Panning (0...256)
|-
| <code>..EV</code> || uint32 || MPTM || Number of volume envelope nodes (if ≥ 25 nodes)
|-
| <code>..EP</code> || uint32 || MPTM || Number of pan envelope nodes (if ≥ 25 nodes)
|-
| <code>.EiP</code> || uint32 || MPTM || Number of pitch envelope nodes (if ≥ 25 nodes)
|-
| <code>..BM</code> || uint16 || IT, MPTM, XM || MIDI Bank
|-
| <code>..PM</code> || uint8 || IT, MPTM, XM || MIDI Program
|-
| <code>..CM</code> || uint8 || IT, MPTM, XM || MIDI Channel
|-
| <code>.[PV</code> || uint16[] || MPTM || Volume Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EV</code> || uint8[] || MPTM || Volume Envelope Values (if ≥ 25 nodes)
|-
| <code>.[PP</code> || uint16[] || MPTM || Pan Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EP</code> || uint8[] || MPTM || Pan Envelope Values (if ≥ 25 nodes)
|-
| <code>[PiP</code> || uint16[] || MPTM || Pitch Envelope Ticks (if ≥ 25 nodes)
|-
| <code>[EiP</code> || uint8[] || MPTM || Pitch Envelope Values (if ≥ 25 nodes)
|-
| <code>.PiM</code> || uint8 || IT, MPTM, XM || Plugin, 0 = no plugin, 1 = first plugin, etc.
|-
| <code>..RV</code> || uint16 || IT, MPTM, XM || Ramping / Attack
|-
| <code>...R</code> || uint8 || IT, MPTM, XM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>..SC</code> || uint8 || IT, MPTM, XM || Cutoff Swing
|-
| <code>..SR</code> || uint8 || IT, MPTM, XM || Resonance Swing
|-
| <code>..MF</code> || uint8 || IT, MPTM, XM || Filter Mode
|-
| <code>HEVP</code> || uint8 || IT, MPTM, XM || Plugin Velocity Handling
|-
| <code>HOVP</code> || uint8 || IT, MPTM, XM || Plugin Volume Handling
|-
| <code>NREV</code> || uint8 || IT, MPTM, XM || Volume Envelope Release Node
|-
| <code>NREA</code> || uint8 || IT, MPTM, XM || Pan Envelope Release Node
|-
| <code>NREP</code> || uint8 || IT, MPTM, XM || Pitch Envelope Release Node
|-
| <code>DWPM</code> || uint8 || IT, MPTM || Pitch Wheel Depth
|-
| <code>LTTP</code> || uint16 || IT, MPTM, XM || Integer part of Pitch / Tempo Lock
|-
| <code>PTTF</code> || uint16 || MPTM || Fractional part of Pitch / Tempo Lock (0...9999)
|}

=== Legacy Extension ===

But wait, there is more! Some really old OpenMPT versions (1.17 RC1 and older, but not 1.17 RC2) do not use the instrument extensions described above. However, they also need to store the plugin reference for each instrument, which is done in another modular block following each instrument header (and possibly the <code>MPTX</code> / <code>XTPM</code> extension of that instrument header).
If this legacy extension is present, the instrument header is followed by the magic bytes <code>MSNI</code> and an uint32 containing the modular data size.

Currently there is only one chunk in this modular data block. Its FOURCC is <code>GULP</code>, has no size information and contains an uint8 for the plugin index (0 = no plugin, 1 = first plugin, etc.).

== OpenMPT Song Extensions ==

Song extensions start with the <code>STPM</code> magic bytes, but there is no size indication of the total size of this block. In an IT / XM file, these extensions are the last chunks in the file, so you can continue reading until you are out of data. In the case of MPTM files, some further MPTM-specific data follows. This data starts with the bytes "228" followed by ASCII charater 4 (not the digit), so you can keep reading the song extensions until you read this FOURCC.

=== Chunk Header Layout ===

Offset Type Content
0 char[4] Magic bytes (FOURCC)
4 uint16 Size of this chunk, excluding the header

=== Chunk Contents ===

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..TD</code> || uint32 || IT, MPTM, XM || Integer part of the default tempo (required if it is larger than 255 in IT / MPTM, but also found in legacy XM files)
|-
| <code>DTFR</code> || uint32 || MPTM || Fractional part of the default tempo (0...9999)
|-
| <code>.BPR</code> || uint32 || IT, MPTM, XM || Rows Per Beat
|-
| <code>.MPR</code> || uint32 || IT, MPTM, XM || Rows Per Measure
|-
| <code>...C</code> || uint16 || IT, MPTM || Number of channels
|-
| <code>SnhC</code> || - || IT, MPTM || If there are more than 64 channels in the IT / MTPM format, this chunk contains the default panning, volume and flags for channels 65+. They are encoded the same way as in the IT header, except that volume and panning are stored in an interleaved way (i.e. volume for channel 65, pan for channel 65, volume for channel 66, ...)
|-
| <code>..MT</code> || uint32 || IT, MPTM, XM || Tempo Mode <ul> <li>0: classic</li> <li>1: alternative</li> <li>2: modern</li> </ul>
|-
| <code>.MMP</code> || uint32 || IT, MPTM, XM || Mix Levels <ul> <li>0: Original</li> <li>1: 1.17 RC1</li> <li>2: 1.17 RC2</li> <li>3: 1.17 RC3</li> <li>4: Compatible</li> <li>5: Compatible (FT2 Pan Law)</li> </ul>
|-
| <code>.VWC</code> || uint32 || IT, MPTM, XM || OpenMPT "Created With" version (e.g. OpenMPT 1.23.45.67 = 0x01234567)
|-
| <code>VWSL</code> || uint32 || IT, MPTM, XM || OpenMPT "Last Saved With" version
|-
| <code>.APS</code> || uint32 || IT, MPTM, XM || Sample Pre-Amp
|-
| <code>VTSV</code> || uint32 || IT, MPTM, XM || VSTi Pre-Amp
|-
| <code>.VGD</code> || uint32 || XM || Global Volume (0...256)
|-
| <code>..PR</code> || uint16 || IT, MPTM || Restart Position
|-
| <code>RSMP</code> || uint32 || MPTM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>CUES</code> || - || MPTM || Sample cue points for a single sample (only MPTM format). The first uint16 in the chunk indicates for which sample slot the cue points are meant. The rest of the chunk contains all cue points as uint32s. If this chunk is missing for a particular sample slot, OpenMPT assumes the default cue points for this slot. The i-th cue point can be computed as i × 2048.
|-
| <code>SWNG</code> || - || MPTM || Contains tempo swing factors (only MPTM format). The first uint16 in the chunk indicates the number of swing rows. The rest of the chunk contains all swing factors as uint32s. A factor of 16777216 (224) is considered to be unity, i.e. does not modify the row duration. After loading, the number of swing factors should be resized to the actual number of rows per beat (in case of malformed file) and re-normalized.
|-
| <code>.FSM</code> || - || IT, MPTM, XM || A bit field of generic compatibility flags. For modules made with OpenMPT 1.25 and older, the most important one is 0x01 (first bit set), which is IT-/XM-compatible playback mode. All other flags indicate which [[Manual: Compatible Playback#Playback Compatibility Settings|compatibility settings]] are toggled.
|-
| <code>AUTH</code> || uint8[] || IT, MPTM, XM || Song artist, as UTF-8 string
|-
| <code>AMIM</code> || - || IT, MPTM, XM || MIDI Mapping settings
|-
| <code>CCOL</code> || rgbx[] || IT, MPTM, XM || Channel colors. The chunk size divided by 4 indicates the number of channels present. Format is [R, G, B, 0] for channels that have a color assigned, or [x, x, x, non-zero] for a channel with no color.
|}

== MPTM Extensions ==

=== Detecting an MPTM file ===

There are two types of hacked IT files: In early versions of the MPTM format (used in OpenMPT 1.17.02.4x), the <code>IMPM</code> magic bytes are replaced by <code>tpm.</code>, so they are not backwards compatible. Newer MPTM files use the original magic, but use a <code>cwtv</code> value between 0889h and 0FFFh (inclusive) in the header.

In both cases, the last four bytes of the file point to the start of the MPTM extensions. If the magic bytes "228" can be found at this start position, it is a valid MPTM file.

=== 228 Extensions ===

228 Extensions have been used since OpenMPT 1.17.02.48 r192 for features that are only available in the MPTM format,
such as Custom Tunings, Multiple Sequences, and Parameter Control notes.

They are documented [[Development:_228_Extensions|here]].

=== External Samples ===

MPTM files can reference external samples. If the <code>cvt</code> value in the sample header is 80h, then the sample is external. In this case, the sample pointer does not point to actual sample data but to a filename:

Offset Type Content
0 VarInt Length of the filename
? char[] Filename as UTF-8 string (not null-terminated)

Note that only the sample waveform should be loaded, but not its metadata: Frequency, loop points, volume, panning, auto-vibrato etc. should be read from the IT file. If the sample length according to the IT header is shorter than the actual sample, the sample data should be trimmed, too.

External samples are used exactly the same way in ITI files.

=== OPL Instruments ===

MPTM files can make use of OPL instruments, just like S3M files. Unlike in S3M files, patch data is not stuffed into the sample header but stored as regular sample data. To tell OPL patches apart from regular samples, the <code>cvt</code> value in the sample header is set to 40h. Note that the check for this flag should be an equal comparison (<code>cvt == 40h</code>), not a bitwise AND, due to ModPlug's legacy ADPCM sample <code>cvt</code> type (FFh). Any combination with other <code>cvt</code> flags is also considered to be illegal.

OPL2 patches are stored in the same order as in S3M files, i.e. interleaved modulator and carrier bytes, with the last (12th) byte being unused and set to 0.

=== Order list (old) ===

If the <code>cwtv</code> is between 088Bh and 088Dh (inclusive), the order list at the start of the file is replaced by the following struct:

Offset Type Content
0 uint16 Version of the order list. Only version 0 is defined. Reject any other values.
2 uint32 Number of items in the order list
6 uint32[] The order list, as a series of uint32 values. The number of values is determined by the previous field.

=== Custom Tunings (old) ===

This section is for OpenMPT versions before 1.17.02.48 r192. For newer versions, check [[Development:_228_Extensions|228 Extensions]].

Before OpenMPT 1.17.02.48 r192, the only feature that was only available in the MPTM format was Custom Tunings.
MPTM files that were made before r192 have a <code>cwtv</code> value between 0x0888 and 0x088C (inclusive).

These MPTM files contain a "Tuning Collection" chunk that contains all the custom tunings that are specific to the song (called "Tune specific tunings" in OpenMPT),
which is right after the OpenMPT song extensions.
It is then followed by a "Tuning Map" that determines which tuning each instrument should use.

A Tuning Collection could also exist separately in a <code>.TC</code> file, that can be exported/imported into an MPTM file in the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In an MPTM file, the last four bytes pointed to the start of the "Tune specific tunings" Tuning Collection,
similar to how they point to the start of 228 extensions in newer (<code>cwtv</code> > 0x088C) MPTM files.

==== Tuning Collection structure ====

The structure of a Tuning Collection is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| <code>char[4]</code>
| Tuning Collection beginning signature: <code>HSCT</code> (4 bytes)
|-
| <code>int32</code>
| Tuning Collection version: Always 1 or 2. 
|-
| <code>uint8</code> or <code>uint32</code>
| Length of the Tuning Collection's name. 
Data type:
* <code>uint8</code> if the Tuning Collection version is 2.
* <code>uint32</code> if the Tuning Collection version is 1.

|-
| <code>char[]</code>
| Tuning Collection name. The current version of OpenMPT reads a maximum of 256 (0x100) characters. 
If the collection is in a TC file, its name is the same as what it was in OpenMPT when the TC file was exported. 
But in MPTM files, only the tune-specific tuning collection is stored, and its name is always <code>Tune specific tunings</code>.
|-
| <code>int16</code>
| Tuning Collection edit mask. 
A set of 16 bits that was used to specify which settings of the tunings can be changed, but is no longer used in newer versions of OpenMPT.

|-
| <code>uint32</code>
| Number of tunings in the collection. The current version of OpenMPT does not load custom tunings at all if the number of tunings in an MPTM file is greater than 50.
|-
| (custom structure)
| The tunings in this collection, stored right after each other. The structure of a tuning is described below.
|-
| <code>char[4]</code>
| Tuning Collection end signature: <code>FSCT</code> (4 bytes)
|}

==== Tuning structure ====

The structure of a Custom Tuning is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| <code>char[8]</code>
| Tuning beginning signature: <code>CTRTI_B.</code> (8 bytes)
|-
| <code>int16</code>
| Tuning version: Always 2 or 3. 
|-
| <code>char[8]</code>
| Tuning SFS chunk beginning signature: <code>CT<sfs>B</code> (8 bytes)
|-
| <code>int16</code>
| Tuning SFS chunk version: Always 3 or 4. 
|-
| <code>uint8</code> or <code>uint32</code>
| Length of the tuning's name. 
Data type:
* <code>uint8</code> if the SFS chunk version is 4.
* <code>uint32</code> if the SFS chunk version is 3.

|-
| <code>char[]</code>
| Tuning name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|-
| <code>int16</code>
| Tuning edit mask. 
A set of 16 bits that was used to specify which settings of the tuning can be changed, but is no longer used in newer versions of OpenMPT.

|-
| <code>int16</code>
| Tuning type.
* 0: Generic
* 1: Group-geometric (originally called "Ratio-periodic")
* 3: Geometric (originally called "TET")
Newer versions of OpenMPT that use the new tuning format will convert old Geometric tunings to Group-geometric for compatibility reasons.
|-
| <code>uint16</code> or <code>uint32</code>
| Size of the tuning's note name map. Maximum value is 65535 (0xFFFF), even if the datatype is <code>uint32</code>. 
Data type:
* <code>uint16</code> if the SFS chunk version is 4.
* <code>uint32</code> if the SFS chunk version is 3.

|-
| (custom structure)
| The tuning's note name map. Contains the names of notes that have custom names. The structure is described in further below.
|-
| <code>char[8]</code>
| Tuning SFS chunk end signature: <code>CT<sfs>E</code> (8 bytes)
|-
| <code>uint16</code> or <code>uint32</code>
| Size of the tuning's ratio table. Maximum value is 65535 (0xFFFF), even if the datatype is <code>uint32</code>. This value is usually set to 256 (or 0 if the ratio table is unneeded). 
Data type:
* <code>uint16</code> if the tuning version is 3.
* <code>uint32</code> if the tuning version is 2.

|-
| <code>float32[]</code>
| The tuning's ratio table. Contains the frequency ratios for every note. If all ratios are 1, the ratio table is unneeded, so its size would be 0. 
Unlike the newer tuning format that uses 228 extensions, this table contains ratios for every note in every group, regardless of the tuning type.
|-
| <code>uint16</code> or <code>uint32</code>
| Finetune steps. Maximum value is 65535 (0xFFFF), even if the datatype is <code>uint32</code>. 
Data type:
* <code>uint16</code> if the tuning version is 3.
* <code>uint32</code> if the tuning version is 2.

|-
| <code>float32[]</code>
| An array of finetune step ratios, containing the same number of values as the finetune steps value. 
The first value is 1, and each value is r(1/finetunesteps) times the previous value, 
where r is the ratio of note 1 (the note after the middle note) to note 0 (the middle note). 
This table no longer exists in the newer tuning format that uses 228 extensions.
|-
| <code>int16</code>
| First note index in the ratio table. Usually set to -128. 
The current version of OpenMPT rejects values smaller than -200 and greater than 200.
|-
| <code>int16</code>
| Group size. 
For generic tunings, this value is 0.
|-
| <code>float32</code>
| Group ratio. 
For generic tunings, this value is 0.
|-
| <code>char[8]</code>
| Tuning end signature: <code>CTRTI_E.</code> (8 bytes)
|}

Many of the values that are stored for each tuning are redundant.
For example, the ratio table contains ratios for every note, regardless of the tuning type, even though it makes sense to
only have ratios for a single group in group-geometric tunings, and to not be stored at all in geometric tunings.
But they still have to be stored for these old versions of OpenMPT to work correctly.
However, these redundancies no longer exist in the newer tuning format that uses 228 extensions.

==== Tuning note name map structure ====

The structure of a single entry in the note name map is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| <code>int16</code>
| Note number.
|-
| <code>uint8</code> or <code>uint32</code>
| Length of the note name. 
Data type:
* <code>uint8</code> if the tuning's SFS chunk version is 4.
* <code>uint32</code> if the tuning's SFS chunk version is 3.

|-
| <code>char[]</code>
| Note name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|}

This structure is stored for every note that has a custom name.

For geometric and group-geometric tunings, only the notes of a single group, where the note numbers are between 0 and groupsize-1 (inclusive).
The note names for that single group are then applied to every group (group/octave numbers are not a part of the note name).

==== Tuning Map structure ====

The structure of a tuning map is identical to that of the new 228 tuning format , but with a difference if the <code>cwtv</code> value is 0x088B or older:

The number of tunings in the map and the length of the tuning names in the map are both stored as <code>uint32</code> instead of <code>uint16</code> and <code>uint8</code> respectively.

== RIFF WAVE ==

OpenMPT uses its own <code>xtra</code> chunk in RIFF WAVE files to store some sample properties which could otherwise not be represented in the format.

Its layout is as follows:

Offset Type Content
0 uint32 Sample flags (0x20: Default panning is enabled)
4 uint16 Default panning (0...256)
6 uint16 Default volume (0...256)
8 uint16 Global volume (0...64)
10 uint16 Reserved (must be 0)
12 uint8 Auto-vibrato type
13 uint8 Auto-vibrato sweep
14 uint8 Auto-vibrato depth
15 uint8 Auto-vibrato rate

Optionally, when copying a sample to the system clipboard, the sample name (32 characters, null-padded) and filename (22 characters, null-padded) follow.

== FLAC ==

Since the FLAC format has no native and standardized way to store loop information, OpenMPT follows Renoise′s way of storing loop information: FLAC supports application-defined metadata, so OpenMPT writes a metadata block with application ID <code>riff</code>. The block contains a <code>smpl</code> chunk (as defined in the [http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/RIFFNEW.pdf RIFF specification]). Similarly, extended sample properties are stored in another <code>riff</code> application block contaning the OpenMPT-specific <code>[[#RIFF WAVE|xtra]]</code> chunk, and sample cue points are stored in a <code>cue </code> chunk.

OpenMPT also reads and writes the following non-standard vorbis comments:
* '''SAMPLERATE''': Contains the sample rate (as text) in case it would exceed the maximum sample rate supported by the FLAC format, 655350 Hz.
* '''LOOPSTART''': The start of the sample loop in frames. This tag is only read, not written.
* '''LOOPLENGTH''': The length of the sample loop in frames. This tag is only read, not written.

[[Category:Development|OpenMPT Format Extensions]]

Development: OpenMPT Format Extensions

2022-02-26T10:05:52Z

CS127: /* MPTM Extensions */ added a link to the 228 extensions page

ModPlug Tracker and OpenMPT have extended the IT and XM formats in various ways. In general, these hacks are frowned upon, but here is some documentation on those hacks in case you want to support them in your own player. I am really sorry about all this mess, but all of this has grown historically way before I joined OpenMPT development.

Presence of these format extensions in a file does not necessarily imply that it was created with ModPlug Tracker or OpenMPT. Some of the extensions are also used e.g. by BeRoTracker.

Any numeric values are stored in little-endian format, unless noted otherwise.

Data types used in this document:
* uint8, uint16, uint32: Unsigned integers with the given bit width.
* int8, int16, int32: Signed integers with the given bit width.
* char: A single character (i.e. a byte)
* float32: Single precision IEEE float
* VarInt: A MIDI-like variable-length unsigned integer (big-endian value where the highest bit of each byte indicates if another byte follows, and the lower 7 bits containing the actual number).
* Square brackets [] denote an array of values:
** [] is a variable-length array (length is deduced from some other attribute)
** [42] denotes an array with 42 entries.

== ModPlug Song Extensions ==

The following extensions exist since the (closed-source) ModPlug Tracker days. These extensions are found in [https://en.wikipedia.org/wiki/Interchange_File_Format IFF]-like chunks, but without any padding bytes. The chunks are placed right after the header data in the IT format (i.e. after the edit history / MIDI macro block). In the XM format these chunks are placed right at the end of the file (i.e. after the sample data). At the time of writing, these chunks are always written out in the order described here, but if possible you should probably try to read them without expecting a certain order. All chunks are optional.

=== Chunk Header Layout ===

Offset Type Content
0 char[4] Magic bytes (FOURCC)
4 uint32 Size of this chunk, excluding the header

=== Chunks ===

==== text (XM only) ====

Contains the song message (CR line endings), its length is determined by the chunk size.

==== MIDI (XM only) ====

Contains the MIDI macro configuration, in the same format as in the IT format.

==== PNAM ====

Contains the pattern names. Each pattern name is 32 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The pattern names are stored continuously, i.e. there are (chunk size / 32) pattern names in the chunk, for pattern 0, pattern 1, ... pattern (chunk size / 32 - 1).

==== CNAM ====

Contains the channel names. Each channel name is 20 bytes long and not necessarily null-terminated. The encoding is unspecified (Windows code page). The channel names are stored continuously, i.e. there are (chunk size / 20) channel names in the chunk, for channel 1, channel 2, ... channel (chunk size / 20).

==== CHFX ====

Contains the plugin assignment for each channel. For every channel, there is a 32-bit integer plugin index. 0 means no plugin, 1 is the first plugin, etc...

==== FX00, ... FX99, F100, ... F255 ====

Contains plugin information for each plugin slot. <code>FX00</code> contains the information for the first plugin slot, <code>FX99</code> for the 100th, <code>F100</code> for the 101st, etc...

Offset Type Content
0 char[4] Plugin type ("PtsV" for VST, "OMXD" for DMO plugins)
4 char[4] Plugin unique ID
8 uint8 Routing Flags
9 uint8 Mix Mode
10 uint8 Gain Factor * 10 (9 = 90%, 10 = 100%, 11 = 110%, etc.). A value of 0 is equal to 10 (i.e. 100%).
11 uint8 Reserved
12 uint32 Output Routing (0 = send to master 0x80 + x = send to plugin x)
16 char[16] Reserved
32 char[32] User-chosen plugin name (Windows code page)
64 char[64] Library name (Original DLL name / DMO identifier - UTF-8 starting from OpenMPT 1.22.07.01, Windows code page in older versions)
128 uint32 Length of plugin-specific data (parameters or opaque chunk)
132 char[] Plugin-specific data

'''Routing Flags:'''
* 0x01: Apply to master mix
* 0x02: Bypass effect
* 0x04: Wet Mix (dry added)
* 0x08: Expand Mix [0%,100%] → [-200%,200%]
* 0x10: Plugin will automatically suspend on silence

'''Mix Modes:'''
* 0: normal processing
* 1: MIX += DRY - WET * wetRatio
* 2: MIX += WET - DRY * dryRatio
* 3: MIX -= WET - DRY * wetRatio
* 4: MIX -= middle - WET * wetRatio + middle - DRY
* 5: MIX_L += wetRatio * (WET_L - DRY_L) + dryRatio * (DRY_R - WET_R) MIX_R += dryRatio * (WET_L - DRY_L) + wetRatio * (DRY_R - WET_R)

The first four bytes of the plugin-specific data determine the type of data. If they are all 0, then the plugin parameters follow as an array of float32 values. Otherwise, plugin type specific data follows which should be treated as an opaque chunk. For example, for VST plugins that support the effGetChunk / effSetChunk chunk, the first four bytes will be "fEvN", followed by the data to be sent to the plugin.

After the plugin information described above, more information may follow in OpenMPT modules. This information is again stored in chunks. However, there are two legacy chunks which do not have any size stored alongside the chunk identifier:

{| class="wikitable"
|-
! FOURCC !! Data Type !! Description
|-
| <code>DWRT</code> || float32 || Dry/Wet Ratio of the plugin. This chunk does not denote its size!
|-
| <code>PROG</code> || uint32 || Default plugin program (preset) to restore. This chunk does not denote its size!
|}

Any chunks that will be added in the future will have proper IFF-like chunks with a 32-bit size field.

== ModPlug Instrument Extensions (IT only) ==

To be able to address more than 256 samples in the IT format, ModPlug Tracker has an extension to store the high byte of sample indices for the instrument sample map.

By default, the last four bytes of an IT instrument (right after the pitch envelope) are unused. If they read <code>MPTX</code> or <code>XTPM</code>, 120 extra bytes follow, one for each note in the sample map. These bytes are the high byte of the sample index, i.e. they need to be multiplied by 256 and then added to the already read sample index.

== OpenMPT Extensions (General Information) ==

In the XM format, OpenMPT instrument extensions may follow the ModPlug song extensions and may in return be followed by OpenMPT song extensions.

In the IT format, OpenMPT instrument extensions may follow the sample block and may in return be followed by OpenMPT song extensions.
This is very ugly, because there might not be any samples, in which case the last thing before the extension block would be the last pattern. If there are no patterns, the last thing before the extension block would be a sample header (at least one sample header will be present even if there is no sample data – but you may even want to cover the case where there are no sample headers, for being compatible with possible future changes). So you will somehow have to keep track of the highest offset you have read into the file. If the last sample is IT-compressed, things become even more complicated: There is no way to know the compressed size of a compressed sample, so in case you want to skip sample loading, and the last sample happens to be compressed, you can do the following:
Since we know that the extended instrument and song properties start right after the last sample, and since IT-compressed samples consist of chunks with a prepended 16-bit length field, you can simply read that 16-bit number, skip this amount of bytes, then check if you can read OpenMPT's <code>XTPM</code> or <code>STPM</code> magic bytes, and if not, read the next 16-bit length, skip the bytes, etc...

In pseudo code, finding the OpenMPT extensions in an IT / MPTM file could look somewhat like this:

''offset'' = 0
''lastSampleCompressed'' = false

// In case there are no patterns and no sample data (just empty sample slots):
if(number of samples > 0):
''offset'' = last sample header pointer + sizeof(ITSampleHeader)

for all samples:
if sample is not compressed or if samples are decoded:
''lastSampleCompressed'' = false
''offset'' = max(''offset'', pointer to sample data + sample size)
else if sample is compressed and samples are not decoded:
''lastSampleCompressed'' = true
''offset'' = max(''offset'', pointer to sample data)

// In case there is no sample data:
for all patterns:
''offset'' = max(''offset'', end of pattern data)

if ''lastSampleCompressed'':
while not eof:
if next four bytes are XTPM or STPM:
''chunkID'' = next four bytes
if ''chunkID'' only contains ASCII characters (all bytes are in 32…127)
''offset'' = current position - 4; break
else
skip back 8 bytes
read uint16 value and skip as many bytes

Try reading XTPM and STPM extensions at ''offset''

The provided data types are just for orientation, i.e. the minimum recommended field size for storing the values in memory. You must expect fields to have a different size, since sometimes they do so for historic reasons. Defensive programming is your friend. Most of the FOURCCs also just make sense when read backwards, again for historic reasons. Note that some of these extensions duplicate existing functionality of the IT/XM format. In this case, the extensions take precedence over the value previous found in the file.

== OpenMPT Instrument Extensions ==

Instrument extensions start with the <code>XTPM</code> magic bytes, but there is no size indication of the total size of this block. So you have to read the following chunks and as soon as you read the <code>STPM</code> magic bytes for a chunk, you know you have read to far and can continue with reading OpenMPT Song Extensions instead.

Instrument extensions are stored in a peculiar way: There is one chunk per property, and it contains the values for all instruments at once. The layout is as follows:

=== Chunk Header Layout ===

Offset Type Content
0 char[4] Magic bytes (FOURCC)
4 uint16 Size of this chunk's entry '''for one instrument''' (i.e. total chunk content size is this field × number of instruments)

=== Chunk Contents ===

The following instrument properties exist. Some of them are redundant depending on the file type and thus not present in all files. If they are redundant, they overwrite the values that were obtained from the format-specific structures.

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..OF</code> || uint32 || IT, MPTM, XM || Fade-out
|-
| <code>...P</code> || uint32 || IT, MPTM, XM || Panning (0...256)
|-
| <code>..EV</code> || uint32 || MPTM || Number of volume envelope nodes (if ≥ 25 nodes)
|-
| <code>..EP</code> || uint32 || MPTM || Number of pan envelope nodes (if ≥ 25 nodes)
|-
| <code>.EiP</code> || uint32 || MPTM || Number of pitch envelope nodes (if ≥ 25 nodes)
|-
| <code>..BM</code> || uint16 || IT, MPTM, XM || MIDI Bank
|-
| <code>..PM</code> || uint8 || IT, MPTM, XM || MIDI Program
|-
| <code>..CM</code> || uint8 || IT, MPTM, XM || MIDI Channel
|-
| <code>.[PV</code> || uint16[] || MPTM || Volume Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EV</code> || uint8[] || MPTM || Volume Envelope Values (if ≥ 25 nodes)
|-
| <code>.[PP</code> || uint16[] || MPTM || Pan Envelope Ticks (if ≥ 25 nodes)
|-
| <code>.[EP</code> || uint8[] || MPTM || Pan Envelope Values (if ≥ 25 nodes)
|-
| <code>[PiP</code> || uint16[] || MPTM || Pitch Envelope Ticks (if ≥ 25 nodes)
|-
| <code>[EiP</code> || uint8[] || MPTM || Pitch Envelope Values (if ≥ 25 nodes)
|-
| <code>.PiM</code> || uint8 || IT, MPTM, XM || Plugin, 0 = no plugin, 1 = first plugin, etc.
|-
| <code>..RV</code> || uint16 || IT, MPTM, XM || Ramping / Attack
|-
| <code>...R</code> || uint8 || IT, MPTM, XM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>..SC</code> || uint8 || IT, MPTM, XM || Cutoff Swing
|-
| <code>..SR</code> || uint8 || IT, MPTM, XM || Resonance Swing
|-
| <code>..MF</code> || uint8 || IT, MPTM, XM || Filter Mode
|-
| <code>HEVP</code> || uint8 || IT, MPTM, XM || Plugin Velocity Handling
|-
| <code>HOVP</code> || uint8 || IT, MPTM, XM || Plugin Volume Handling
|-
| <code>NREV</code> || uint8 || IT, MPTM, XM || Volume Envelope Release Node
|-
| <code>NREA</code> || uint8 || IT, MPTM, XM || Pan Envelope Release Node
|-
| <code>NREP</code> || uint8 || IT, MPTM, XM || Pitch Envelope Release Node
|-
| <code>DWPM</code> || uint8 || IT, MPTM || Pitch Wheel Depth
|-
| <code>LTTP</code> || uint16 || IT, MPTM, XM || Integer part of Pitch / Tempo Lock
|-
| <code>PTTF</code> || uint16 || MPTM || Fractional part of Pitch / Tempo Lock (0...9999)
|}

=== Legacy Extension ===

But wait, there is more! Some really old OpenMPT versions (1.17 RC1 and older, but not 1.17 RC2) do not use the instrument extensions described above. However, they also need to store the plugin reference for each instrument, which is done in another modular block following each instrument header (and possibly the <code>MPTX</code> / <code>XTPM</code> extension of that instrument header).
If this legacy extension is present, the instrument header is followed by the magic bytes <code>MSNI</code> and an uint32 containing the modular data size.

Currently there is only one chunk in this modular data block. Its FOURCC is <code>GULP</code>, has no size information and contains an uint8 for the plugin index (0 = no plugin, 1 = first plugin, etc.).

== OpenMPT Song Extensions ==

Song extensions start with the <code>STPM</code> magic bytes, but there is no size indication of the total size of this block. In an IT / XM file, these extensions are the last chunks in the file, so you can continue reading until you are out of data. In the case of MPTM files, some further MPTM-specific data follows. This data starts with the bytes "228" followed by ASCII charater 4 (not the digit), so you can keep reading the song extensions until you read this FOURCC.

=== Chunk Header Layout ===

Offset Type Content
0 char[4] Magic bytes (FOURCC)
4 uint16 Size of this chunk, excluding the header

=== Chunk Contents ===

{| class="wikitable"
|-
! FOURCC !! Data Type !! Formats !! Description
|-
| <code>..TD</code> || uint32 || IT, MPTM, XM || Integer part of the default tempo (required if it is larger than 255 in IT / MPTM, but also found in legacy XM files)
|-
| <code>DTFR</code> || uint32 || MPTM || Fractional part of the default tempo (0...9999)
|-
| <code>.BPR</code> || uint32 || IT, MPTM, XM || Rows Per Beat
|-
| <code>.MPR</code> || uint32 || IT, MPTM, XM || Rows Per Measure
|-
| <code>...C</code> || uint16 || IT, MPTM || Number of channels
|-
| <code>SnhC</code> || - || IT, MPTM || If there are more than 64 channels in the IT / MTPM format, this chunk contains the default panning, volume and flags for channels 65+. They are encoded the same way as in the IT header, except that volume and panning are stored in an interleaved way (i.e. volume for channel 65, pan for channel 65, volume for channel 66, ...)
|-
| <code>..MT</code> || uint32 || IT, MPTM, XM || Tempo Mode <ul> <li>0: classic</li> <li>1: alternative</li> <li>2: modern</li> </ul>
|-
| <code>.MMP</code> || uint32 || IT, MPTM, XM || Mix Levels <ul> <li>0: Original</li> <li>1: 1.17 RC1</li> <li>2: 1.17 RC2</li> <li>3: 1.17 RC3</li> <li>4: Compatible</li> <li>5: Compatible (FT2 Pan Law)</li> </ul>
|-
| <code>.VWC</code> || uint32 || IT, MPTM, XM || OpenMPT "Created With" version (e.g. OpenMPT 1.23.45.67 = 0x01234567)
|-
| <code>VWSL</code> || uint32 || IT, MPTM, XM || OpenMPT "Last Saved With" version
|-
| <code>.APS</code> || uint32 || IT, MPTM, XM || Sample Pre-Amp
|-
| <code>VTSV</code> || uint32 || IT, MPTM, XM || VSTi Pre-Amp
|-
| <code>.VGD</code> || uint32 || XM || Global Volume (0...256)
|-
| <code>..PR</code> || uint16 || IT, MPTM || Restart Position
|-
| <code>RSMP</code> || uint32 || MPTM || Resampling Mode <ul> <li>0: No Interpolation (1 tap)</li> <li>1: Linear (2 taps)</li> <li>2: Cubic Spline (4 taps)</li> <li>3: Sinc + Lowpass / Polyphase (8 taps)</li> <li>4: Sinc / XMMS-ModPlug (8 taps)</li> <li>5: Default</li> </ul>
|-
| <code>CUES</code> || - || MPTM || Sample cue points for a single sample (only MPTM format). The first uint16 in the chunk indicates for which sample slot the cue points are meant. The rest of the chunk contains all cue points as uint32s. If this chunk is missing for a particular sample slot, OpenMPT assumes the default cue points for this slot. The i-th cue point can be computed as i × 2048.
|-
| <code>SWNG</code> || - || MPTM || Contains tempo swing factors (only MPTM format). The first uint16 in the chunk indicates the number of swing rows. The rest of the chunk contains all swing factors as uint32s. A factor of 16777216 (224) is considered to be unity, i.e. does not modify the row duration. After loading, the number of swing factors should be resized to the actual number of rows per beat (in case of malformed file) and re-normalized.
|-
| <code>.FSM</code> || - || IT, MPTM, XM || A bit field of generic compatibility flags. For modules made with OpenMPT 1.25 and older, the most important one is 0x01 (first bit set), which is IT-/XM-compatible playback mode. All other flags indicate which [[Manual: Compatible Playback#Playback Compatibility Settings|compatibility settings]] are toggled.
|-
| <code>AUTH</code> || uint8[] || IT, MPTM, XM || Song artist, as UTF-8 string
|-
| <code>AMIM</code> || - || IT, MPTM, XM || MIDI Mapping settings
|-
| <code>CCOL</code> || rgbx[] || IT, MPTM, XM || Channel colors. The chunk size divided by 4 indicates the number of channels present. Format is [R, G, B, 0] for channels that have a color assigned, or [x, x, x, non-zero] for a channel with no color.
|}

== MPTM Extensions ==

=== Detecting an MPTM file ===

There are two types of hacked IT files: In early versions of the MPTM format (used in OpenMPT 1.17.02.4x), the <code>IMPM</code> magic bytes are replaced by <code>tpm.</code>, so they are not backwards compatible. Newer MPTM files use the original magic, but use a <code>cwtv</code> value between 0889h and 0FFFh (inclusive) in the header.

In both cases, the last four bytes of the file point to the start of the MPTM extensions. If the magic bytes "228" can be found at this start position, it is a valid MPTM file.

=== 228 Extensions ===

228 Extensions have been used since OpenMPT 1.17.02.48 r192 for features that are only available in the MPTM format,
such as Custom Tunings, Multiple Sequences, and Parameter Control notes.

They documented [[Development:_228_Extensions|here]].

=== External Samples ===

MPTM files can reference external samples. If the <code>cvt</code> value in the sample header is 80h, then the sample is external. In this case, the sample pointer does not point to actual sample data but to a filename:

Offset Type Content
0 VarInt Length of the filename
? char[] Filename as UTF-8 string (not null-terminated)

Note that only the sample waveform should be loaded, but not its metadata: Frequency, loop points, volume, panning, auto-vibrato etc. should be read from the IT file. If the sample length according to the IT header is shorter than the actual sample, the sample data should be trimmed, too.

External samples are used exactly the same way in ITI files.

=== OPL Instruments ===

MPTM files can make use of OPL instruments, just like S3M files. Unlike in S3M files, patch data is not stuffed into the sample header but stored as regular sample data. To tell OPL patches apart from regular samples, the <code>cvt</code> value in the sample header is set to 40h. Note that the check for this flag should be an equal comparison (<code>cvt == 40h</code>), not a bitwise AND, due to ModPlug's legacy ADPCM sample <code>cvt</code> type (FFh). Any combination with other <code>cvt</code> flags is also considered to be illegal.

OPL2 patches are stored in the same order as in S3M files, i.e. interleaved modulator and carrier bytes, with the last (12th) byte being unused and set to 0.

=== Order list (old) ===

If the <code>cwtv</code> is between 088Bh and 088Dh (inclusive), the order list at the start of the file is replaced by the following struct:

Offset Type Content
0 uint16 Version of the order list. Only version 0 is defined. Reject any other values.
2 uint32 Number of items in the order list
6 uint32[] The order list, as a series of uint32 values. The number of values is determined by the previous field.

=== Custom Tunings (old) ===

This section is for OpenMPT versions before 1.17.02.48 r192. For newer versions, check [[Development:_228_Extensions|228 Extensions]].

Before OpenMPT 1.17.02.48 r192, the only feature that was only available in the MPTM format was Custom Tunings.
MPTM files that were made before r192 have a <code>cwtv</code> value between 0x0888 and 0x088C (inclusive).

These MPTM files contain a "Tuning Collection" chunk that contains all the custom tunings that are specific to the song (called "Tune specific tunings" in OpenMPT),
which is right after the OpenMPT song extensions.
It is then followed by a "Tuning Map" that determines which tuning each instrument should use.

A Tuning Collection could also exist separately in a <code>.TC</code> file, that can be exported/imported into an MPTM file in the [[Manual:_Tuning_Properties|Tuning Properties]] dialog.

In an MPTM file, the last four bytes pointed to the start of the "Tune specific tunings" Tuning Collection,
similar to how they point to the start of 228 extensions in newer (<code>cwtv</code> > 0x088C) MPTM files.

==== Tuning Collection structure ====

The structure of a Tuning Collection is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| <code>char[4]</code>
| Tuning Collection beginning signature: <code>HSCT</code> (4 bytes)
|-
| <code>int32</code>
| Tuning Collection version: Always 1 or 2. 
|-
| <code>uint8</code> or <code>uint32</code>
| Length of the Tuning Collection's name. 
Data type:
* <code>uint8</code> if the Tuning Collection version is 2.
* <code>uint32</code> if the Tuning Collection version is 1.

|-
| <code>char[]</code>
| Tuning Collection name. The current version of OpenMPT reads a maximum of 256 (0x100) characters. 
If the collection is in a TC file, its name is the same as what it was in OpenMPT when the TC file was exported. 
But in MPTM files, only the tune-specific tuning collection is stored, and its name is always <code>Tune specific tunings</code>.
|-
| <code>int16</code>
| Tuning Collection edit mask. 
A set of 16 bits that was used to specify which settings of the tunings can be changed, but is no longer used in newer versions of OpenMPT.

|-
| <code>uint32</code>
| Number of tunings in the collection. The current version of OpenMPT does not load custom tunings at all if the number of tunings in an MPTM file is greater than 50.
|-
| (custom structure)
| The tunings in this collection, stored right after each other. The structure of a tuning is described below.
|-
| <code>char[4]</code>
| Tuning Collection end signature: <code>FSCT</code> (4 bytes)
|}

==== Tuning structure ====

The structure of a Custom Tuning is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| <code>char[8]</code>
| Tuning beginning signature: <code>CTRTI_B.</code> (8 bytes)
|-
| <code>int16</code>
| Tuning version: Always 2 or 3. 
|-
| <code>char[8]</code>
| Tuning SFS chunk beginning signature: <code>CT<sfs>B</code> (8 bytes)
|-
| <code>int16</code>
| Tuning SFS chunk version: Always 3 or 4. 
|-
| <code>uint8</code> or <code>uint32</code>
| Length of the tuning's name. 
Data type:
* <code>uint8</code> if the SFS chunk version is 4.
* <code>uint32</code> if the SFS chunk version is 3.

|-
| <code>char[]</code>
| Tuning name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|-
| <code>int16</code>
| Tuning edit mask. 
A set of 16 bits that was used to specify which settings of the tuning can be changed, but is no longer used in newer versions of OpenMPT.

|-
| <code>int16</code>
| Tuning type.
* 0: Generic
* 1: Group-geometric (originally called "Ratio-periodic")
* 3: Geometric (originally called "TET")
Newer versions of OpenMPT that use the new tuning format will convert old Geometric tunings to Group-geometric for compatibility reasons.
|-
| <code>uint16</code> or <code>uint32</code>
| Size of the tuning's note name map. Maximum value is 65535 (0xFFFF), even if the datatype is <code>uint32</code>. 
Data type:
* <code>uint16</code> if the SFS chunk version is 4.
* <code>uint32</code> if the SFS chunk version is 3.

|-
| (custom structure)
| The tuning's note name map. Contains the names of notes that have custom names. The structure is described in further below.
|-
| <code>char[8]</code>
| Tuning SFS chunk end signature: <code>CT<sfs>E</code> (8 bytes)
|-
| <code>uint16</code> or <code>uint32</code>
| Size of the tuning's ratio table. Maximum value is 65535 (0xFFFF), even if the datatype is <code>uint32</code>. This value is usually set to 256 (or 0 if the ratio table is unneeded). 
Data type:
* <code>uint16</code> if the tuning version is 3.
* <code>uint32</code> if the tuning version is 2.

|-
| <code>float32[]</code>
| The tuning's ratio table. Contains the frequency ratios for every note. If all ratios are 1, the ratio table is unneeded, so its size would be 0. 
Unlike the newer tuning format that uses 228 extensions, this table contains ratios for every note in every group, regardless of the tuning type.
|-
| <code>uint16</code> or <code>uint32</code>
| Finetune steps. Maximum value is 65535 (0xFFFF), even if the datatype is <code>uint32</code>. 
Data type:
* <code>uint16</code> if the tuning version is 3.
* <code>uint32</code> if the tuning version is 2.

|-
| <code>float32[]</code>
| An array of finetune step ratios, containing the same number of values as the finetune steps value. 
The first value is 1, and each value is r(1/finetunesteps) times the previous value, 
where r is the ratio of note 1 (the note after the middle note) to note 0 (the middle note). 
This table no longer exists in the newer tuning format that uses 228 extensions.
|-
| <code>int16</code>
| First note index in the ratio table. Usually set to -128. 
The current version of OpenMPT rejects values smaller than -200 and greater than 200.
|-
| <code>int16</code>
| Group size. 
For generic tunings, this value is 0.
|-
| <code>float32</code>
| Group ratio. 
For generic tunings, this value is 0.
|-
| <code>char[8]</code>
| Tuning end signature: <code>CTRTI_E.</code> (8 bytes)
|}

Many of the values that are stored for each tuning are redundant.
For example, the ratio table contains ratios for every note, regardless of the tuning type, even though it makes sense to
only have ratios for a single group in group-geometric tunings, and to not be stored at all in geometric tunings.
But they still have to be stored for these old versions of OpenMPT to work correctly.
However, these redundancies no longer exist in the newer tuning format that uses 228 extensions.

==== Tuning note name map structure ====

The structure of a single entry in the note name map is as follows:

{| class="wikitable"
|-
! Data type
! Content/Description
|-
| <code>int16</code>
| Note number.
|-
| <code>uint8</code> or <code>uint32</code>
| Length of the note name. 
Data type:
* <code>uint8</code> if the tuning's SFS chunk version is 4.
* <code>uint32</code> if the tuning's SFS chunk version is 3.

|-
| <code>char[]</code>
| Note name. The current version of OpenMPT reads a maximum of 65535 (0xFFFF) characters.
|}

This structure is stored for every note that has a custom name.

For geometric and group-geometric tunings, only the notes of a single group, where the note numbers are between 0 and groupsize-1 (inclusive).
The note names for that single group are then applied to every group (group/octave numbers are not a part of the note name).

==== Tuning Map structure ====

The structure of a tuning map is identical to that of the new 228 tuning format , but with a difference if the <code>cwtv</code> value is 0x088B or older:

The number of tunings in the map and the length of the tuning names in the map are both stored as <code>uint32</code> instead of <code>uint16</code> and <code>uint8</code> respectively.

== RIFF WAVE ==

OpenMPT uses its own <code>xtra</code> chunk in RIFF WAVE files to store some sample properties which could otherwise not be represented in the format.

Its layout is as follows:

Offset Type Content
0 uint32 Sample flags (0x20: Default panning is enabled)
4 uint16 Default panning (0...256)
6 uint16 Default volume (0...256)
8 uint16 Global volume (0...64)
10 uint16 Reserved (must be 0)
12 uint8 Auto-vibrato type
13 uint8 Auto-vibrato sweep
14 uint8 Auto-vibrato depth
15 uint8 Auto-vibrato rate

Optionally, when copying a sample to the system clipboard, the sample name (32 characters, null-padded) and filename (22 characters, null-padded) follow.

== FLAC ==

Since the FLAC format has no native and standardized way to store loop information, OpenMPT follows Renoise′s way of storing loop information: FLAC supports application-defined metadata, so OpenMPT writes a metadata block with application ID <code>riff</code>. The block contains a <code>smpl</code> chunk (as defined in the [http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/RIFFNEW.pdf RIFF specification]). Similarly, extended sample properties are stored in another <code>riff</code> application block contaning the OpenMPT-specific <code>[[#RIFF WAVE|xtra]]</code> chunk, and sample cue points are stored in a <code>cue </code> chunk.

OpenMPT also reads and writes the following non-standard vorbis comments:
* '''SAMPLERATE''': Contains the sample rate (as text) in case it would exceed the maximum sample rate supported by the FLAC format, 655350 Hz.
* '''LOOPSTART''': The start of the sample loop in frames. This tag is only read, not written.
* '''LOOPLENGTH''': The length of the sample loop in frames. This tag is only read, not written.

[[Category:Development|OpenMPT Format Extensions]]