~amaurycarvalho/midi2pt3/trunk

How to decode a Vortex Tracker II "PT3" File

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	by Vince "Deater" Weaver, <vince@deater.net>

	http://www.deater.net/weave/vmwprod/pt3_player/

	10 September 2019

Background:

~~~~~~~~~~~

	Vortex Tracker II ( https://bulba.untergrund.net/vortex_e.htm )

	is a music tracker (tool for writing music) that targets systems

	with the AY-3-8910 sound chip.  The music made is most popular

	on various ZX Spectrum (z80) and Atari ST systems.

	I wanted to make a decoder for a 6502-based Apple II with a

	AY-3-8910 based Mockingboard sound card.  The challenge was

	all the low-level Vortex Tracker documentation is in Russian,

	and the source code available is either uncommented z80 assembly

	language or Russian-commented Pascal source code.

	This document is based at least partly on the writeup here:

		http://karoshi.auic.es/index.php?topic=397.msg4641#msg4641

	as well as the AY_emul source code, and lastly just from reverse

	engineering things while trying to get my code to match the output

	of AY_emul exactly.

The PT3 Format

~~~~~~~~~~~~~~

* File Header

	Note: 16-bit values are little-endian

	Offset    : Size     : Description  : Contents

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

	$00 - $0C : 13 bytes : Magic        : "ProTracker 3."

	$0D       :  1 byte  : Version      : '5' for Vortex Tracker II

	$0E - $1D : 16 bytes : String       : " compilation of "

	$1E - $3E : 32 bytes : Name         : Name of the module

	$3E - $41 :  4 bytes : String       : " by "

	$42 - $62 : 32 bytes : Author       : Author of the module.

	$63       :  1 byte  : Frequency table (from 0 to 3)

	$64       :  1 byte  : Speed/Delay

	$65       :  1 byte  : Number of patterns+1  (Max Patterns)

	$66       :  1 byte  : LPosPtr      : Pattern Loop Pointer

	$67 - $68 :  2 bytes : PatsPtrs     : Pointers to the patterns

	$69 - $A8 : 64 bytes : SamPtrs[32]  : Pointers to the samples

	$A9 - $C8 : 32 bytes : OrnPtrs[16]  : Pointers to the ornaments

	$C9 - ??? :          : Patterns[]   : $FF terminated, More on this below

	Version: is at offset $0D, which is just the ASCII value of

		the version number from the magic.  Usually you

		subtract off '0' to get the proper value.

		If the value is not a valid number, '6' is assumed.

* Pattern list

	The pattern list starts at $C9 and is terminated by $FF

	The pattern is multiplied by 3.

	A sample pattern list might look like

		$03, $06, $09, $FF

	which corresponds to playing in order patterns

		1, 2, 3

* Samples

	The pt3 file allows for 32 samples.  These samples contain

	values that are applied to the music notes as they are playing.

	The 16-bit address of a sample X can be found by getting the

		16-bit little-endian address at offsets

		$6A+(X*2) and $6B+(X*2) in the header.

	Byte 0:	 LOOP VALUE -- sample offset to return to once hit the end

	Byte 1:  LENGTH     -- number of 32-bit sample values

	Byte 2+: VALUES     -- list of 4-byte (32-bit samples)

	* Sample format

		+ Byte 0 --- 7 6 5 4321 0

				Bit 7 - Amplitude sliding

				Bit 6 - 1/0 amplitude slide up/down

				Bit 5 - 1/0 envelope slide up/down

				Bits 4321 - sign extend, envelope slide value

				Bit 0 - Sample has envelope

		+ Byte 1 --- 7 6 5 4 3210

				Bit 7     - Envelope sliding

				Bit 6     - Accumulate Tone

				Bit 5     - parameter to envelope sliding?

				Bit 4     - Bit 6+4 used to set Noise/Channel

					    mixer value

				Bits 3210 - Amplitude

		+ Byte 2 --- Freq Low -\

		+ Byte 3 --- Freq High----- Used as base tone

* Ornaments

	The PT3 file format has 16 ornaments, which are patterns applied

	to the note.  This can be used for ?? effects.

	The 16-bit address of an ornament X can be found by getting the

		16-bit little-endian address at offsets

		$A9+(X*2) and $AA+(X*2) in the header.

	Byte 0:	 LOOP VALUE -- ornament offset to return to once hit the end

	Byte 1:  LENGTH     -- number of ornament values

	Byte 2+: VALUES     -- list of single-byte values applied to the notes

* Pattern data

	For each of three channels (A,B,C) there is a nul-terminated

	stream of bytes that gives the pattern data.

	To find the pattern data for a pattern, look it up in 

	A 6-byte chunk with the 16-bit addresses for A,B,C for pattern

	X can be found by

		a_addr_l = [address in ($68/$67)] + (X*6)+0

		a_addr_h = [address in ($68/$67)] + (X*6)+1

		b_addr_l = [address in ($68/$67)] + (X*6)+2

		b_addr_h = [address in ($68/$67)] + (X*6)+3

		c_addr_l = [address in ($68/$67)] + (X*6)+4

		c_addr_h = [address in ($68/$67)] + (X*6)+5

	Follow that address to find the nul-terminated pattern data.

	The data can be interpreted this way:

	+ $00         - NUL termination, end of pattern

	+ $01-$0f     - effects, see later.

			Note that parameters to the effect appear in the

			bytestream *after* the note to play

	+ $10-$1f     - set envelope type

			+ $10 means disable envelope

				- sample number is next byte

			+ $11-$1F 

				- envelope type is bottom 4 bits

				- envelope period is next 2 bytes (big endian)

				- envelope delay is next 1 byte

				- sample number is next byte

	+ $20-$3f     - set noise

				- Noise set to the ($20...$3F) value - $20

	+ $40-$4f     - set ornament

				- ornament sent to bottom 4 bits

				- possibly setting 0 counts as disabling

	+ $50-$af     - play note

                0   1   2   3   4   5   6   7   8   9   a   b   c   d   e   f

          50: C-1 C#1 D-1 D#1 E-1 F-1 F#1 G-1 G#1 A-1 A#1 B-1 C-2 C#2 D-2 D#2

          60: E-2 F-2 F#2 G-2 G#2 A-2 A#2 B-2 C-3 C#3 D-3 D#3 E-3 F-3 F#3 G-3

          70: G#3 A-3 A#3 B-3 C-4 C#4 D-4 D#4 E-4 F-2 F#4 G-4 G#4 A-4 A#4 B-4

          80: C-5 C#5 D-5 D#5 E-5 F-5 F#5 G-5 G#5 A-5 A#5 B-5 C-6 C#6 D-6 D#6

          90: E-6 F-6 F#6 G-6 G#6 A-6 A#6 B-6 C-7 C#7 D-7 D#7 E-7 F-7 F#7 G-7

          a0: G#7 A-7 A#7 B-7 C-8 C#8 D-8 D#8 E-8 F-8 F#8 G-8 G#8 A-8 A#8 B-8

	+ $b0         - disable envelope, reset ornament position

	+ $b1         - set skip value

				- next byte is how many lines to skip for

				  this note

	+ $b2-$bf     - set envelope

				- envelope type to (bottom 4 bits - 1)

				- envelope period next 2 bytes (big endian)

	+ $c0         - turn off note (volume=0 and disable everything)

	+ $c1-$cf     - set volume

				- volume set to bottom 4 bits

	+ $d0         - done processing this note (end note)

	+ $d1-$ef     - set sample

				- sample set to value-$d0.

	+ f0-$ff      - initialize ornament/sample.  Envelope is disabled

				- ornament is bottom 4 bits

				- next byte is sample*2

	Note when parsing if you reach a note, a $D0 or a $C0 then you

	are done parsing the note for this line and should move on

	to parsing the effects.

	Effects

	~~~~~~~

	AY_emul supports having up to one of each effect for each line, and

	tracks the order in which to apply them.  However in the wild

	I have not seen more than one effect applied per line/channel

	(I don't think Vortex Tracker lets you add multiple?)

	The bytes for the effects follow after the byte that ended the note.

	The effect value on disk is not the same as that displayed when

	viewed in the tracker.

	On	In

	Disk  Tracker

	~~~~  ~~~~~~~

	$01     $01:	Glissando (slide through discrete notes) / Tone Down

			First byte: delay

			Next 2 bytes: frequency to add (is negative)

	$01     $02:	Glissando (slide) / Tone Up

			This appears differently in tracker, but is just

			the same as above but with a positive frequency.

	$02     $03:	Tone portamento (continuous slide)

			First byte: delay

			Next 2 bytes: ignored?

			Next 2 bytes: slide step (little-endian)

	$03     $04:	Sample Offset

			First byte: value to set the sample position offset

	$04     $05:	Ornament offset

			First byte: value to set the ornament offset

	$05     $06:	Vibrato

			Periodic sound off/on in that channel

			First byte: OffOn delay (frames to stay off)

			Second byte: OnOff delay (frames to stay on)

	$08	$09:	Envelope Glissando -- Frequency decreasing

			First byte: delay

			Next two bytes: Slide add (little-endian)

	$08     $0A:	Envelope Glissando -- Frequency increasing.

			Like previous but with sign switched?

	$09	$0B:	Set playing speed (new Delay).

			First byte: new delay (global number of frames per line)

* Frequency Tables

	Various versions of the tracker use different frequency tables.

	Players lookup notes in these tables to get the proper frequency.

	The value in the frequency table field specifies up to 4 (0...3)

	tables, but there is an alternate set of tables if the tracker version

	PT3_VERSION is 3 or less.

	Presumably for space reasons, some players only support tables 

	one and two from the newer set.

	These tables in theory can be calculated at runtime, but usually

	they aren't unless you are extremely space constrained.

	The z80 player has code to do this in z80 assembly.

	The tables are a set of 96 16-bit values (8 octaves of 12 notes)

	The frequency tables supported by Ay_Emul:

		PT3Version#	Table#		Frequency Table

		-----------	------		======================

		<=3.3		0		PT3NoteTable_PT_33_34r

		all		1		PT3NoteTable_ST

		<=3.3		2		PT3NoteTable_ASM_34r

		<=3.3		3		PT3NoteTable_REAL_34r

		3.4+		0		PT3NoteTable_PT_34_35

		all		1		PT3NoteTable_ST

		3.4+		2		PT3NoteTable_ASM_34_35

		3.4+		3		PT3NoteTable_REAL_34_35

* Volume Tables

	There are multiple 256-byte amplitude/volume lookup tables

	These seem to have changed with different versions of Vortex Tracker

	so to be complete you need to contain them all and use the proper

	one at run time

* Corner cases seen in the wild:

	+ What to do if the delay on an effect is set to zero?

* 6-channel PT3 Files

	In the Protracker 3.7 format you can look for a turbosound header

	at the very end of the file.

	Type1 (4 bytes), Size (16-bits, little-endian)

	Type2 (4 bytes), Size (16-bits, little endian)

	TSID: (4 bytes) 02TS

	If the type of these files is PT3! then these are describing

	PT3 subfiles, and can be read as two 3-channel files which can

	be interpreted together as one 6-channel file.

============================================================================

Example 1*

So if we have this in the module: $D2,$CF,$B1,$05,$50 we will have this in the

tracker:

C-1     2..F   ....

---     ....    ....

---     ....    ....

---     ....    ....

---     ....    ....

$D2: Sample 2    ($Dx samples)

$CF: Volume 15   ($Cx volume)

$B1: No envelope ($Bx envelope)

$05,$50: Play note $50 (C1) during five tracker lines.

*Example 2*

If we have this in the module: $D1,$CE,$09,$B1,$08,$50,$07

$D1: Sample 1.

$CE: Volume 14.

$09: New delay will be set. See after note is set.

$B1: No envelope.

$08,$50: Play note $50 (C1) during eight tracker lines.

$07: New Delay.