Music file formats supported by QTM v1.42          Steve Harrison, 1993-2013
-----------------------------------------------------------------------------

QTM v1.42 directly supports 4 different file formats. Each format is based on
the ProTracker 31 sample format, but contains differences such as 8 channel
support, and differing ranges of effects.


ProTracker 2.x/3.x file format

Offset | Length | Meaning
-------+--------+------------------------------------------------------------
     0 |     20 | Song name, ctrl character terminated, if less than 20 chars
    20 |  31*30 | Sample information table, for 31 samples (see below)
   950 |      1 | Number of sequences in song (1-128)
   951 |      1 | Unused by ProTracker or QTM, set to 127 for compatibility
   952 |    128 | Sequence table, 1 byte per sequence (see below)
  1080 |      4 | Format recognition bytes, ascii characters "M.K." or "M!K!"
  1084 |   1024 | Pattern 1
  2108 |   1024 | Pattern 2
  3132 |   1024 | Pattern 3
  .... |   1024 | Pattern ....
 xxxxx |  nnnnn | Sample data, stored in signed linear format
       |        | (first sample starts immediately after end of last pattern)

This is the 'main' 4 channel format supported by QTM, it is important to note
that QTM does not distinguish between 'format recognition bytes' appart from
those listed over the next few file formats. The reason for this is that many
ProTracker songs have corrupted, or blanked, recognition bytes, to stop 
recognition bytes, at offset 1080, can be either "M.K." or "M!K!". The latter
signifies that the song contains more than 64 patterns. QTM does not take any
special action in either case, as it can cope with any number of patterns.
But if you are converting a song into ProTracker format, you should enter
"M!K!" if the song has more than 64 patterns, to allow compaibility with
other packages.


ProTracker 1.x/Sound Tracker 15 sample file format

Offset | Length | Meaning
-------+--------+------------------------------------------------------------
     0 |     20 | Song name, ctrl character terminated, if less than 20 chars
    20 |  15*30 | Sample information table, for 15 samples (see below)
   470 |      1 | Number of sequences in song (1-128)
   471 |      1 | Set to 120, to signify 15 sample format
   472 |    128 | Sequence table, 1 byte per sequence (see below)
   600 |   1024 | Pattern 1
  1624 |   1024 | Pattern 2
  2648 |   1024 | Pattern 3
  .... |   1024 | Pattern ....
 xxxxx |  nnnnn | Sample data, stored in signed linear format
       |        | (first sample starts immediately after end of last pattern)

This file format also differs in the effects supported. 15 sample songs
cannot have fine-tunning on samples, or use the extended speed tempo range
(32-255) - that range is just treated as normal speed settings.


Startrekker 4 channel file format

Offset | Length | Meaning
-------+--------+------------------------------------------------------------
     0 |     20 | Song name, ctrl character terminated, if less than 20 chars
    20 |  31*30 | Sample information table, for 31 samples (see below)
   950 |      1 | Number of sequences in song (1-128)
   951 |      1 | Unused by Startrekker or QTM, set to 127 for compatibility
   952 |    128 | Sequence table, 1 byte per sequence (see below)
  1080 |      4 | Format recognition bytes, ascii characters "FLT4"
  1084 |   1024 | Pattern 1
  2108 |   1024 | Pattern 2
  3132 |   1024 | Pattern 3
  .... |   1024 | Pattern ....
 xxxxx |  nnnnn | Sample data, stored in signed linear format
       |        | (first sample starts immediately after end of last pattern)

This format is identical to the ProTracker 2.x/3.x file format, appart from
the format recognition bytes, at offset 1080. Although the range of effects
supported in Startrekker songs is different to ProTracker songs. The main
difference being the speed/tempo effect. In Startrekker songs, speeds in the
extended tempo range (32-255) are not treated as tempos, but just as normal
speed settings.


Startrekker 8 channel file format

Offset | Length | Meaning
-------+--------+------------------------------------------------------------
     0 |     20 | Song name, ctrl character terminated, if less than 20 chars
    20 |  31*30 | Sample information table, for 31 samples (see below)
   950 |      1 | Number of sequences in song (1-128)
   951 |      1 | Unused by Startrekker or QTM, set to 127 for compatibility
   952 |    128 | Sequence table, 1 byte per sequence (see below)
  1080 |      4 | Format recognition bytes, ascii characters "FLT8"
  1084 |   1024 | Pattern 0 (channels 1-4)
  2108 |   1024 | Pattern   (channels 5-8)
  3132 |   1024 | Pattern 2 (channels 1-4)
  .... |   1024 | Pattern n ....
 xxxxx |  nnnnn | Sample data, stored in signed linear format
       |        | (first sample starts immediately after end of last pattern)

This format is identical to the Startrekker 4 channel format, appart from the
format recognition bytes, at offset 1080, and that the odd numbered patterns 
now contain data for the last four channels of the previous pattern.

Note: only even numbered patterns appear in the sequence table.



Sample information table (all formats)
--------------------------------------

Information for one sample is:

Offset | Length | Meaning
-------+--------+------------------------------------------------------------
    00 |     22 | Sample name
    22 |      2 | Sample length, in bytes, divided by 2 (MSB-LSB data)
    24 |      1 | Finetuning value, signed 4 bits ie. &F=-1, &E=-2, &7=+7
       |        | Upper 4 bits should be 0 (Finetuning 0 on 15 sample format)
    25 |      1 | Volume of sample, (min) 0-64 (max), linear scale
    26 |      2 | Repeat offset, in bytes from sample start, divided by 2
    28 |      2 | Repeat length, in bytes, divided by 2

Note repeat offset + repeat length must NOT be greater than sample length.



Sequence table (all formats)
----------------------------

The sequence table is 128 bytes long, and each byte holds a pattern number
(0-99, even numbers only if 8 channel) for that sequence position. The number
of patterns in the song is calculated by scanning for the largest number in
the sequence table, and adding 1 (to get within the range 1-100).



Pattern data (4 channel formats)
--------------------------------

Each pattern consists of 64 bars. Each bar contains data for 4 channels, as
follows:

Offset | Length | Meaning
-------+--------+------------------------------------------------------------
    00 |      4 | Note word for channel 1 \
    04 |      4 | Note word for channel 2  \_ Bar 1
    08 |      4 | Note word for channel 3  /
    12 |      4 | Note word for channel 4 /
    16 |      4 | Note word for channel 1
    nn |      4 | ...

Note word format:    bits   0-3 | High 4 bits of note period
                     bits   4-7 | High 4 bits of sample number
                     bits  8-15 | Low 8 bits of note period
                     bits 16-19 | Effect number
                     bits 20-23 | Low 4 bits of sample number
                     bits 24-31 | Effect data

From this you can calculate a 12 bit note period, 8 bit sample number, 4 bit
effect number, and 8 bit effect data



Pattern data (8 channel format)
-------------------------------

Each pattern is as in 4 channel format, the extra channels 5-8 are contained
in the next (odd numbered) pattern in the song.
