                      Soundtracker pro II file format
                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

I haven't planned to write a converter from pro2-mods to protracker-
or MED-mods any time soon, so I decided to document and release
the pro2-fileformat, hoping that someone will do it for me. ;)
If you do, I would't mind if send me a copy.

Soundtracker pro II files exist in three versions, 0, 1 and 2.
Since the first official release (2.0) of pro2, only the version 2
fileformat has been used for saving.
You might encounter a version 0 or 1 song written by one of the
betatesters. The fileformats are very much the same, it is not
hard to make a loader for all of them.

In a mixture of pseudo-C/assembler/pro2-script, the file formats are as
follows:

dc.l    'STP3'          ; an identifier not easily impersonated
dc.w    version         ; only versions 0, 1 and 2 supported
dc.b    songlength      ; number of valid entries in pattern sequence
dc.b    patternlength   ; default length of patterns in lines. In version 0 this
                        ; is also the actual patternlengt for all pattern.
ds.b    128             ; 128 bytes pattern sequence, only <songlength> are valid
dc.w    delay           ; delay
dc.w    delayfraction   ; delay fraction. 0,1,2,3 for 0, .25, .5 and .75
dc.w    count           ; cia count
dc.w    songflags       ; see below
ds.l    1               ; reserved, should be zero
dc.w    midi            ; number of MIDI bytes to follow (50)
ds.b    midi            ; the MIDI settings

dc.w    x               ; number of samples to follow
dc.w    y               ; length of each sample structure, must be even
			; for version 0 and 1 this structure is 82 bytes in size
			; version 2 has this word set to 4
repeat x
  if(version <= 1)
  {
    dc.w  samplenumber
    ds.b  y               ; standard sample structure, see below
  }
  else
  {
    dc.w samplenumber
    dc.l structsize
    ds.b structsize-2
  }
  if (version>=1)
  {
    dc.w  numloops      ; number of loops in the sequence, use 0 for non-seqs
    ds.l  2*numloops    ; loops: repstart,replen
  }
endrep

if(version==0)
{
  dc.w  x               ; number of patterns
  repeat x
    ds.b  patternlength*16
  endrep
}
else
{
 { /* continue until patternnumber = -1 */
   dc.w  patternnumber
   dc.w  patternlength  ; in lines
   dc.w  patternwidth   ; in tracks
   ds.l  patternlength*patternwidth
 }
 { /* loop until scriptnumber = -1*/
   dc.w  scriptnumber
   dc.w  status          ; compiled/uncompiled = compiled/text
   dc.l  length
   ds.b  length
 }

  ds.b  17              ; drumpad sample numbers
  ds.b  17              ; drumpad note numbers
}

if (!EOF)
{
   ds.b   total sample length  ; sampledata
}

NOTE: - the absence of scripts or the absence of patterns is signalled by
        giving -1 as the first script- or patternnumber (version 1 and up)
      - Currently the patternwidth must be 4.

*---------------------------------------------------------------------

sample structure version 0 and 1:
        ds.b    30		pathname, 30 chars max
        dc.b    0		zero termination, in case all 30 chars were used
        dc.b    sampleflags	flags, see below
        ds.b    30		filename
        dc.l    samplelength	in bytes
        dc.b    volume		0-$40
        ds.b    1		reserved, set to zero
        dc.l    repeat offset	in bytes
        dc.l    repeat length	in bytes, 0 for no repeat
        dc.w    default command
        ds.b    4		4 reserved bytes, set to 0

sample structure version 2:
        ds.b    N		pathname, zero terminated, 256 chars max
        dc.b    sampleflags	flags, see below
        ds.b    M		filename, zero terminated, 30 chars max
        even    		pad to even boundary
        dc.l    samplelength	in bytes
        dc.b    volume		0-$40
        ds.b    1		reserved, set to 0
        dc.l    repeat offset	in bytes
        dc.l    repeat length	in bytes, use 0 for no repeat (PT uses 2)
        dc.w    default command
        dc.w    default period
        dc.b    finetune	-16 to +15
        ds.b    1		reserved, set to 0
	

A sample must not have a nonzero repeatstart and zero repeatlength, unless
it contains a sequence!!!!!!!!

*---------------------------------------------------------------------

patterns contain notes, one longword per note, like this:
track0note0  track1note0  track2note0  track3note0
track0note1  track1note1  track2note1  track3note1
track0note2  track1note2  track2note2  track3note2
etc...

The longwords are as follows:

        'note'-word                     'info'-word
        0000 0000  0000 0000            0000 0000  0000 0000
        \       /  \       /
         \     /    \     /             high byte:
          \   /      \   /              command #
           \ /        \ /                          low byte:
          sample #    key # (MIDI)                 command parameter
                                      (some commands use the low 3 nibbles
                                       as command parameter)

MIDI keynumbers start at 24 decimal for note C-1 and are incremented by one
for each higher note.

*---------------------------------------------------------------------

songflags: (filter+clockmode indicator)

       bits:      ......ed a.b...c.
                     a: 1=par in slow
                     b: 1=use cnt clock,0=use 02 clock
                     c: 1= filter on
                     d: 1=par out
                     e: 1=par out slow
All other bits are reserved and should be set to zero

sampleflags:
       bits:	c... .ur.
                  c: 1= chipram preferred for this sample
                  u: 1=upsample for notes A#3, B-3, A#4 and B-4
		  r: 1=load right channel of stereo sample
                     0=load left channel of stereo sample
                     (only for songs, since mods have the
                      correct sample embedded)
All other bits are reserved and should be set to zero

*---------------------------------------------------------------------
