GoatTracker v2.15
-----------------

Editor by Lasse rni (loorni@gmail.com)
Uses reSID engine by Dag Lem and SDL library.
GoatTracker icon by Antonio Vera.

Distributed under GNU General Public License
(see the file COPYING for details)

Covert BitOps homepage:
http://covertbitops.c64.org


Table of contents
-----------------

1. General information
1.1 Warnings
1.2 Compatibility with v1.xx

2. Using GoatTracker
2.1 Command line options
2.2 Keyboard commands
2.2.1 General keys
2.2.2 Pattern edit mode
2.2.2.1 Protracker note-entry mode
2.2.2.2 DMC note-entry mode
2.2.3 Song edit mode
2.2.4 Instrument edit mode
2.2.5 Table edit mode
2.2.6 Songname edit mode

3. Song data
3.1 Orderlist data
3.2 Pattern data
3.3 Instrument data
3.4 Table data
3.4.1 Wavetable
3.4.2 Pulsetable
3.4.3 Filtertable
3.5 Playback details
3.6 Miscellaneous tips
3.7 Multispeed tips

4. Using the included utilities
4.1 INS2SND2.EXE
4.2 SNGSPLI2.EXE
4.3 MOD2SNG.EXE
4.4 BETACONV.EXE

5. Using the songs outside the editor
5.1 Playroutines 1 & 2: Standard
5.2 Playroutine 3: Gamemusic
5.3 Playroutine 4: Under-IO gamemusic
5.4 Playroutine 5: Minimal

6. File/data formats description
6.1 GoatTracker v2 song (.SNG) format
6.1.1 Song header
6.1.2 Song orderlists
6.1.3 Instruments
6.1.4 Tables
6.1.5 Patterns header
6.1.6 Patterns
6.2 GoatTracker v2 instrument (.INS) format
6.3 Sound effect data format

7. Recompiling

8. Version history


1. General information
----------------------

This program is a tracker-like C64 music editor running on Win32 or Linux
platforms (using the SDL library, see http://www.libsdl.org)

GoatTracker v2 adds more commands and uniform step programming tables for
waveform/arpeggio, pulse effects, and filter effects. It is likely much more
complex to learn & master than v1.xx.

Familiarity with tracker programs in general, hexadecimal notation, and the
C64's SID chip are required. Consult the C64 Programmer's Reference Guide
(http://project64.c64.org) or AAY64 (http://www.the-dreams.de/aay.html) for
SID chip reference.

For filesize & library compatibility reasons, precompiled binaries exist only
for Win32 platform.

1.1 Warnings
------------

1. Always look at the end of this file for changes! Sometimes keyboard commands
   change etc.

2. Always save your songs in the .SNG-format with F11 key if you plan to
   continue editing! Packed & relocated songs (PRG/BIN/SID) can not be loaded
   back into the editor.

3. Even the reSID emulation is in some cases quite far from the output of a
   real SID. Especially if filters are in use, consider strongly testing your
   tune on a C64 or on a HardSID card. (Using filters has always been
   complicated because every SID tends to sound different.)

4. The editor will stop playing if:
   - The song restart position is illegal (beyond end of song)
   - The sequence of orderlist commands is incorrect
     * In a sequence of both TRANSPOSE & REPEAT, TRANSPOSE must come first
     * The last thing before a RST-endmark should be a pattern number
   - Gateoff timer value is too high compared to song tempo.
   These are not valid ways to create an oneshot song, as it will lead to
   bugged playback once you pack/relocate the song. Create instead one empty
   pattern and loop to it if you want the song to end.

5. Using delayed wavetable or no wavechange (0x 00, where x is 0-7) in the
   first step of instrument wavetable is unsupported and may result in missing
   notes.

6. Results will be undefined if you jump directly onto a table row containing
   a jump (FF xx), either with instrument pointers or 8XY, 9XY, AXY commands.

7. When using a playroutine with unbuffered SID-writes (Standard /w unbuffered
   or Minimal) and encountering ADSR-bugs after packing/relocating, you can try
   either:
   1) Set pulse-startpos to nonzero value in the troublesome instruments and
      change the HardRes/1stWave parameter of some instrument slightly, for
      example from $09 to $0B, to disable a playroutine optimization. The
      idea in this is to make the noteinit routine take more CPU cycles.
   2) Use a playroutine with buffered writes to pack/relocate.

1.2 Compatibility with v1.xx
----------------------------

GoatTracker v2 can load v1.xx songs and instruments, but it saves only in v2
format. Some subtleties (like tricks involving instrument changes) will not
play back exactly like in v1.xx.

The only major feature removal is that of the arpeggio command in v2.
Everything that this command does can also be done with wavetables, and the
import feature converts all arpeggio commands to corresponding wavetable
programs.


2. Using GoatTracker
--------------------

2.1 Command line options
------------------------

Start Goattracker V2 by typing GOATTRK2 in the command prompt, followed by the
songname to be loaded at startup (optional) and any command line options you
may want. For example "goattrk2 dojo.sng /s1 /e1" to set 1x-speed mode and SID
model 8580 and to load "dojo.sng" on startup.

/Axx Set hard restart ADSR parameter in hex. DEFAULT=0F00
/Bxx Set sound buffer length in milliseconds DEFAULT=100
/Cxx Use CatWeasel MK3 PCI SID (0 = off, 1 = on)
/Dxx Pattern row display (0 = decimal, 1 = hexadecimal)
/Exx Set emulated SID model (0 = 6581 1 = 8580) DEFAULT=6581
/Hxx Use HardSID (0 = off, 1 = HardSID ID0 2 = HardSID ID1 etc.)
/Ixx Set reSID interpolation (0 = off, 1 = on) DEFAULT=off
/Kxx Note-entry mode (0 = PROTRACKER 1 = DMC) DEFAULT=PROTRK.
/Lxx SID memory location in hex. DEFAULT=D400
/Mxx Set sound mixing rate DEFAULT=44100
/Sxx Set speed multiplier (0 for 25Hz, 1 for 1x, 2 for 2x etc.)
/Vxx Set finevibrato-mode (0 = off, 1 = 1x-speed only, 2 = on) DEFAULT=1
/N   Use NTSC timing
/P   Use PAL timing (DEFAULT)
/W   Write emulated sound output to a file SIDAUDIO.RAW
/?   Show command line options

Try the command line options if there are any problems. For example, if you
experience choppy audio you can increase audio buffering with /B option. SDL
seems to have trouble with some soundcards under Windows; you might want to
try even a 500ms buffer, or tweak the hardware acceleration level of the
soundcard (from Control Panel). Also, reSID interpolation will take remarkably
more CPU time and could cause the sound and/or editing to get choppy.

HardSID support is available with the /H option (use first HardSID = /H1,
second = /H2 etc., return to emulated output = /H0). You must have the HardSID
drivers installed to use this feature.

CatWeasel MK3 PCI SID support is available with /C option (/C1 to turn on).

To use the PC64 cable, you need Daniel Illgen's HardSID-DLL-Clone. Available at
http://da-work.tailbit.de/

Remember to restore normal operation with /S1 when you are finished working
with multispeed-tunes. Multispeeds higher than 2x do not seem to work too well
with the HardSID, because the operating system timers' granularity comes into
play. With emulated output this problem does not exist, as the timing is based
on sound buffer sizes.

Finevibrato mode is on by default, when speed multiplier is below 2x, and off
by default at 2x and above. You can change this behaviour with /V option.

The hard restart ADSR parameter will especially affect how rapid passages of
notes will sound like. 0000 is probably too hard to be useful, except perhaps
with gateoff timer value 1. 0F00 (default) is a lot softer, and 0F01 adds also
a little bit of release to the gateoff phase for even softer sound.

2.2 Keyboard commands
---------------------

This program is entirely operated on keyboard. For a list of keyboard commands
press F12 (online help) in the tracker or see the table below:

NOTE: SHIFT & CTRL are interchangeable in the commands. You can also use [ ]
or ( ) instead of < >.

2.2.1 General keys
------------------

TAB       Cycle between editing modes (forwards)
SHIFT+TAB Cycle between editing modes (backwards)
F1        Play from beginning
F2        Play from current pos.
F3        Play one pattern from current pos.
F4        Stop playing & silence all sounds
SHIFT+F1  Play from beginning /w follow play
SHIFT+F2  Play from current pos. /w follow play
SHIFT+F3  Play one pattern from current pos. /w follow play
SHIFT+F4  Mute current channel
F5        Go to pattern editor
F6        Go to song editor
F7        Go to instrument/table editor
F8        Go to songname editor
F9        Pack, relocate & save PRG,SID etc.
F10       Load song (Pattern/Song/Songname mode) or instrument (Instrument mode)
F11       Save song (Pattern/Song/Songname mode) or instrument (Instrument mode)
F12       Online help screen
INS       Insert row (Press INS/DEL on endmark to change pattern length)
DEL       Delete row
SHIFT+ESC Clear musicdata & set default pattern length
ESC       Exit program

2.2.2 Pattern edit mode
-----------------------

- +         Select instrument
/ *         Select octave
< >         Select pattern
0-9 & A-F   Enter parameters
SPACE       Switch between jam/editmode
RETURN      (also CAPSLOCK) Insert keyoff
            Enter table (when cursor is over a wave, pulse or filter command)
SHIFT+RET.  Insert keyon
BACKSPACE   Insert rest
SHIFT+BKSP. Insert rest and clear effects
SHIFT+Q     Transpose halfstep up
SHIFT+A     Transpose halfstep down
SHIFT+W     Transpose octave up
SHIFT+S     Transpose octave down
SHIFT+I     Invert selection / whole pattern if no selection
SHIFT+CRSR UP,DOWN Mark pattern
SHIFT+CRSR LEFT,RIGHT Select pattern
SHIFT+L     Mark/unmark entire pattern
SHIFT+M,N   Choose highlighting step size
SHIFT+X,C,V Cut,copy,paste pattern
SHIFT+E,R   Copy,paste effects
SHIFT+Z     Cycle autoadvance-mode

There are 2 modes for note entering:

2.2.2.1 Protracker note-entry mode
----------------------------------

This is the default or activated with command line option /K0. There are two
rows of a piano keyboard:

  Lower octave     Higher octave
 S D  G H  K L    2 3  5 6 7  9 0
Z X CV B NM , .  Q W ER T Y UI O P

Octave (0-7) is selected with / and * keys on the numeric keypad.

In this mode there are 2 different autoadvance-modes (the mode can be seen from
the color of the jam/editmode indicator)

GREEN - Advance when entering notes & command-databytes
RED - Do not advance automatically

2.2.2.2 DMC note-entry mode
---------------------------

Activated with command line option /K1, there is one row of piano keyboard

 W E  T Y U  O P
A S DF G H JK L

and octave of a note (sets default octave at the same time) is changed with
number keys 0-7.

In this mode there are 3 different autoadvance-modes:

GREEN - Advance when entering notes, octaves or command-databytes
YELLOW - Advance when entering notes or command-databytes, not octaves
RED - Do not advance automatically

2.2.3 Song edit mode
--------------------

< >         Select subtune
- +         Insert Transpose down/up command (shown as -/+ in the orderlist)
0-9 & A-F   Enter pattern numbers
SPACE       Set start position for F2 key
RETURN      Go to pattern
SHIFT+R     Insert Repeat command (shown as "R" in the order-list)
SHIFT+1,2,3 Swap current channel orderlist with channel 1,2,3
SHIFT+X,C,V Cut,copy,paste channel orderlist
SHIFT+SPACE Set start position on all channels
SHIFT+RET.  Go to pattern on all channels

2.2.4 Instrument edit mode
--------------------------

- +         Select instrument
/ *         Select octave
F7          Go to table editor
0-9 & A-F   Enter parameters
SPACE       Play test note
SHIFT+SPACE Silence test note
RETURN      Go to table position indicated by wave/pulse/filterpos.
SHIFT+X,C,V Cut,copy,paste instrument
SHIFT+S     Smart paste an instrument
SHIFT+N     Edit instrument name
SHIFT+DEL   (also SHIFT+BACKSPACE) Delete instrument & tabledata

The test note will be played on the channel you last were on in the pattern
editor. To hear filtering as intended, be sure to play it on a channel that has
been selected for filtering in the filter parameters.

Note that cut,copy,paste instrument do not touch the tabledata, just for the
case you need it in another instrument. If you want to completely get rid of
an instrument + its associated tabledata, press SHIFT+DEL.

If wave/filter/pulsepos. is 00 and you press RETURN over it, you will move to
the first free location in the corresponding table. If you press SHIFT+RETURN,
also the instrument parameter will be set accordingly.

"Smart paste" will convert instrument numbers in all patterns if you "move" an
instrument by cut/pasting it.

2.2.5 Table edit mode
---------------------

- +         Select instrument
/ *         Select octave
F7          Go to instrument editor
0-9 & A-F   Enter parameters
SPACE       Play test note
SHIFT+SPACE Silence test note
RETURN      Go back to wave/pulse/filterpos. parameter
SHIFT+L     Convert <limit,speed> modulation step to <time,speed>
SHIFT+N     Negate speed parameter in pulse or filtertable

If you need to insert rows in the beginning of an instrument's wave/pulse/
filtertable, press SHIFT+INS instead of just INS: this way table pointers
pointing to the table first row will not move.

For easier programming of negative modulation speeds in pulse/filtertables, you
can first enter a positive speed positive value ($00-$7F) and then press
SHIFT+N to negate it.

Alternatively, you can enter pulse/filter modulation steps in limit-based
format, and convert them to time-based with SHIFT+L. For example, you could
enter the following in the pulsetable,

  01: 84 00 Set initial pulse to $400
  02: C0 10 Modulate pulse to $C00 with speed $0010*2
  03: 40 10 Modulate pulse back to $400 with speed $0010*2

position the cursor on step 02 and press SHIFT+L twice, to convert both of the
modulation steps. If necessary, the steps will be expanded to several if the
resulting time parameter is over 127.

Remember that the player only understands time-based steps and you always have
to convert limit-based steps before they play correctly!

2.2.6 Songname edit mode
------------------------

Use cursor UP/DOWN to move between song, author & copyright strings, and
other keys to edit them.


3. Song data
------------

3.1 Orderlist data
------------------

A song can consist of up to 32 subtunes. For each subtune's each channel, there
is an orderlist which determines in what order patterns are to be played. In
addition to pattern numbers, there can be TRANSPOSE & REPEAT commands and
finally there is a RST (RESTART) endmark followed by restart position. The
maximum length of an orderlist is 254 pattern numbers/commands + the endmark.

TRANSPOSE is measured in halftones. Transpose up (shown as +X) can be 0-14
halftones and transpose down (shown as -X) can be 1-15. Transpose is
automatically reset only when starting the song, not when looping.

A REPEAT command (shown as RX) will repeat the pattern following it 1-16 times.
"Repeat 16 times" is displayed as R0.

There are some rules for orderlist command order:

- If there are both TRANSPOSE and REPEAT commands before a pattern number,
  TRANSPOSE must come first.

- The last thing before the RST-endmark must be a pattern number. If you need
  to reset transpose on song repeat, do it in the beginning of the repeat loop.

In case of wrong order, the editor will halt playback. This tells that the
resulting packed/relocated song would play incorrectly.

3.2 Pattern data
----------------

Patterns are single-channel only for flexibility & low memory use. They contain
the actual notes, instrument changes & sound commands. A pattern can have
variable length, up to 96 rows. There can be 208 different patterns in a song.

The explanation of a pattern row:

 Note name
 |
 | Octave
 | |
 | | Instrument number ($01 - $3F, or $00 for no change)
 | | |
 | | |  Command ($0 - $F)
 | | |  |
 | | |  | Databyte
 | | |  | |
 C-1 00 0 00

The highest note available in a pattern is G#7. To reach the top three notes
(A-7 to B-7), you can use transpose.

In place of a normal note, there can also be one of these special "notes":

 ... Rest
 --- Key off (clear gatebit mask)
 +++ Key on (set gatebit mask)

The actual state of the gatebit will be the gatebit mask ANDed with data from
the wavetable. A key on cannot set the gatebit if it was explicitly cleared
at the wavetable.

Commands 1XY-4XY and FXY bear some resemblance to Soundtracker/Protracker/
Fasttracker effects. However, they are different in some ways, so read their
descriptions! Note that there is no "databyte $00 uses the last databyte"-
action in the commands.

Command 0XY: Do nothing. Databyte will always be $00.

Command 1XY: Portamento up. Raise the pitch with XY * 4 each tick.

Command 2XY: Portamento down. Lower the pitch with XY * 4 each tick.

Command 3XY: Toneportamento. Raise or lower pitch until target note has been
             reached. Speed $00 achieves a "tie note" effect, otherwise pitch
             change on each tick is XY * 4.

Command 4XY: Vibrato. X determines how long until the direction changes (speed)
             and Y * 16 is the amount of pitch change on each tick (depth).
             When finevibrato mode is on, speed can only take values 0-7 and
             the highest bit ($80) gives intermediate vibrato depths when set.

Command 5XY: Set attack/decay register to value XY.

Command 6XY: Set sustain/release register to value XY.

Command 7XY: Set waveform register to value XY. If a wavetable is actively
             changing the channel's waveform at the same time, will be
             ineffective.

Command 8XY: Set wavetable pointer. $00 stops wavetable execution.

Command 9XY: Set pulsetable pointer. $00 stops pulsetable execution.

Command AXY: Set filtertable pointer. $00 stops filtertable execution.

Command BXY: Set filter control. X is resonance and Y is channel bitmask.
             $00 turns filter off and also stops filtertable execution.

Command CXY: Set filter cutoff to XY. Can be ineffective if the filtertable is
             active and also changing the cutoff.

Command DXY: Set mastervolume to Y, if X is $0. If X is not $0, value XY is
             copied to the timing mark location, which is playeraddress+$3F.

Command EXY: Funktempo. Will alternate between tempos X and Y on subsequent
             pattern steps. Sets the funktempo active on all channels, but you
             can use the next command to override this per-channel.

Command FXY: Set tempo. Values $03-$7F set tempo on all channels, values $83-
             $FF only on current channel (subtract $80 to get actual tempo).
             Tempos $00 and $01 recall the funktempos set by EXY command.

Master volume is by default the maximum ($F), but it is only reset when loading
a new song or clearing songdata in the editor, not every time playback starts.
If you change mastervolume, you have to reset it manually in the beginning of
your song.

If the command is not 1XY-4XY, instrument vibrato will be active.

Note that the one-shot commands 5XY-FXY allow the previous 1XY-4XY command or
instrument vibrato to continue "underneath" them. In section 3.7 (hints & tips)
there is an example of this.

3.3 Instrument data
-------------------

You can use up to 63 different instruments in a song. Each instrument is
defined by 9 parameters:

Attack/Decay          $0 is fastest attack or decay, $F is slowest

Sustain/Release       Sustain level $0 is silent and $F is the loudest. Release
                      behaves like Attack & Decay (F slowest).

Wavetable Ptr         Wavetable startposition. Value $00 stops the wavetable
                      execution and isn't very useful.

Pulsetable Ptr        Pulsetable startposition. Value $00 will leave pulse
                      execution untouched.

Filtertable Ptr       Filtertable startposition. Value $00 will leave filter
                      execution untouched. In most cases it makes sense to have
                      a filter-controlling instrument only on one channel at a
                      time.

Vibrato Delay         How many ticks until instrument vibrato starts. Value 00
                      turns instrument vibrato off.

Vibrato Speed/Depth   Instrument vibrato parameters. See command 4XY.

Gateoff Timer         How many ticks before note start gateoff+hard restart
                      happens. Can be at most tempo-2. So on tempo 4 highest
                      acceptable value is 2.

Hardres/1st Wave      Waveform used on init frame of the note, usually 9 (gate+
                      testbit). If the high bit is set (values $80-) hard
                      restart will be skipped. Values $00 & $80 enable
                      instrument legato.

In case of illegal (too high) gateoff timer values, the song playback is
stopped.

ADSR settings are crucial to getting any sound at all. If all of them are zero
just a very short "click" will be heard. Here's a diagram to help you visualize
the Attack, Decay, Sustain & Release phases.

     V      /\            |<- gatebit reset (key-off) at this point
     O     /  \           |
     L    /    \__________|
     U   /                |\
     M  /                 | \
     E /                  |  \
TIME ---------------------------->
         A   D      S       R

Some ADSR examples:

  A/D 09 Will produce a sound that starts from full volume right away and fades
  S/R 00 to silence automatically. By increasing the Decay value, the fade will
         last longer.

  A/D 00 A sound that goes very fast from full volume to sustain level 8.
  S/R 8A If you increase the Decay value, it will go to the sustain level
         slower. After key-off, starts fading out with speed A.

  A/D CC A sound that rises slowly to maximum volume, then decays slowly to the
  S/R AF sustain level A and after key-off, fades out to silence very slowly.

Instrument legato works as following: When Hardres/1st Wave parameter is $00 or
$80, no hard restart or gateoff/gateon will be performed. On the note
initialization frame, no 1st frame waveform will be set. However wave/pulse/
filterpointers and ADSR are initialized normally. You can also use this in
conjunction with command 8XY to set another wavetable pointer for the note.

It is advisable to stick to one gateoff timer value throughout all instruments.
Consider this: When the song begins, all channels are reset to instrument 1.
Assume that instrument 1 has gatetimer value 2. This means new notes are
fetched 2 ticks before note start. Now, if on the first row of the pattern,
there is an instrument change to an instrument having gateoff timer 1, the
new note fetch will happen immediately again on the next tick, and the playback
goes out of sync!

3.4 Table data
--------------

Tables control the execution of instruments' waveform/arpeggio changes, pulse
modulation, and filter modulation. All the tables are controlled by the left
side bytes, while the right side byte specifies additional parameters.

Note that you should never jump directly onto a table jump command (FF) either
with instrument parameters or pattern commands 8XY, 9XY, AXY. Otherwise,
results are undefined.

3.4.1 Wavetable
---------------

Wavetable left side:   00    Leave waveform unchanged
                       01-07 Delay this step by 1-7 frames
                       08-FE Waveform values. Kindly refer to C64
                             Programmer's Reference Guide or AAY64.
                       FF    Jump. Right side tells position ($00 = stop)

Wavetable right side:  00-5F Relative notes
                       80    Keep frequency unchanged
                       81-DF Absolute notes C#0 - B-7

Short explanation of waveform bitvalues:
01 = Gatebit. When on, initiates attack/decay/sustain phase. When off,
     initiates the release phase.
02 = Synchronize. Creates weird effects using output of another channel
04 = Ring modulation. Creates weird effects using output of another channel.
     Most effective with the triangle waveform.
08 = Testbit. Silences sound and resets the oscillator.
10 = Triangle waveform.
20 = Sawtooth waveform.
40 = Pulse waveform.
80 = Noise waveform.

All waveforms except noise can be combined (for example triangle+pulse), but
the effect will be different on 6581 and 8580 SID chips, so use caution.

The way how the channels work with synchronize/ringmod:
- When used on channel 1, channel 3's output modulates the sound.
- When used on channel 2, channel 1's output modulates the sound.
- When used on channel 3, channel 2's output modulates the sound.

Wavetable delay or no wavechange should not be used in the first step of
instrument wavetable. Otherwise, missing notes may be caused. On the other
hand, if you use 8XY command to jump into a wavetable program, those are
allowed.

Using wavetable delay or a wavetable step with no frequency change allows
continuous commands & instrument vibrato to be executed together with wave-
table. Be warned that this has the potential for large rastertime usage!

Some examples of wave tables (all examples start on table step 1)

  01: 21 00 Sawtooth waveform on note's original pitch.
  02: FF 00

  01: 41 00 A flute sound with pulse on the first tick and triangle on all
  02: 11 00 the rest.
  03: FF 00

  01: 41 01 A "koto" sound that is one halfstep higher on the first tick and
  02: 40 00 on original pitch the next. Gatebit is also cleared on the second
  03: FF 00 tick.

  01: 81 D0 A snaredrum sound, using all absolute notes so it doesn't depend on
  02: 41 AA which note it's played. Use pulsewidth 800 for best result.
  03: 41 A4
  04: 80 D4
  05: 80 D1
  06: FF 00

  01: 81 DF A pulse sound on original pitch, preceded with a short noise (like
  02: 41 00 a hi-hat or something) that has always an absolute pitch of B-7.
  03: FF 00

  01: 41 00 A 4-note looping arpeggio sound with pulse waveform. Note that
  02: 00 04 waveform doesn't change in the looping part.
  03: 00 07
  04: 00 0C
  05: 00 00
  06: FF 02

  01: 21 00 A delayed minor chord arpeggio with sawtooth waveform. Each step
  02: 02 03 takes 3 ticks.
  03: 02 07
  04: 02 00
  05: FF 02

  01: 41 00 Use pulse first, but then switch between pulse & triangle every 5
  02: 03 80 ticks while frequency remains unchanged (allowing for vibrato &
  03: 11 80 slides).
  04: 03 80
  05: 41 80
  06: FF 02

3.4.2 Pulsetable
----------------

Pulsetable left side:  01-7F Pulse modulation step. Left side indicates time
                             and right side the speed (signed 8-bit value).
                             Amount of pulse change each tick is speed*2.
                       8X-FX Set pulse width. X is the high 4 bits, right
                             side tells the 8 low bits.
                       FF    Jump. Right side tells position ($00 = stop)

Some examples of pulse tables (all examples start on table step 1)

  01: 88 00 Set pulse value $800 (middle)
  02: FF 00 Stop pulse execution

  01: 80 10 Set pulse value $010 (very thin)
  02: 20 40 For 32 ticks, increase pulse with speed $0040*2 (128)
  03: 40 E0 For 64 ticks, decrease pulse with speed $FFE0*2 (-64)
  04: 40 20 For 64 ticks, increase pulse with speed $0020*2 (64)
  05: FF 03 Jump back to step 03 for a nice loop

3.4.3 Filtertable
-----------------

Filtertable left side: 00    Set cutoff, indicated by right side
                       01-7F Filter modulation step. Left side indicates time
                             and right side the speed (signed 8-bit value)-
                       80-F0 Set filter parameters. Left side high nybble
                             tells the passband ($90 = lowpass, $A0 = bandpass
                             etc.) and right side tells resonance/channel
                             bitmask, as in command BXY.
                       FF    Jump. Right side tells position ($00 = stop)

If "Set filter parameters" is followed by "Set cutoff" directly below, both
will be executed on the same frame.

Some examples of filter tables (all examples start on table step 1)

  01: 90 F1 Set lowpass, resonance F, channel bitmask 1 (filter channel 1 only)
  02: 00 40 Set cutoff to $40
  03: FF 00 Stop filter execution

  01: 80 00 No passband selected, resonance 0, bitmask 0 (no filtered channels)
  02: FF 00 Stop filter execution

  01: A0 87 Set bandpass, resonance 8, channel bitmask 7 (filter all channels)
  02: 00 00 Set cutoff to $00
  03: 7F 01 Increase cutoff with speed $01 for 127 ticks
  04: 7F 01 Continue cutoff increase
  05: 7F FF Then decrease back to starting position (speed $FF = -1)...
  06: 7F FF
  07: FF 03 ...and loop back to step 03

  01: C0 F2 Set highpass, resonance F, channel bitmask 2 (filter channel 2)
  02: 00 F0 Set cutoff to $F0
  03: 90 F2 On the next frame, change to lowpass...
  04: 00 50 ...and set cutoff $50
  05: FF 00 Stop filter execution

Note that the second example could also be achieved simply with pattern command
B00 (set filter control, and stop filter execution, because parameter was $00)

3.5 Playback details
--------------------

Each pattern row is divided into as many 50Hz/60Hz "ticks" as the tempo
indicates. Some ticks are reserved for special actions, and to conserve raster-
time, certain realtime effects (pulse, vibrato, portamento) are skipped at the
same time. Let's assume a tempo of 6 and gateoff timer value 2 and look at
what happens on each tick:

Tick    Actions
0       - Initialization of new notes (no audible sound yet)
        - Orderlist advance if necessary
        - Pulsetable execution only if no orderlist advance
        - Wavetable execution
        - "One-shot" commands 5XY-FXY

1       - New notes become audible
        - Pulsetable execution
        - Wavetable or continuous commands 1XY-4XY

2,3     - Pulsetable execution
        - Wavetable or continuous commands 1XY-4XY

4       - New notes fetched from the pattern
        - Gateoff and hard restart for new notes
          (2 ticks before first frame, as gatetimer indicates)
        - No pulsetable execution
        - Wavetable or continuous commands 1XY-4XY

5       - Pulsetable execution
        - Wavetable or continuous commands 1XY-4XY

Filtertable is executed on each tick regardless of what the channels are doing.
Wavetable is never skipped, so arpeggios/drumsounds should always play OK.

If you use tempo 3 and gateoff timer 2, be aware that pulse execution is then
actually skipped on the first audible frame of the notes! It would probably be
better to use gateoff timer 1 in that case.

3.6 Miscellaneous tips
----------------------

- Patterns will take less memory the less there are command changes. When the
  song is packed/relocated, for example a long vibrato or portamento effect
  needs to be stored only once as long as the parameter stays the same on
  subsequent pattern rows.

- Using instrument vibrato can make 4XY commands unnecessary and save even
  more memory. However, since vibrato/portamento speed isn't calculated from
  note pitch, the effect becomes less noticeable in higher octaves.

- In the instrument parameters, there is no option to stop pulse execution
  directly. So if you have for example a sawtooth instrument, there might be
  an "unnecessary" pulsemodulation going on underneath and wasting rastertime.
  There are two ways you can stop this:
  1) Make a short pulseprogram like this and use it in the instrument:
     01: 80 00 Set pulse $000
     02: FF 00 Stop pulse execution
  2) Use pattern command 900 to stop pulse execution

- If you have a continuous command (vibrato/portamento), you can put "one-shot"
  commands 5XY-FXY inbetween and the continuous effect will be unaffected. An
  example:

  C-4 01000
  --- 00444 Begin vibrato with parameter $44
  --- 00444
  --- 00444
  --- 0065A Set sustain/release to $5A. Vibrato executes also on this step!
  --- 00444 Continue vibrato normally
  --- 00444

  However, the vibrato would stop immediately if command 0 was encountered.

3.7 Multispeed tips
-------------------

- When making multispeed songs, remember to multiply your tempos and also the
  gateoff timer values! For example, gateoff timer is normally 2, but in a 2X-
  speed tune the same gateoff length would be achieved with value 4.

- When importing a v1.xx multispeed song, you also need to multiply the
  gateoff timers.

- In the instruments, using Attack 0 might result in a very silent first row of
  the wavetable. You could try increasing the attack, or adding one or more
  09 00 (testbit+gate) to the beginning of the wavetable.


4. Using the included utilities
-------------------------------

4.1 INS2SND2.EXE
---------------

INS2SND2.EXE converts GoatTracker v1.xx or v2 instruments (.INS-files) into
sound effects, outputting the data as source code or binary.

Usage: INS2SND <instrumentfile> <sourcecodefile> <options>
Options:
-b output in binary
-c output in CovertScript format (deprecated)

Default output is C64 assembler (DASM) style source code

Look at section 6.3 or run the program without parameters to see the
limitations of the sound effect system.

4.2 SNGSPLI2.EXE
----------------

SNGSPLI2.EXE splits the patterns of a GoatTracker v2 song into smaller pieces
for memory use optimization. It is comfortable to compose with large patterns
but usually more efficient memory-wise to use small patterns. Remember! Always
keep the original song because a pattern-splitted song is much harder to edit
further.

Usage: SNGSPLI2 <source> <destination> [target len]

For example, if a pattern is 64 rows long and the target length is 16, it will
be split into 4 pieces. A pattern that falls below 2 x target length, will not
be split at all.

4.3 MOD2SNG.EXE
---------------

Dedicated exclusively to T.M.R, this program converts the pattern & orderlist
data of 4-channel, 31-instrument MOD-files into GoatTracker .SNG files. You
must choose one channel to leave out, and obviously instruments aren't
converted, except for their names. You can also specify a transpose in
halfsteps.

Usage: MOD2SNG <mod> <sng> [channel] [transpose]
       [channel] is the channel to leave out (1-4), default 4
       [transpose] is the halfstep transpose added to notes, default 0

4.4 BETACONV.EXE
----------------

Converts GT v2 beta songs to new format used by GT v2 RC1 onwards. Old format
had 47 instruments max. and new has 63 max. Additionally, depending on what
beta version you used, you can choose to halve vibrato depths and pulse speeds
to make them play correct in the current version. Warning: the conversion is
irreversible, so have backups if you overwrite the old versions.

Usage: BETACONV <source> <destination> [vibdepth] [pulse]
       [vibdepth] decides whether to halve vibdepth (1=yes 0=no), default 0
       [pulse] decides whether to halve pulse speed (1=yes 0=no), default 0


5. Using the songs outside the editor
-------------------------------------

Press F9 in the editor to enter the packer/relocator. Choose playroutine,
startaddress, zeropage address (need 2 consecutive locations) and file format
(PRG/BIN/SID), then type the filename.

If you use patterns longer than 64 rows, there is the possibility that
relocation fails because of too complex patterns. Each pattern row can be 0-4
bytes packed, and the total amount of bytes per one pattern may not exceed 256.

If wave/pulse/filtertables overflow past row 255 without a jump command, you
will get a warning screen and have to press Y to confirm, or any other key to
cancel.

Look at /examples/example1.prg - example4.prg to get an idea how much these
playroutines take rastertime. No promises!

Note that if all instruments have the same gateoff timer and 1st wave settings,
and all of them use hard restart, the packer/relocator can choose an optimized
playroutine, which is slightly smaller/faster. Instrument data will also take
less space (7 vs. 9 bytes per instrument).

5.1 Playroutines 1 & 2: Standard
--------------------------------

To init music:

        LDA #tunenumber         ;Starting from 0
        JSR startaddress

To play one frame of music:

        JSR startaddress+3

To use timing marks:

        Put a mastervolume command (DXY) with parameter 10-FF in the music
        data. This value will be put at startaddress+$3F when the command is
        executed.

To fade out/fade in music:

        Seek for the command sequence
        LDA #$xx
        ORA #$0F
        STA $D418
        from the beginning of player, and change the parameter of the ORA
        command between $00-$0F to fade the music. Note that the master volume
        command (DXY) also modifies this same location, so it will clash if you
        use both methods..

Author-info can be read at startaddress+$20 (32 bytes).

If you need the whole zeropage, save the locations used by the player before
calling the playroutine. The playroutine itself doesn't depend on their value
between calls in any way.

Playroutine 1 has unbuffered SID writes and takes less rastertime, but in rare
cases you may encounter ADSR-bugs by having notes with very fast releases and
no pulse/filterinit in the instruments. For these cases, playroutine 2 has
buffered SID writes, but is slower.


5.2 Playroutine 3: Gamemusic (with sound-FX support)
----------------------------------------------------

Because the relocations involved would be very complex, v2 again saves also the
playroutine with the music data.

To init music / to play one frame of music: like playroutine 1

To play a sound effect: (see /examples/src/example2.s for more details)

        LDA #<effect      ;Start address of sound effect data
        LDY #>effect
        LDX #channel      ;0, 7 or 14 for channels 1-3
        JSR startaddress+6

To change mastervolume:

        LDA #volume       ;0-F
        JSR startaddress+9

The sound effects have a hardcoded priority system based on their start
addresses. A sound higher up in memory (bigger address) will never be
interrupted with a sound lower in memory.

5.3 Playroutine 4: Under-IO gamemusic
-------------------------------------

Works like playroutine 3, except that instead of writing to SID registers, it
writes to ghostregisters on zeropage, and can thus be located under the IO
area. This routine needs 27 bytes of zeropage: the 25 first locations are the
ghostregisters and the remaining 2 are temp-variables like in the other
players.

After playing one frame of music, use a reverse loop to copy the ghostregisters
to SID:

        LDX #$18
copy:   LDA ghostregs,x
        STA $D400,x
        DEX
        BPL copy

If you want, you can of course unroll the copy loop, but the idea is that ADSR
should always be written before waveform, so that the attack of notes remains
the same.

Because the ghostregisters are shared between both music & sound effect player,
there exists a possibility of sound errors, when a sound effect has finished,
and the same channel now wishes to play a music note using a pulse instrument
without pulseinit, continuing the previous pulseprogram.

(In comparision, the normal gamemusic player has ghostregisters of its own,
but the sound effect code writes to SID directly.)

5.4 Playroutine 5: Minimal
--------------------------

Works otherwise like playroutine 1, but timing marks are unsupported and no
author-info will be saved.


6. File/data formats description
--------------------------------

The sections in the files come in the sequential order in which they're
described.

6.1 GoatTracker v2 song (.SNG) format
-------------------------------------

6.1.1 Song header
-----------------

Offset  Size    Description
+0      4       Identification string GTS2
+4      32      Song name, padded with zeros
+36     32      Author name, padded with zeros
+68     32      Copyright string, padded with zeros
+100    byte    Number of subtunes

6.1.2 Song orderlists
---------------------

The orderlist structure repeats first for channels 1,2,3 of first subtune,
then for channels 1,2,3 of second subtune etc., until all subtunes
have been gone thru.

Offset  Size    Description
+0      byte    Length of this channel's orderlist n, not counting restart pos.
+1      n+1     The orderlist data:
                Values $00-$CF are pattern numbers
                Values $D0-$DF are repeat commands
                Values $E0-$FE are transpose commands
                Value $FF is the RST endmark, followed by a byte that indicates
                the restart position

6.1.3 Instruments
-----------------

Offset  Size    Description
+0      byte    Amount of instruments n

Then, this structure repeats n times for each instrument. Instrument 0 (the
empty instrument) is not stored.

Offset  Size    Description
+0      byte    Attack/Decay
+1      byte    Sustain/Release
+2      byte    Wavepointer
+3      byte    Pulsepointer
+4      byte    Filterpointer
+5      byte    Vibrato delay
+6      byte    Vibraro parameter
+7      byte    Gateoff timer
+8      byte    Hard restart/1st frame waveform
+9      16      Instrument name

6.1.4 Tables
------------

This structure repeats for each of the 3 tables (wavetable, pulsetable,
filtertable).

Offset  Size    Description
+0      byte    Amount n of rows in the table
+1      n       Left side of the table
+1+n    n       Right side of the table

6.1.5 Patterns header
---------------------

Offset  Size    Description
+0      byte    Number of patterns n

6.1.6 Patterns
--------------

Repeat n times, starting from pattern number 0.

Offset  Size    Description
+0      byte    Length of pattern in rows m
+1      m*4     Groups of 4 bytes for each row of the pattern:
                1st byte: Notenumber
                          Values $60-$BC are the notes C-0 - G#7
                          Value $BD is rest
                          Value $BE is keyoff
                          Value $BF is keyon
                          Value $FF is pattern end
                2nd byte: Instrument number ($00-$3F)
                3rd byte: Command ($00-$0F)
                4th byte: Command databyte

6.2 GoatTracker v2 instrument (.INS) format
-------------------------------------------

Offset  Size    Description
+0      byte    Attack/Decay
+1      byte    Sustain/Release
+2      byte    Wavepointer
+3      byte    Pulsepointer
+4      byte    Filterpointer
+5      byte    Vibrato delay
+6      byte    Vibraro parameter
+7      byte    Gateoff timer
+8      byte    Hard restart/1st frame waveform
+9      16      Instrument name

After the instrument data, this structure repeats for each of the 3 tables
(wavetable, pulsetable, filtertable).

Offset  Size    Description
+0      byte    Amount n of rows in the table
+1      n       Left side of the table
+1+n    n       Right side of the table

6.3 Sound effect data format
----------------------------

Offset  Size    Description
+0      byte    Attack/Decay
+1      byte    Sustain/Release
+2      byte    Pulse width. This value has nybbles reversed from what it looks
                like in the editor so a middle pulse $800 will be stored as $08,
                and the sound effect routine will put this value to both $D402
                and $D403 registers.
+3      ?       Wavetable. Contains note/waveform pairs (different order than
                in instrument wavetable), from which the waveform can be
                omitted if unchanged, as the value ranges don't overlap:
                        Value $00 ends the sound effect
                        Values $01-$81 are waveforms
                        Values $82-$DF are absolute notes D-0 - B-7
                Note that a note can't be omitted to store only waveform
                changes!

As you can see, the sound effect format is very simplistic. When converting an
instrument to a sound effect with INS2SND2, following things cause an error
message:

- If the resulting sound effect is more than 128 bytes
- If the instrument's wavetable contains relative notes, absolute notes C-0 or
  C#0, or waveforms > 129 ($81)

The instrument's pulsewidth modulation & filter settings will be completely
discarded.


7. Recompiling
--------------

To recompile for Win32, you need the MinGW development enviroment, use the
file src/makefile.win as makefile.

To recompile for Linux, use src/makefile.

In both cases you need the SDL development libraries in addition to the SDL
runtime, and the BME graphics/sound library. See http://www.libsdl.org for
the SDL library and the tools section of http://covertbitops.c64.org for BME.


8. Version history
------------------

v2.0 Beta Original public release.

v2.0      - Fixed crash in DMC-note entry mode.
          - Fixed v1.xx import pulse conversion, a case where pulse startpos
            was lower than the pulse low limit was not converted right.
          - Fixed instrument gatetimer becoming zero (can lead to tempo bugs)
            when cutting an instrument (SHIFT+X)
          - Fixed order of SID writes to make editor & C64 playroutine behave
            as similarly as possible.
          - Fixed removal of table-entries (when loading an instrument) in
            case another instrument uses them too.
          - Fixed toneportamento (3XY) with wavetable delays.
          - Fixed funktempo in packed/relocated songs.
          - Fixed behaviour of + & - keys while editing instrument name.
          - Fixed pattern editor transpose functions.
          - Added SHIFT+DEL to delete an instrument + its tabledata.
          - Added SHIFT+INS to insert rows on table first row without having to
            adjust tablepointers afterwards.
          - Added SHIFT+W,S for octave transpose.
          - Added SHIFT+1,2,3 to swap orderlists between channels.
          - Added SHIFT+BACKSPACE to clear a whole pattern row.
          - Added optimized playroutines, that will be used if all instruments
            have the same gateoff timer & 1st wave parameters.
          - Added duplicate check for v1.xx pulse conversion.
          - Added BETACONV-utility for conversion from beta format.
          - Added reSID interpolation option /I.
          - Added hexadecimal pattern row display option /D.
          - Added SID memory location parameter /L.
          - reSID interpolation is on by default.
          - Changed appearance of pattern special notes (rest, keyoff/on)
          - Increased amount of instruments to 63 and changed song dataformat.
          - v1.xx import converts arpeggios to instruments as long as there is
            room.
          - Vibrato depth changed back to same as in v1.xx.
          - Pulse modulation speeds are doubled.
          - Upon startup, songdata erase, or importing v1.xx data, gatetimer
            will be set to 2 * multiplier as opposed to just 2.
          - Optimized size & speed of all playroutines (initialization,
            checking for new note fetch, pulsetable execution).
          - Wavetable delay or no-wavechange on first step of instrument is
            definitely unsupported now! Protection to allow this conflicted
            with 3XY command.

v2.01     - Added under-IO gamemusic playroutine.

v2.02     - Added RETURN when instrument tableparameter (wave/pulse/filter) is
            0 to get you to the first free table location. SHIFT+RETURN will
            additionally also set the instrument tableparameter.
          - Added "set mastervolume"-jump to gamemusic routines.
          - Improved sound effect handling, when an effect is interrupted by
            another (less silence between sounds).

v2.03     - Added execution of continuous commands & instrument vibrato during
            wavetable delay.
          - Added wavetable right side value $80 to keep frequency unchanged
            (as a consequence, the note C-0 will cause the same effect).
          - Added relocator optimizations: all unnecessary data is stripped
            when packing/relocating.
          - Playroutines size-optimized.
          - Explanation of how different gatetimer values can lead to playback
            going out of sync (section 3.3).
          - reSID interpolation is no longer on by default :)

v2.04     - Added a questionable 25Hz mode (/S0)
          - Execution of commands on wavetable delay is completely reworked
            and more consistent now.
          - Note C-0 is usable again.

v2.05     - Added instrument legato feature (Hardres/1stwave parameter $00).
          - ADSR writes moved farther away from wave writes in the standard
            playroutine noteinit, lessening possibility of ADSR bugs.
          - Song initialization and pulsetable execution speed/sizeoptimized.

v2.06     - Packer/relocator tolerates up to 256 bytes long patterns now.
          - Optimized playroutine sizes.

v2.07     - Fixed transpose reset with F2/F3 song start (should not happen).
          - Fixed varying tempo on channels with F2/F3 song start.
          - Added warning screen to packer/relocator if table execution
            overflows.
          - Added writing of PAL/NTSC and 6581/8580 flags according to PSID V2
            NG specification.
          - -mwindows added to linker options for no displaying of DOS prompt
            window (in win32 version).

v2.08     - Added finevibrato mode (/V command line option).
          - Optimized playroutine sizes & speed.

v2.09     - Fixed max.pattern length in Clear Musicdata operation.
          - Added Minimal playroutine.
          - First wave value $80 also acts as a proper legato instrument now.
          - Optimized playroutine sizes & speed.
          - SID chip type & timing (PAL/NTSC) displayed on top row.

v2.1      - Added SHIFT+N for negating pulse/filter modulation speeds.
          - Added no-funktempo & no-octave0 optimizations to playroutines (a
            total of 8 sub-types for each playroutine).
          - Maximum speed is 16X now.
          - Separate song/instrument/packed song directories are remembered
            during session.
          - Pathname is displayed in the fileselector.
          - Filters ** and *.* display all files in the fileselector.
          - Song entered on commandline will be loaded at startup.
          - Song filename currently being edited is shown in the titlebar.
          - Currently edited song filename will be used as default in the
            "SAVE SONG" and "SAVE MUSIC+PLAYROUTINE" dialogs.
          - Instrument name will also be used as instrument filename as default
            in the "SAVE INSTRUMENT" dialog.
          - UPX used for compression of win32 executables.
          - Included a short reference of waveform bits (manual only).
          - Configuration file has clearer structure.

v2.11     - Added SHIFT+S for smart instrument paste (converts instrument
            numbers in all patterns, after cut/pasting an instrument).
          - Added SHIFT+L which allows to write <limit,speed> pulse/filter
            modulation steps and then convert them to the proper <time,speed>
            format.

v2.12     - Playroutine 1 has buffered SID-writes.
          - Octave 0 is not disabled in routines with sound FX (no matter what
            the relocator says...)

v2.13     - Standard playroutine now both in unbuffered and buffered flavors.

v2.15     - Added SHIFT+I for inverting current pattern selection / whole
            pattern.
