@node The Protracker format, The Protracker file format, Tracker memory consumption, Technical Information
@cindex The Protracker format
@cindex Module format
@cindex Soundtracker format
@cindex Decoding soundtracker files

@chapter A description of the Protracker format

As it is very difficult to get a good description of the Protracker format, I've tried
to write my own. If you find any mistakes, please send me corrections at @value{EMAIL}.
@menu
* The Protracker file format::
* Decoding pattern information::
* Soundtracker and Protracker tempo::
* Protracker finetunes::
* Sample numbers and note periods::
* Base effects::
* Protracker extended effects::
@end menu
@node The Protracker file format, Decoding pattern information, The Protracker format, The Protracker format 
@section The binary Protracker file format

@ifinfo
@display
Offset
---------------------------------------
  0        20 bytes        Song Name @footnote{Song names and sample names
will be converted to a null-terminated string.
Be very careful as to what to allow there@dots{}}
 20        22 bytes        Sample name
 42         1 word         sample length @footnote{Sample length, 
looping start point, looping length are normally stored
as a number of words. Occasionally, in very old modules, the looping start
point might be stored in bytes (case in point: @file{kawai-k1}). Checking
looping start point + looping length against sample length might discover
the problem. Sound samples are 8-bit signed}
 43         1 byte         finetune @footnote{Finetune does only exist for protracker modules: if the signature isn't 
M.K./M!K!, it should be 0. Normal values are 0-15. 
@c @xref{Protracker finetunes}, for a discussion of finetunes. 
Signature M!K! should only occur if the number of patterns is greater than 64.}
 44         1 byte         volume @footnote{This is the sample default volume, 
when no specific values have been given. 
Normal values are 0-64. Some songs include out of range values. Be sure to normalize to 0-64}
 46         1 word         looping start point
 48         1 word         looping length
          ---------
           30 bytes @footnote{There are 15 sample info entries in old soundtracker files, 
31 in newer protracker/noisetracker ones. 
The difference lies in the signature. Valid signatures are M.K. / M!K! (for Mahoney & Kaktus), 
FLT4/FLT8 for startrekker modules.}

20+30*n     1 byte         length of song @footnote{Range 1-128}
21+30*n     1 byte         number of patterns to load @footnote{Do not trust this byte ! 
Very old trackers used it to indicate the number of pattern indices, 
so it's set to 127 by protracker to enable old trackers
to load this module. Noisetracker uses this byte for restart.}
22+30*n   128 bytes        pattern indices @footnote{This is a sequencing order: 
like in play pattern #2, then #4, then #2 again, and so on@dots{}}

1080        4 bytes        signature (31 samples modules only)

150+30*n 1024 bytes        each pattern @footnote{We use the highest pattern number in the pattern 
indices table to determine the number of patterns p to load. Older trackers saved it as
`number of patterns to load'.
}

150+30*n                   sample data @footnote{Sample data is given for each existing sample. 
Non-existing samples have a length of 0 or 1 (usually 1).
Sample values are signed bytes, in 2-complement notation. Each sample length
is a multiple of 2 in bytes.}
+1024*p
@end display
@end ifinfo
@tex
@halign{@hfil#@quad&@hfil # &#@hfil@quad&#@hfil@cr
Offset@cr
@multispan{4}@hrulefill@cr
  0       &20&bytes      & Song Name @footnote{Song names and sample names
will be converted to a null-terminated string.
Be very careful as to what to allow there@dots{}}\vadjust{\vskip 4pt}@cr
 20       &22&bytes      & Sample name\cr
 42       & 1&word       & sample length @footnote{Sample length, 
looping start point, looping length are normally stored
as a number of words. Occasionally, in very old modules, the looping start
point might be stored in bytes (case in point: @file{kawai-k1}). Checking
looping start point + looping length against sample length might discover
the problem. Sound samples are 8-bit signed}\cr
 43       & 1&byte       & finetune @footnote{Finetune does only exist for protracker modules: if the signature isn't 
M.K./M!K!, it should be 0. Normal values are 0-15. 
%@c @xref{Protracker finetunes}, for a discussion of finetunes. 
Signature M!K! should only occur if the number of patterns is greater than 
64.}\cr
 44       & 1&byte       & volume @footnote{This is the sample default volume, 
when no specific values have been given. 
Normal values are 0-64. Some songs include out of range values. Be sure to 
normalize to 0-64}\cr
 46       & 1&word       & looping start point\cr
 48       & 1&word       & looping length\cr
			 &\multispan{2}\hrulefill\cr
          &30&bytes @footnote{There are 15 sample info entries in old soundtracker files, 
31 in newer protracker/noisetracker ones. 
The difference lies in the signature. Valid signatures are M.K. / M!K! (for 
Mahoney \& Kaktus), 
FLT4/FLT8 for startrekker modules.}\vadjust{\vskip 4pt}\cr

20+30*n   & 1&byte       & length of song @footnote{Range 1-128}\cr
21+30*n   & 1&byte       & number of patterns to load @footnote{Do not trust this byte ! 
Very old trackers used it to indicate the number of pattern indices, 
so it's set to 127 by protracker to enable old trackers
to load this module. Noisetracker uses this byte for restart.}\cr
22+30*n  &128&bytes      & pattern indices @footnote{This is a sequencing order: 
like in play pattern \#2, then \#4, then \#2 again, and so on@dots{}}\cr

1080    &   4&bytes      & signature (31 samples modules only)\cr

150+30*n&1024&bytes      & each pattern @footnote{We use the highest pattern number in the pattern 
indices table to determine the number of patterns p to load. Older trackers saved it as
`number of patterns to load'.
}\cr

150+30*n&   &            & sample data @footnote{Sample data is given for each existing sample. 
Non-existing samples have a length of 0 or 1 (usually 1).
Sample values are signed bytes, in 2-complement notation. Each sample length
is a multiple of 2 in bytes.}\cr
\quad+1024*p\cr
}

@end tex

@node Decoding pattern information, Soundtracker and Protracker tempo, The Protracker file format, The Protracker format
@section Decoding pattern information

Each pattern holds 64 sets of 4 events, one for each Amiga track, numbered 
0 to 3 in the usual Amiga way (0-3: left channels, 1-2: right channels, @pxref{Amiga audio hardware}).
Some modules programmed on PC have a special signature @code{6CHN} or @code{8CHN},
and accordingly, they feature more channels.

The four bytes per event are to be decoded as follows:

@example
    _____byte 1_____   byte2_    _____byte 3_____   byte4_
   |                | |      |  |                | |      |
   0000          0000-00000000  0000          0000-00000000

   Upper four    12 bits for    Lower four    Effect/parameters
   bits of sam-  note period.   bits of sam-
   ple number.                  ple number.
@end example

Sample number should be in the range 0-31@dots{} anything else is an error, and
should be flagged as such. 
For standard protracker modules, the note period can be converted to a note n
with the following lookup table@footnote{Actually, tracker doesn't use this
exact table, but builds a precise well-tempered scale using powers of 2, see
@file{notes.c}}:
@table @asis
@item  C-1 to B-1 
856,808,762,720,678,640,604,570,538,508,480,453
@item  C-2 to B-2 
428,404,381,360,339,320,302,285,269,254,240,226
@item  C-3 to B-3 
214,202,190,180,170,160,151,143,135,127,120,113
@end table

Older tracker modules may use highly non-standard periods.
I have yet to encounter some, though. @footnote{It would be easy to add some
heuristics to the virtual player to detect these modules, and build the
corresponding well-tempered scale on the fly. The hardest decisions would
be to adjust the table because of limited precision (values stored as integer
arithmetic) and possible distinct scales for each sample.}
As a result tracker converts these pitch values to notes and stores notes 
internally.
These pitch values @emph{are} Amiga-dependent. @xref{Amiga audio hardware}, for further details.

The effect command has two parts:
an effect and parameters. You should actually decode it as three independent
nibbles: e (effect) phi (parameter, hi-part), plow (parameter, low-part).
The interpretation is very dependent of the actual command involved. In many
cases, phi and plow are read as a single byte parameter (para=phi<<4 | plow)



@node Soundtracker and Protracker tempo, Protracker finetunes, Decoding pattern information, The Protracker format
@section Protracker tempo
The player uses two tempo values: fundamental tempo (t1) and fine tempo (t2,
invention of protracker).

By default, t1=6 and t2=125.
A tick occurs with a frequency of 50*t2/125 Hz (some specific tracker tunes
have been developped on NTSC machines with a buggy tracker and the frequency
is 60*t2/125 Hz in that case).

The basic play-sequence takes t1 ticks:
0st tick: read new series of event and applies them. Do @emph{not} apply on-going
effects (violent contrast with MED).
1st to t1-1th ticks: apply effects.
then start again.

@node Protracker finetunes, Sample numbers and note periods, Soundtracker and Protracker tempo, The Protracker format 
@section The finetune concept
Finetune is a weird invention of protracker. Since it is used very often,
we can't avoid it.

It must be decoded as follows:
@footnote{This is actually a two-complement value, but over a nibble, which is
a bit unusual.} 
@display
Value:    0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
Finetune: 0 +1 +2 +3 +4 +5 +6 +7 -8 -7 -6 -5 -4 -3 -2 -1
@end display
Its interpretation is as follows: an instrument with a current finetune of f
should be played offset by f/8 halftones up.
In the end, to find the correct pitch to play a note at, you take the note 
period @emph{as stored in the table for f=0}, convert it to a note value, and then
offset it to finetune f, compute the correct pitch [look it up] and play the
note. Loading a sample (as in sample number != 0) will obviously update the
finetune for the corresponding channel. There is also an extended command to
change a sample finetune without loading a new sample (see module @file{crystal_rain}
for instance). @xref{Set finetune}.

In a module, the stored pitch always use the base table and never takes finetune
into account. So, to play a Protracker note you need to
@itemize @minus
@item
decode the note from the pitch value using the base pitch table.
@item
look up the new pitch according to the current finetune for that channel.
@item
play the note at the corrected frequency.
@end itemize

@node Sample numbers and note periods, Base effects, Protracker finetunes, The Protracker format
@section How to set sample numbers and note periods

There has to exist a separate automaton for each of the four channels
of a Protracker song. To have a sample number != 0 means to load
a number of parameters from the sample information:
@itemize @minus
@item
its default volume (special case: @pxref{Set volume})
@item
its finetune (@pxref{Protracker finetunes}, @pxref{Set finetune},
for the extended finetune command)
@end itemize
Likewise, to have a note period different from 0 means to change the note period 
immediately, except for the @ref{Tone portamento} and 
@ref{Tone portamento + Volume slide} commands.




@node Base effects, Arpeggio, Sample numbers and note periods, The Protracker format
@section Base effects
The first trackers didn't have many effects. The only program that knows something about them
is ProWizard, for the Amiga. 
Here is a rundown of the standardized Amiga effects:

@menu
* No effect:         Arpeggio.                   effect 0
* Arpeggio::                                     effect 0
* Portamento up::                                effect 1
* Portamento down::                              effect 2
* Tone portamento::                              effect 3
* Vibrato::                                      effect 4
* Tone portamento + Volume slide::               effect 5
* Vibrato + Volume slide::                       effect 6
* Tremolo::                                      effect 7
* Set sample offset::                            effect 9 @footnote{Note there is no effect 8}
* Slide volume::                                 effect 10
* Far jump::                                     effect 11
* Set volume::                                   effect 12
* Pattern break::                                effect 13
* Extended command: Protracker extended effects. under effect 14
* Set tempo::                                    effect 15
@end menu

@node Arpeggio, Portamento up, Base effects, Base effects
@subheading 0 Arpeggio/No effect
The actual effect depends upon the parameters.
if phi and plow are both null, there is no effect,
else, the pitch changes at each tick, cycling through notes n, n+phi, n+plow 
in this order (phi and plow in half-tones up) 
Previous @ref{Tone portamento} effects will be forgotten, since a note value is needed.

Scrolling mode for no effect:
@example
	1 A-4
@end example
sample number/note

Scrolling mode for arpeggio:
@example
	1 A-4 B-4 A#4
@end example
sample number/note/arpeggiated note 1/arpeggiated note 2

@node Portamento up, Portamento down, Arpeggio, Base effects
@subheading 1 Portamento up
Slide the note pitch up from the current pitch at the rate of para each tick.
There normally is an upper boundary of B-3/pitch 113, meaning that the slide up stops
at that pitch.

Note that there is @emph{no} default value to keep: `Portamento up with a null para'
means `don't do anything'.

Scrolling mode:
@example
	1 A-4   -5
@end example

@node Portamento down, Tone portamento, Portamento up, Base effects
@subheading 2 Portamento down
Slide the note pitch down from the currenty pitch at the rate of para each tick.
There normally is a lower boundary of C-1/pitch 856, meaning that the slide down stops
at that pitch.

Note that there is @emph{no} default value to keep: `Portamento down with 
a null para' means `don't do anything'.

Scrolling mode:
@example
	1 A-4   +5
@end example

@node Tone portamento, Vibrato, Portamento down, Base effects
@subheading 3 Tone portamento
Slide the note pitch from the current pitch to the given note pitch at the rate
of para each tick. You can keep on sliding without having to specify a new
para nor a new note. @*
The goal is reset to 0 when reached, so if you reach the note, no Tone
portamento without a goal will have an effect.@*
You can change the rate without having to specify a new note.@*
If you specify a new note, the current pitch is used as a starting point,
not the previous goal or anything like that.@*
A Tone portamento when the goal is already reached has no effect.

If @ref{Glissando control} has been applied, the pitch is rounded to the nearest
note for the actual sound output, but this value is not stored anywhere, and has
not any other influence on the player's behaviour.

Scrolling mode:
@example
	1 --> A-4 (  5)
@end example
sample number/-->note to slide(rate of slide)

@node Vibrato, Tone portamento + Volume slide, Tone portamento, Base effects
@subheading 4 Vibrato
phi is the speed of the vibrato and plow the depth of the vibrato.
Null values for phi or plow just mean `keep the previous value.' @*
The basic vibrato waveform is a sine waveform.
It can be changed to a square waveform, or a rampdown waveform.

Here are the actual shapes used, with origin et all.
@example
    ****                     ********                     **
  **    **                                              **
 *        *                                           **
*          *                                        **       
            *        *                                          **
             **    **                                         **
               ****                  *******                **

   Sine 0                     Square 1                Rampdown 2

@end example
(@pxref{Set vibrato waveform}, for a detailled discussion of some aspects of that effect).

The resulting waveform has an amplitude of 2*depth, e.g., its values are in 
the range [-2*depth, 2*depth], and its full period is 64/speed ticks.

The position in the waveform is reset at each and every new note on the 
channel.

Scrolling mode:
@example
	1 A-4 vb 5/3
@end example
sample number / note / depth/speed.

@node Tone portamento + Volume slide, Vibrato + Volume slide, Vibrato, Base effects
@subheading 5 Tone-portamento + Volume slide
Continue the current @ref{Tone portamento} while applying a @ref{Slide volume}.
The parameters are used for the Volume slide. The Tone portamento parameters
currently in effect still apply.

Scrolling mode:
@example
   1 --> A-4  -5
@end example
sample number/note to slide to/volume slide rate

@node Vibrato + Volume slide, Tremolo, Tone portamento + Volume slide, Base effects
@subheading 6 Vibrato + Volume slide
Works like @ref{Tone portamento + Volume slide}: continue the current
@ref{Vibrato} while applying a @ref{Slide volume}.

Scrolling mode:
@example
   1 A-4 vibs +5
@end example
sample number/note number/volume slide rate

@node Tremolo, Set sample offset, Vibrato + Volume slide, Base effects
@subheading 7 Tremolo
Just like @ref{Vibrato} except it affects the volume instead of the pitch.
Note that the amplitude is TWICE that of Vibrato as per protracker 1.1 source.
Also note that there is a range check since the volume must stay in the 0,64 range.

Scrolling mode:
@example
	1 A-4 tr 5/3
@end example
sample number / note / depth/speed.

@node Set sample offset, Slide volume, Tremolo, Base effects
@subheading 9 Set Sample offset
Play the sample from an offset instead of from the start. The offset (in bytes)
is para * 256. If para is null, we use the last para instead.
If offset exceeds the sample length, just play a null sample.

Scrolling mode:
@example
   1 A-4 off%50
@end example
sample number / note / start position (percentage of sample length)

@node Slide volume, Far jump, Set sample offset, Base effects
@subheading 10 Slide volume
If phi is not null slide the volume up by phi each tick,
else slide the volume down by plow each tick.
Note: phi and plow can be zero, there will simply be no volume change.

A good test is the module @file{ghouls and ghosts}: if you mix up the test
for phi and plo, you won't hear the flute solo.

Scrolling mode:
@example
   1 A-4 vol +5
@end example
sample number / note / slide increment

@node Far jump, Set volume, Slide volume, Base effects
@subheading 11 Far jump/Position jump
The next events will be read from pattern index para instead of
the normal position. para has the normal range 0-127@dots{} 
Protracker code can be confusing since it is somewhat confused and intricate there.

Scrolling mode:
@example
   1 A-4 ff 50
@end example
sample number / note / new pattern number

@node Set volume, Pattern break, Far jump, Base effects
@subheading 12 Set volume/Volume change
Set volume for the associated channel to para. The value is pure binary,
the volume is normalized to the range 0-64.

Scrolling mode:
@example
   1 A-4 vol 50
@end example
sample number / note / new volume

@node Pattern break, Protracker extended effects, Set volume, Base effects
@subheading 13 Small jump/Pattern break
The next events will be read from the next pattern starting at
position phi*10+plow instead of 0. @footnote{for strange reasons, we have a BCD value
here.} Values greater than 64 are reduced to 0 !

Scrolling mode:
@example
   1 A-4 skp 25
@end example
or
@example
	1 A-4 next
@end example
(if starting at position 0 in next pattern)


@node Set tempo, Amiga audio hardware, Invert loop, Base effects
@subheading 15 Set tempo
If 0 <= para <= 31, set t1=para, reset t2 to 125. 
Else, set t2=para (for Protracker).
Older trackers don't ever change t2, but always set t1=para.
Special value 0 is supposed to end the module with Protracker.@*
Special case: several set speed commands in the same events. The later ones
do take precedence upon the earlier ones if both are supposed to affect t1
or t2. If one set speed command affects t1 and the other t2, the most likely
guess is to set t1 and t2 accordingly, but you @emph{can't} be sure@dots{} you have to
either provide some switch to change your player behavior according to the
value you got, or to apply some heuristic to go on playing@dots{}
@xref{Soundtracker and Protracker tempo}, for more details.

Scrolling mode:
@example
   1 A-4 SPD 7		(for t1 tempo)
	1 A-4 spd%95	(percentage of normal finespeed)
@end example


@node Protracker extended effects, Set filter, Pattern break, Base effects
@section The extended command 14
For older soundtrackers, extended command 14 was simply a toggle for
the filter (@pxref{Set filter}).
Protracker extended this: in the case of command 14, phi is interpreted as a
secondary command number, so the parameter is actually plow for these commands.

@menu
* Set filter::             effect 14-0
* Fine portamento up::     effect 14-1
* Fine portamento down::   effect 14-2
* Glissando control::      effect 14-3
* Set vibrato waveform::   effect 14-4
* Set finetune::           effect 14-5
* Loop pattern::           effect 14-6
* Set tremolo waveform::   effect 14-7
* Retrig note::            effect 14-9@footnote{Note there is not effect 14-8}
* Fine volume slide up::   effect 14-10
* Fine volume slide down:: effect 14-11
* Cut note::               effect 14-12
* Delay note::             effect 14-13
* Delay pattern::          effect 14-14
* Invert loop::            effect 14-15
@end menu

Note that @ref{Glissando control} and @ref{Invert loop} are rarely used.


@node Set filter, Fine portamento up, Protracker extended effects, Protracker extended effects
@subheading 14-0 Set filter   [not implemented in tracker]
Change the state of the Amiga low-pass filter, @xref{Amiga audio hardware}.

@node Fine portamento up, Fine portamento down, Set filter, Protracker extended effects
@subheading 14-1 Fine portamento up
Like @ref{Portamento up} except it occurs only on the 0th tick, this means at the
precise instant the command is interpreted, not later as for Portamento up.
The exact opposite of @ref{Fine portamento down}.

Scrolling mode:
@example
   1 A-4 sth-15
@end example

@node Fine portamento down, Glissando control, Fine portamento up, Protracker extended effects
@subheading 14-2 Fine portamento down
Like @ref{Portamento down} except it occurs only on the 0th tick, this means at the
precise instant the command is interpreted, not later as for Portamento down.
The exact opposite of @ref{Fine portamento up}.

Scrolling mode:
@example
   1 A-4 sth+15
@end example

@node Glissando control, Set vibrato waveform, Fine portamento down, Protracker extended effects
@subheading 14-3 Glissando control 
Set funk glissando if para is not null. Clear funk glissando if para is null.
While funk glissando is null @ref{Tone portamento}s will round each pitch value
to the nearest entire note.

Scrolling mode:
@example
   1 A-4 gls on
	1 A-4 gls off
@end example

@node Set vibrato waveform, Set finetune, Glissando control, Protracker extended effects
@subheading 14-4 Set vibrato waveform 
Acceptable range is 0-3: 0 is the default sine, 1 the square, and 2 the
rampdown. Protracker docs speak of 3 being a random waveform, but I've
yet to see it implemented ! Neither pt1-1, pt1-2 nor pt2-0 implement it.
You're supposed to add 4 to control whether the viboffset is reset at 
each note (if 4, not reset, but this looks buggy as hell to me@dots{})
@xref{Vibrato}, for the waveforms used.

Scrolling mode:
@example
   1 A-4 vb mode
@end example
with @code{mode} being one of @code{sine, sqre, ramp} or
@code{SINE, SQRE, RAMP} if the viboffset should not be reset.

@node Set finetune, Loop pattern, Set vibrato waveform, Protracker extended effects
@subheading 14-5 Set finetune
Set finetune for the current channel to the given para right away, instead of 
the current sample finetune (@pxref{Protracker finetunes}).

Scrolling mode:
@example
   1 A-4 fine 15
@end example
where the parameter is between 0 and 15.

@node Loop pattern, Set tremolo waveform, Set finetune, Protracker extended effects
@subheading 14-6 Loop pattern
if para is null, set start of loop to remember, 
else loop to loop start para+1 times before playing on.

This effect is channel-dependent, so you can use several channels and 
interleave loops@dots{} 

Scrolling mode:
@example
   1 A-4 SETLOOP
@end example
at the beginning,
@example
   1 A-4 LOOP 10
@end example
for looping 10 times.

@node Set tremolo waveform, Retrig note, Loop pattern, Protracker extended effects
@subheading 14-7 Set tremolo waveform 
Like @ref{Set vibrato waveform}, except it applies to @ref{Tremolo}.

Scrolling mode:
@example
   1 A-4 tr mode
@end example
with @code{mode} being one of @code{sine, sqre, ramp} or
@code{SINE, SQRE, RAMP} if the viboffset should not be reset.


@node Retrig note, Fine volume slide up, Set tremolo waveform, Protracker extended effects
@subheading 14-9 Retrig note
Retrig note on para-th, 2para-th,@dots{} tick.

Scrolling mode:
@example
   1 A-4 rtg 3
@end example

@node Fine volume slide up, Fine volume slide down, Retrig note, Protracker extended effects
@subheading 14-10 Fine volume slide up
Like @ref{Slide volume} up, except it occurs only once on the 0th tick

Scrolling mode:
@example
   1 A-4   ++5
@end example

@node Fine volume slide down, Cut note, Fine volume slide up, Protracker extended effects
@subheading 14-11 Fine volume slide down
Like @ref{Slide volume} down, except it occurs only once on the 0th tick

Scrolling mode:
@example
   1 A-4   --5
@end example

@node Cut note, Delay note, Fine volume slide down, Protracker extended effects
@subheading 14-12 Cut note
Set volume of current note to 0 on para-th tick.
@emph{Note that this does cut the sound, but the note continues playing}.

Scrolling mode:
@example
   1 A-4 cut 3
@end example

@node Delay note, Delay pattern, Cut note, Protracker extended effects
@subheading 14-13 Delay note
Start note on para-th tick instead of now.

Scrolling mode:
@example
   1 A-4 late 3
@end example

@node Delay pattern, Invert loop, Delay note, Protracker extended effects
@subheading 14-14 Delay pattern
Wait for para times t1 ticks before processing new entries.
Note that effects do proceed as usual, except that they @emph{don't}
occur once every speed-th tick (the event change is inhibited).
Delay pattern is a global effect.

Scrolling mode:
@example
   1 A-4 DLAY 3
@end example


@node Invert loop, Set tempo, Delay pattern, Protracker extended effects
@subheading 14-15 Invert loop 
See code for that weird effect.

Scrolling mode:
@example
   1 A-4 inv 3
	1 A-4 inv off
@end example

