TBM File Format Specification: Major Revision 1

Introduction

This document is a formal specification of the file format for TrackerBoy module files, or *.tbm files. This document is for major revision 1 of the file format.

A Module file is a serialized form of the Module object.

The libtrackerboy library provides a reference implementation for serializing and deserialing module files with this format. See the io module for more documentation.

Note	All multi-byte fields in this specification are stored in little-endian byte order.

Changes

Major 1 introduces the following changes to the format:

The INDX block has been deprecated, and is no longer present in the payload.
SONG, INST, and WAVE blocks now each contain a single song, instrument or waveform, respectively.
The payload can contain 1-256 SONG blocks and 0-64 INST and WAVE blocks.
numberOfInstruments and numberOfWaveforms fields have been replaced by the icount and wcount fields in the header.
Added scount field to the header.
LString type uses a 2-byte length instead of 1-byte
Added a terminator that follows the payload
Added a table of error codes to the specification
Added a field, numberOfEffects, to SongFormat record in SONG blocks.
(Revision 1.1) New effect, Jxy, for setting the global volume scale.

Additionally, a specification for module piece files has been introduced. This allows for parts of a module to be stored separately, for easy reuse and sharing.

Definitions

Module: A container of songs, instruments and waveforms. Instruments and waveforms are shared between all songs. A module can store up to 256 songs, 64 instruments and 64 waveforms.
Module Piece: An individual part of the module as a song, instrument or waveform. This individual part can be stored as a separate file.
Order: Song order data, a list of OrderRows that determine each pattern in the song.
OrderRow: A track id assignment for each channel. Determines the tracks which make a pattern.
Pattern: A collection of Tracks, one for each channel.
Track: Song data for a single channel. A Track is a list of TrackRows.

File extensions

It is recommended that the following file extensions are used for files adhering to this specification:

*.tbm: TrackerBoy Module file
*.tbi: TrackerBoy Instrument file
*.tbs: TrackerBoy Song file
*.tbw: TrackerBoy Waveform file

Basic Types

Below are basic data types used throughout the format

Type name

Size (bytes)

Description

Uint8

Unsigned 8-bit integer (0-255)

BiasedUint8

Unsigned 8-bit integer, biased form (1-256)

Char

8-bit Character type

Bool

Boolean as an uint8 (0 for false, nonzero for true)

Uint16

Unsigned 16-bit integer, in little endian (0-65536)

Uint32

Unsigned 32-bit integer, in little endian

LString

2 + length

Length-prefixed UTF-8 string, string data prefixed by a Uint16 length

Error Codes

Below is a list of error codes possible when deserialing/serializing a module file. After processing a file, one of these error codes, or Format Result (fr), is given.

Identifier

Code

Description

frNone

No error, format is acceptable

frInvalidSignature

File has an invalid signature

frInvalidRevision

File has an unrecognize revision, possibly from a newer version of the format

frCannotUpgrade

An older revision file could not be upgraded to the current revision

frInvalidSize

A payload block was incorrectly sized

frInvalidCount

The icount and/or wcount in the header was too big

frInvalidBlock

An unknown identifier was used in a payload block

frInvalidChannel

The format contains an invalid channel in a payload block

frInvalidSpeed

The format contains an invalid speed in a SONG block

frInvalidRowCount

A TrackFormat’s rows field exceeds the Song’s track size

frInvalidRowNumber

A RowFormat’s rowno field exceeds the Song’s track size

frInvalidId

An INST or WAVE block contains an invalid id

frDuplicatedId

Two INST blocks or two WAVE blocks have the same id

frInvalidTerminator

The file has an invalid terminator

frReadError

An read error occurred during processing

frWriteError

A write error occurred during processing

Structure

A TrackerBoy module consists of a Header, Payload and Terminator.

Figure 1. TBM File structure

Header

The header structure provides valuable information about the data stored in the payload, as well as versioning information.

The table below defines the layout of the Header structure. Reminder that all multi-byte fields are stored in little-endian. The size of the header is a fixed 160 bytes, with any unused space marked as reserved. Reserved fields can be utilized for future revisions of the format.

The layout of the header depends on the header revision, located in offset 24. The following table is for the current revision of the specification.

Table 1. TBM Header structure
Offset	Size	Type	Field name
+0	12	Char[12]	signature
+12	4	Uint32	versionMajor
+16	4	Uint32	versionMinor
+20	4	Uint32	versionPatch
+24	1	Uint8	m. rev
+25	1	Uint8	n. rev
+26	2	Char[2]	reserved
+28	32	Char[32]	title
+60	32	Char[32]	artist
+92	32	Char[32]	copyright
+124	1	Uint8	icount
+125	1	BiasedUint8	scount
+126	1	Uint8	wcount
+127	1	Uint8	system
+128	2	Uint16	customFramerate
+130	30	Char[30]	reserved

Signature

Every TrackerBoy file begins with this signature:

Table 2. TBM Signature format
+0	+1	+2	+3	+4	+5	+6	+7	+8	+9	+10	+11
`'\0'`	`'T'`	`'R'`	`'A'`	`'C'`	`'K'`	`'E'`	`'R'`	`'B'`	`'O'`	`'Y'`	`'\0'`

in order to identify the file as a TrackerBoy file.

Version (major, minor, patch)

Version information is stored as three 4-byte words. This information determines which version of trackerboy that created the file. Versioning is maintained by keeping a major and minor version, followed by a patch number. For example, if the trackerboy version is v1.0.2, then the header’s version fields will contain 0x1 0x0 and 0x2 for major, minor and patch, respectively.

Major revision (m. rev)

This version number indicates a breaking change for the file format. Starts at 0 and is incremented whenever the layout of the header or payload changes. TrackerBoy will not attempt to read modules with a newer major version, but can attempt to read older versions (backwards-compatible).

Examples of breaking changes:

Modifying the layout of the Header structure
Adding/removing blocks to the payload
Modifying the format of a payload block

Minor revision (n. rev)

This version number indicates a change in the format that is forward-compatible with older versions. Changes such as utilizing a reserved field in the header.

Note	TrackerBoy can read any module file as long as its major revision is less than or equal to the current revision. Saving always uses the current revision, so saving an older major version is a one-way upgrade.

Author information (title, artist, copyright)

These fields in the header are fixed 32 byte strings. Assume ASCII encoding. Any unused characters in the string should be set to 0 or \0. Since these strings are fixed, null-termination is not needed.

Note	The size and naming of these strings are identical to the ones in *.gbs file format. This is intentional, as exporting to gbs is a planned feature.

icount, scount and wcount

icount: instrument count
scount: song count
wcount: waveform count

These counter fields determine the number of INST, SONG and WAVE blocks present in the payload, respectively. icount and wcount can range from 0-64 and is unbiased. scount can range from 0-255 and is biased (a value of 0 means there is 1 SONG block).

System

The system field determines which Game Boy model this module is for. Since the driver is typically updated every vblank, the system field determines the framerate, tick rate or vblank interval for the driver. The available choices are listed in the following table:

Table 3. Valid system values
Identifier	Value	System name	Tick rate
systemDmg	0	DMG	59.7 Hz
systemSgb	1	SGB	61.1 Hz
systemCustom	2	N/A	varies

If the system is systemCustom, then a custom tick rate is used instead of the system’s vblank. The custom tick rate is stored in the customFramerate field of the header. This custom tick rate must be a positive number and nonzero. The implementation should default to 30 fps when the custom tick rate does not meet this criteria.

If the system does not match any of these values, then the implementation should treat the system as the default, systemDmg.

Reserved

The remainder of the header is the reserved field(s). This is an unused section that may be utilized in future versions of the format if needed.

This field should be zeroed but the specification does not require it. The field can be safely ignored when processing module files.

Payload

The payload is located right after the header (offset 160). It contains a variable number of "blocks" or tagged data with a size.

Blocks

A block in the payload contains three parts: the id, the length and the data. The format of the block is shown below:

Table 4. Format of a payload block.
Offset	Size	Description
0	4	Identifier
4	4	Length
8	Length	Data

Block types

Each block has an identifier, which determines the type of data present in the block. The table below lists all recognized identifiers in the payload.

Table 5. Block types used in TBM files
Identifier	Value (Uint32)	Description
"COMM"	0x4D4D4F43	User set comment data for a module.
"SONG"	0x474E4F53	Container for a single song.
"INST"	0x54534E49	Container for a single instrument.
"WAVE"	0x45564157	Container for a single waveform.

Block ordering

Blocks are stored categorically by type in the following order:

Table 6. Order and total number of blocks in the payload
Order	Identifier	Count
1	COMM	1
2	SONG	1-256
3	INST	0-64
4	WAVE	0-64

A payload will always have exactly one COMM block, at least one SONG block, and 0 or more INST and WAVE blocks.

COMM block format

The COMM block just contains a UTF-8 string that is the user’s comment data. The string is not null-terminated since the length of the string is the length of the block. If the user has no comment set, then this block is empty (length = 0).

SONG block format

A SONG block contains the data for a single song in the module. Songs are stored in the same order as they were in the module’s song list. The first song block is song #0 and so on.

Song data is composed of the following, in this order:

The name, LString
A SongFormat record
The song order, as an array of OrderRow or Char[4][patternCount]
The track data, as a sequence of TrackFormat and RowFormat records

Song name

The first part of a SONG block is the song’s name, as an LString.

SongFormat

Following the name is a SongFormat record:

Offset

Size

Type

Field name

BiasedUint8

rowsPerBeat

BiasedUint8

rowsPerMeasure

Uint8

speed

BiasedUint8

patternCount

BiasedUint8

rowsPerTrack

Uint16

numberOfTracks

Uint8

numberOfEffects

rowsPerBeat: number of rows that make up a beat, used by the front end for highlighting and tempo calculation.
rowsPerMeasure: number of rows that make up a measure, used by the front end for highlighting.
speed: Initial speed setting for the song in Q4.4 format

patternCount

number of patterns for the song

rowsPerTrack

the size, in rows, of a track (all tracks have the same size).

numberOfTracks

number of tracks stored in this song block.

numberOfEffects

this byte contains the number of effect columns visible for each channel. Each count ranges from 1-3 and is stored as a 2 bit number in this byte. Bits 0-1 are the count for CH1, bits 2-3 are the count for CH2 and so on.

Note	This value is for UI purposes only and has no effect on playback!

Song Order

Next is the song order, an array of OrderRow records with the dimension being the patternCount field from the song format record. An OrderRow record is a set of 4 Uint8 track ids, with the first being the track id for channel 1 and the last being the id for channel 4.

Track Data

Finally, the rest of the block contains the pattern data for every track in the song. Each track gets its own TrackFormat record and an array of RowFormat records.

The TrackFormat record:

Offset

Size

Type

Field name

Uint8

channel

Uint8

trackId

BiasedUint8

rows

channel: determines which channel the track is for. Valid values 0-3.
trackId: determines the track id to use for this track
rows: the number of RowFormat records that follow this structure

The RowFormat record:

Offset

Size

Type

Field name

Uint8

rowno

TrackRow

rowdata

rowno

the index in the track’s row array to set

rowdata

the data to set at this index, where the TrackRow type is:

Offset

Size

Type

Field name

Uint8

note

Uint8

instrument

Effect[3]

effects

with Effect being:

Offset

Size

Type

Field name

Uint8

effectType

Uint8

effectParam

and effectType should be any of the following:

Value

Effect Syntax

Identifier

---

etNoEffect

Bxx

etPatternGoto

C00

etPatternHalt

Dxx

etPatternSkip

Fxy

etSetTempo

Txx

etSfx

Exx

etSetEnvelope

V0x

etSetTimbre

I0x

etSetPanning

Hxx

etSetSweep

Sxx

etDelayedCut

Gxx

etDelayedNote

L00

etLock

0xy

etArpeggio

1xx

etPitchUp

2xx

etPitchDown

3xx

etAutoPortamento

4xy

etVibrato

5xx

etVibratoDelay

Pxx

etTuning

Qxy

etNoteSlideUp

Rxy

etNoteSlideDown

Jxy

etSetGlobalVolume

The last RowFormat record for the last track ends the SONG block.

INST block format

An INST block contains the data for a single instrument. The data is structured in this order:

The instrument’s id, Uint8
The instrument’s name, LString
An InstrumentFormat record
4 sequences each composed of:
1. A SequenceFormat record
2. The sequence’s data

Id and Name

The INST block data begins with a 1 byte id (0-63), followed by an LString name.

Note	`WAVE` blocks also begin with an id and name in the same format.

InstrumentFormat

The InstrumentFormat record defines settings for the instrument.

Offset

Size

Type

Field name

Uint8

channel

Bool

envelopeEnabled

Uint8

envelope

channel: determines which channel the instrument is for, 0 is channel 1, 3 is channel 4, etc. Valid values 0-3.
envelopeEnabled: set to true if the instrument has an initial envelope setting.
envelope: the initial envelope setting that is used if envelopeEnabled was true.

Sequence data

Following the InstrumentFormat record is the sequence data for each of the instrument’s sequences. Data for a sequence is structured as a SequenceFormat record followed by the sequence data. There are four kinds of sequences for every instrument. The kind of sequence the data is for is determined by its order in the block:

Order	SequenceKind
0	skArp
1	skPanning
2	skPitch
3	skTimbre

The SequenceFormat record:

Offset

Size

Type

Field name

Uint16

length

Bool

loopEnabled

Uint8

loopIndex

length: The length of the sequence data. Following this record will be this number of Uint8 bytes that are the sequence’s data. Valid values 0-256.
loopEnabled: Determines if this sequence has a loop index.
loopIndex: The index of the loop point.

WAVE block format

A WAVE block contains the data for a single waveform. The data is structured in this order:

The waveform’s id, Uint8
The waveform’s name, LString
The waveform’s data, a 16 byte array of packed 4-bit PCM samples

id and name

Same as INST blocks, the WAVE block’s data begins with the waveform’s id and name.

Waveform data

Next is the waveform’s data, a 16 byte array of 32 4-bit PCM samples, with the same layout as the Game Boy’s CH3 Wave RAM. The first sample in the waveform is the upper nibble of the first byte in the array, whereas the last sample is the lower nibble of the last byte in the array.

The waveform data ends the WAVE block.

Terminator

A terminator follows the payload, it is the signature, reversed.

Table 7. TBM Terminator format
+0	+1	+2	+3	+4	+5	+6	+7	+8	+9	+10	+11
`'\0'`	`'Y'`	`'O'`	`'B'`	`'R'`	`'E'`	`'K'`	`'C'`	`'A'`	`'R'`	`'T'`	`'\0'`

EOF

The module file should be at end of file (EOF) after the terminator.

Module Piece Format

Module piece files contain a single part of a module, for easy reuse and sharing. A piece file can contain either a song (*.tbs), an instrument (*.tbi) or a waveform (*.tbw).

Structure

A piece file consists of a header followed by a payload. The payload is a single INST, SONG or WAVE block. A terminator is not used since there is only one block present in the payload.

Figure 2. Structure of a module piece file

Header

The Header for a piece file is the same as the module one, but a reduced variant. This reduced header contains only the signature, version and revision fields, or bytes 0-25. The fields are exactly the same as the module format, see the previously defined Header format for more info.

Payload

The payload is a single INST block for *.tbi files, a single SONG block for *.tbs files or a single WAVE block for *.tbw files.

The format of these blocks are the same as the ones used in the module file format except for one key detail: the id is omitted for INST and WAVE blocks.

Note	INST and WAVE blocks will be 1 byte less than their module counterpart, since the Id is omitted.