GeneralSound/docs/format_ust.txt

=============================================================================
Ultimate Soundtracker module format description
Version 0.1 (w) 1997 by Michael Schwendt <sidplay@geocities.com>
=============================================================================

This is  an attempt  on documenting  the file  format of music modules
(MOD  files)  that  were  created  with  Karsten  Obarski's   Ultimate
Soundtracker, the original  Soundtracker that started  it all back  in
1987/88 on AMIGA.

Whereas  various   Soundtracker  derivatives   such  as    Protracker,
Noisetracker,  or  a  few  of  the  Soundtracker v2 series, are widely
known and supported, hardly  any available MODule player  supports old
and classic Soundtracker modules.

In  1988  and  later  Karsten  Obarski's  original program was hacked,
ripped  off,  and  improved  by  various programmers from cracking and
demo groups.  Some of the  first were Exterminator of TJC, Tip  of The
New  Masters,  Unknown/D.O.C,  Mahoney  &  Kaktus  of  Northstar   and
Silents, and Mnemotron/Spreadpoint.  During this process the  original
module  format  got  altered  and  extended.   One  by-product of this
development   was    partial   incompatibility    between    competing
Soundtrackers and their modules,  most noticably between the  Ultimate
Soundtracker and  the first  illegal series  of Soundtracker versions.
Even  worse,  some  changes  made  it  impossible  -  or at least very
difficult - to detect the true module format.

Years later  people without  knowledge of  the incompatibility between
the  original   Soundtracker  module   format  and   successors   like
Soundtracker 2.4 or Protracker  damaged modules by converting  them to
Protracker  format.   It  would  be  tiresome  trying to find any such
module in any  collection and either  repair or remove  it in case  it
can't be restored properly.  However, the opposite doesn't seem to  be
a real choice either.  Rather than trying to find and convert any  old
Soundtracker module  into some  well-defined module  format, it sounds
much more reasonable  to add native  Ultimate Soundtracker support  to
MODule players.

Old Soundtracker modules  that are likely  to be found  in any classic
collection  are  those  composed  by  Karsten Obarski himself, such as
famous game sounds from  Amegas, Crystal Hammer, Ralleymaster  (sic!),
or Sarcophaser, to name a few, and others done in 1987 and 1988,  most
noticably the unforgotten tunes by SLL.

Rather  than  serving  as  a  complete  MOD  reference,  this document
focuses  on  relevant  differences  between  the Ultimate Soundtracker
format and the first  popular hacked Soundtracker versions  that still
featured  4  voices  and  15  channels.   The terminology used in this
document might differ from other available MOD format descriptions.

The following abbreviations are  local to this document.  Please don't
use them in MOD players. They are uncommon and would confuse users.

 UST -> Ultimate Soundtracker
 ST  -> Soundtracker (scene versions)
 MST -> Master Soundtracker
 PT  -> Protracker
 NT  -> Noisetracker

One false assumption often made is that "M.K." is an ID introduced  in
Protracker or by "Mahoney & Kaktus".  The truth is it was  Unknown/DOC
who put his initials into Soundtracker 2.4 to server as format ID  and
indicate 31 samples.  Mahoney & Kaktus used "N.T." in Noisetracker.

Thanks  to  Jake  Stine  (MikMod)  and  Lada Kopecky (A.M.P) for their
interesting discussions about UST format detection proposals.

If you have any comments or corrections, feel free to e-mail me.

-----------------------------------------------------------------------------

Short summary of differences and incompatibilities (more below):

 - maximum sample length
 - numbering of effects
 - playing of repeat-samples (looping samples)

Format characteristics:

 - 4 tracks (voices, channels)
 - 15 sample headers (instrument definitions, slots)
 - sample header length is 30 bytes
 - 128 pattern table steps (pattern order)
 - pattern length is 1024 bytes

File offset         Content description

 + 0                song/module working title
 + 20               15 sample headers (see below)
 + 470              song length (number of steps in pattern table)
 + 471              song speed in beats per minute (see below)
 + 472              pattern step table
 + 600              pattern data (1024 bytes) for each pattern number
 .                  that can be found in entire pattern table
 .
 + ???              sample data


Sample header (big-endian byte order):

 + 0  sample file/name
 + 22 sample length in words
 + 24 volume word (0-64)
 + 26 sample repeat offset in bytes
 + 28 sample repeat length in words (0=loop off, >1 loop on)
[+ 30 (end)]


Noticable features in sample header:

 - Volume word does not contain a "Finetuning" value in its high-byte.

 - Sample repeat offset is in bytes (unlike PT, NT, and ST 2.5, where
   it is specified as number of words).

 - Maximum sample length is 9999 bytes decimal, but 1387 words hexadecimal.
   Longest samples on original sample disk ST-01 were 9900 bytes.

 - Sample file names have no disk name prefix like "st-01:" or "ST-01:"
   since only a single sample disk was supported. In later ST versions
   one had to enter a disk name.

   Caveat: There are hacked modules where disk names have been
           dropped or added.

Notes on playing repeat-samples:

 - Unlike PT only the loop-area is played. PT plays from Start to Repeat
   End and then loops between Repeat Start and Repeat End. UST modules
   often (!) sound screwed if repeat-samples are played incorrectly.
   Hence: Sample Start = Repeat Start, Sample Length = Repeat Length.

Effects:

 - Arpeggio: 1xy (1. base note)
                 (2. x semitones higher)
                 (3. y semitones higher)

 - Pitchbend: 2xy (20y = sub y from period = pitch up)
                  (2x0 = add x to period = pitch down)

Conversion of UST effects to PT (or MST):

 - Arpeggio:  1xy => 0xy

 - Pitchbend: 20y => 10y
              2x0 => 20x

-----------------------------------------------------------------------------

Song speed in beats per minute:

The byte at module offset 471  is not the "song restart position".  It
is meant to be  the song speed in  beats per minute (bpm),  satisfying
this formula:

  AMIGA Timer-IRQ value = (240-bpm)*122

This might  be constant  for other  15-instrument ST  modules, but not
for the Ultimate Soundtracker.

The default for UST  modules is 0x78 =  120 BPM = 48  Hz. AMIGA custom
chips only ran at 716 kHz,  which is one tenth of the  processor clock
speed.  Thus:

  freq = 716 kHz / ((240-bpm)*122)
  [freq] = kHz

Rumours state  that Karsten  Obarski made  a failure  upon calculating
that default speed and planned to get a default of 50 Hz. For sure  he
didn't calculate  at full  precision.   This would  have required  the
true accurate clock speed of the  AMIGA.  And that one was  varying in
different documentation.  If you happen to find a more accurate  clock
speed, the result might differ by 1-2 Hz more. Look:

  with 716 kHz = 716*1024 Hz : freq(120) ~= 50.08 Hz
  with 716 kHz = 716*1000 Hz : freq(120) ~= 48.9 Hz

-----------------------------------------------------------------------------

An experimental format detection:

Note that the recommended way is  to either default to UST or  provide
a switch to  toggle between UST  and ST. The  fact that an  UST module
can't  be  detected  100%  percent  correctly,  can't  make  MODplayer
authors happy. But think about a switch at least.

 - Check whether every Sample Length is <= 9999 bytes. If not, the
   MOD cannot be in UST format. Newer Sountrackers supported samples
   longer than 9999 bytes. So, it might be in some newer ST format.

   Caveat: It still could be a ST, MST or PT module with short samples.

 - If (Repeat Offset in words + Repeat Length in words) converted to
   bytes exceeds Sample End and/or length of file, it is an UST file
   with Repeat Offset in bytes. In other words, first assume Repeat
   Offset to be given in words and calculate the Repeat End in order
   to be able to check the sample range:

     Sample Start + Repeat Offset * 2 = Repeat End

   If this Repeat End exceeds the sample end, it is an UST module and
   Repeat Offset is specified in bytes.

   Caveat: The looping in some ST modules (bad rips, for instance)
   could go a couple of bytes past the end, so better add some safety
   bytes.

 - If you use a format loader/converter, scan each pattern for the
   availability of PT effects or any effects other than 1xy and 2xy.
   If available it cannot be UST.

   Might be an idea to check the pattern data for effects 1xy and 2xy
   with xy > 0x1f. Could be that no Soundtracker module would ever have
   a reason to pitchbend up or down that far, while almost any UST module
   that uses either effect does so. The exception would be a UST module
   that uses only 20y / 21x commands or a very low arpeggio.

Of  course,  the  only  exception  to  the  rule  now  is  if  a newer
SoundTracker module doesn't  follow the sample  prefix rules, has  all
samples < 9999 bytes, uses no effects at all, and has a loop near  the
start of a sample only. A more advanced detection could check  whether
the samples are from the ST-01 sample disk preset.

Master  Soundtracker  1.0  introduced  new  effects and changes effect
numbering.

Soundtracker 2.0  was based  on Master  Soundtracker 1.0. Soundtracker
2.0, 2.1, 2.2, 2.3, 2.4 have Repeat Offset specified in bytes.  As  of
Soundtracker  2.5  Repeat  Offset  is  in  words.   Soundtracker   2.3
introduced  31  samples.   Soundtracker  2.4  introduced Unknown/DOC's
initials  "M.K."  as   format  ID.  Soundtracker   2.6  introduced   a
double-sized  pattern  order  table  and  the  "MTN"  format  ID  from
Mnemotron.

In  Noisetracker   1.0,  Repeat   Offset  is   specified  in    words.
Noisetracker features 31 samples and the "N.T." ID.

-----------------------------------------------------------------------------