TRILOTRACKER

Introduction

Work on TriloTracker was started around mid 2011. The goal was to write a music tracker that would support both the PSG (AY3-8910) and SCC (Konami's Sound Custom Chip) for our own projects.
After some experiments it was decided to move the tracker to dedicated MSX hardware (or MSX emulation) as sound emulation didn't work out very well.

TriloTracker is strongly influenced by Vortex Tracker II which is probably the best tracker available for creating PSG music for the MSX. To be able to convert quickly from Vortex Tracker II to TriloTracker we adopted many features (like the instrument macros). Other influences come from FastTracker 2. The effects, order list, instrument list and pattern lay-out show similarities.
Later, during development, an FM version of the tracker was created. This version is only a hacked version of the origininal tracker for PSG and SCC. This version is not fully developed and still has SCC references and has some unintuitive user interfaces.

TriloTracker would not be what it is today without the help of the following people:
* ARTRAG (SCC routines, teaching me to code)
* John Hassink (Design, Testing)
* Inverse Phase (Design, Testing)
* Gryzor87 (Design, Testing)

MSX emulation

This is a short guide to get started on running TriloTracker using emulation.

openMSX installation and setup
This guide will only describe the installation and configuration on a windows operating system.
Download the latest (install) version of the openMSX emulator on the openMSX website: (http://openmsx.sourceforge.net/)
<img>
Once downloaded execute the installer. Make sure you install the 'Core Emulator' and 'Catapult'. If you like to create videos you can also install the "Video Codec".
<img>
Once the installation is done we still need the MSX system ROM's to be able to run the emulator.
Most MSX system roms can be found on the blueMSX (this is another MSX emulator) website (http:\\www.vik.cc/bluemsx/resource.html).
Choose the Panasonic "FS-A1GT" package. Download the file and extract the ROMs into the openMSX system ROM folder (C:\Program Files\openMSX\share\systemroms).
Now start the Catapult UI (from the start menu). On the first run catapult will test the available system ROMs. The Panasonic FS-A1GT ROMs will be recognized an stored it is dedicated folder.
Now you are almost ready to start using TriloTracker. In the Catapult UI select the Panasonic 'FS-A1GT' and 'SCC' extension. Select the disk image of TT using the disk button.
Press 'start' and the emulator will start the MSX emulation.
At default the you will end up on the MSX-DOS prompt. Type 'TT' to start the tracker software.

Instrument editor

General

At default all instruments are empty (no sound). At first it might be a little confusing but once you are used to it it will take little effort to create your own instruments.
To edit the instruments you have to open the instrument editor using the [F2] key. There is a total of 31 instruments available. The instruments consist out of several parts:
? A name
? A macro
? A waveform


Name

The name of the instrument is only for helping keep track of what instrument is which. The instruments names are always visible in the instrument menu area (top right) in the pattern and instrument editor.

Macro

The macro is the most important part. Without it there is no sound. Each instrument macro has its own length and restart (loop) position. Each tic a macro step is processed. A macro step is built up like this:
r ss TN fFFF nNN vV
For TTFM
r ss TNL fFFF nNN vV
For TTSMS
r ss TNL fFFF N X vV 

Column(s)
Description
Values
r
Restart column. The [R] indicator marks the loop position.

ss
Macro step number.
$00 - $1f (32 steps)
T
Tone enabled/disabled.
'T'(enabled) or 't'
N
Noise enabled/disabled.
'N'(enabled) or 'n'
L
FM Voice link. (see note below)
'L'(enabled) or 'l'.
f
Tone (frequency) deviation type .
'+' or '-'
FFF
Tone change in addition to the previous macro step.
$000-$fff (4096 steps)
n
Noise deviation type.
'_', '+' or '-'
NN
Noise change in addition to the previous macro step(+/-) or absolute(_).
$00-$1f (32 steps)
N
Noise value (absolute) First 4 values sets the periodic noise and next 4 set white noise options.
$0-$7 (8 steps)
v
Volume deviation type.
'_', '+' or '-'
V
Volume change in addition to the previous macro step (+/-) or absolute(_).
$0-$f (16 steps)
X
Noise volume (absolute).
$0-$f (16 steps)

NOTE:
When using the voicelink for FM instruments.
Make sure to manual restore the starting voice in the first step using link too.
The most simple instrument macro is this (you can test a macro using the keyjazz mode:
R 00 Tn +000 _00 _F        
The macro will generate a constant sound. As the tone (T) is enabled and the volume is at max. But you can make much nicer instruments using multiple macro steps. Most common is to only use the volume to set the ADSR (Attack,Decay and Sustain, Release) technique.
The noise columns are only processed when the instrument is used in the three PSG channels. Do remember that there is only 1 noise channel (the 4th PSG channel). When using multiple instruments that produce noise (noise enabled) on the same tic, only the last noise values are used.

Waveform

The waveform is only used for the SCC. Without it the SCC will not generate sound (even if the Tone is enabled). A waveform is a 32 byte sample that is played constantly (looped). Each instrument can be linked to 1 of 32 available waveform slots.
FM Voice
The FM Voice is only used for the FM (TTFM and TTSMS versions). Next to the default 15 HW voices there are a set of software voice available. The last voices are customs voices. These voices can be created/edited and will be saved. Note: The default set of custom voices can be edited too but are not saved when changed.

Loading and Saving

The [F5] key opens the instrument filedialog from withing the instrument editor. Use it to load/save:
? instruments
? instrument sets (31 instruments)
? macros
? macro sets (31 macros)
? waveforms
waveform sets (32 waveforms)

CONFIGURATION

The configuration menu is available under the [SHIFT]+[F5] key combination.

EFFECTS:

0xy ? Arpeggio

[ PSG ][ SCC ][ FM ]
Cycles between note, note+x halftones, note+y halftones. Example:
C-4 1. 047  - Set arpeggio
... .. ...  - Arpeggio continues
... .. 100  - Arpeggio stops.

This will play C-4, C-4+4 semitones and C-4+7 semitones (C-4, E-4 and G-4) Note: if both x and y are zero, this command is ignored (and displayed as "..."). You can stop the arpeggio with 100, 200, 300, 400, etc.
See also command E0y Short Arpeggio for details for using 2 tone arpeggios.

1xy - Portamento up

[ PSG ][ SCC ][ FM ]
This will slide up the pitch of the current note being played by the given step size (in xy) each tic. 100 will continue the previous portamento values, even after a new note or effect. The slide will wrap around when it has reached the limit of the tone register. The slide is not delimited.
C#4 .. ...      Play a note
... .. 106      Portamento up in steps of 6 on each tic.
... .. 100      Continue slide
G-4 .. ...      New note
... .. 100      Slide the new note in steps of 6 again.


In next release: This will slide up the pitch of the current note being played by the given step size (in xy) each tic. Values for x and y range between 1 and 255 ($1-$FF). 100 will stop the portamento. The slide will wrap around when it has reached the limit of the tone register. The slide is not delimited.
C#4 .. ...      Play a note
... .. 106      Portamento up in steps of 6 on each tic.
... .. ...      Continue slide
... .. 100      Stop the slide


2xy - Portamento down

[ PSG ][ SCC ][ FM ]
Same as portamento up bit his will slide up the pitch of the current note being played by the given step size (in xy) each tic.

3xy - Tone Portamento

[ PSG ][ SCC ][ FM ]
This command is used together with a note, and will bend the current pitch at the given step size ,on each tic, towards the specified note. Example:
C-4 1. ...
F-4 .. 305 (bend the note up towards F-4)
... .. 300 (continue to slide up, until F-4 is reached)

In next release: This command is used together with a note, and will bend the current pitch at the given step size, on each tic, towards the specified note. Use 300 to stop the portamento when needed. Example:
C-4 1. ...
F-4 .. 305 (bend the note up towards F-4)
... .. ... (continue to slide up, until F-4 is reached)

4xy ? Vibrato

[ PSG ][ SCC ][ FM ]
Vibrato with speed x and depth y. This command will oscillate the frequency of the current note with a sine wave. (You can change the vibrato waveform to a triangle wave, a square wave, or a random table by using the E4x command). the depth value ranges from 0 to 7.

Next release: Vibrato with speed x and depth y. This command will oscillate the frequency of the current note with a sine wave. The depth value ranges from 1 to 13 ($1 - $D). Higher values are ignored. The speed x set the speed in number of tics from 1 to 15 ($1 - $F). The vibrato can be updated during the effect by using 40y (set new depth) or 4x0 (set new speed). 400 will stop the effect. Example:
C-4 .. ...
... .. 442 Start vibrato with depth 2 and speed 4
... .. ... 
... .. 404 Update the vibrato depth to 4 and keep speed the same. 

5xy - Tone Portamento + Volume Slide

[ PSG ][ SCC ][ FM ]
This command is equivalent to Tone-Portamento and Volume Slide. (3xy + Axy). First set the Tone-Portamento.

6xy - Vibrato + Volume Slide

[ PSG ][ SCC ][ FM ]
This command is equivalent to Vibrato and Volume Slide. (400 + Axy).

7xy - <unused>


8xy - PSG HW Envelope Multiplier

[ PSG ][ [ SCC ] ][ FM ]
This command sets the frequency of the hardware envelope registers. The value of xy is multiplied with 8 to set the frequency value(0-2040). The frequency value sets the speed of the envelope steps. The default frequency is always set to 0. Value set using this command will stay in effect until changed and/or end of playback.
This command only sets the envelope frequency and can be used in any track (even non-PSG tracks). To use the HW envelope playback command EEy is used.
Example:
... .. 801 Set the frequency to 8. Step speed is: (8*1024)/4000000 = 0,002 seconds

9xy - Macro offset

[ PSG ][ SCC ][ FM ]
This command, when used together with a note, will start playing the sample at the position xy (instead of position 0). If xy is 00 (900), the previous value will be used. Be sure not to use xy values outside the instrument macro.

NOTE:
This effect is NOT supported in the standalone re-player.

Axy - Volume slide

[ PSG ][ SCC ][ FM ]
Slide up or down the current volume. ... .. A20 Slides up the current volume each 2 ticks by one. ... .. A08 Slides down the current volume each 8 ticks by one.
Note!: Until TT v0.9 there is a bug in the volume slide.

Bxy - SCC commands

[ PSG ][ SCC ][ FM ]

B00 ? Reset

Resets the waveform to the waveform related to the current instrument.

B1y - Duty Cycle

Generates a square waveform for the current track. The value ($0 - $f) in y defines the shape (0-50%) of the waveform to generate in steps of 3,125%.
... .. B10       Waveform 3,1%: ________
... .. B17                25%: ??______

B2y - Waveform cut

Cuts the current waveform (related to instrument) at position y to 0 (no amplitude). The value in y ($0-$f) defines size of the waveform in steps of 6.5%. The rest is cut to center.
... .. B20       Waveform 6,5%: /-------
... .. B2F                100%: /\////// 

B4y - Waveform compress

Next release: Removed
Compresses the current waveform (related to instrument). Parameter y contains the value ($0..$7) of the compression rate in steps of 4%. ($0=4%, $7=32%).

BBy - Set waveform

Changes the current waveform into the waveform specified in y. Only waveforms $0..$F can be used.

BCy - Set waveform+16.

Changes the current waveform into the waveform+16 specified in y. Only waveforms $0..$F can be used. With this command it is possible to set the upper 16 waveforms.

Bxy - FM commands

[ PSG ][ SCC ][ FM ]

B0y - Change channel setup

Set the channel set-uo used to replay the song.
... .. B00       Use 2 PSG and 6 FM channels
... .. B01       Use 3 PSG and 5 FM channels

Cxy - SCC morph

[ PSG ][ SCC ][ FM ]

NOTE:
This effect only affects the SCC chip channels. In contradiction to the other effect commands this command will stay active and do not need to be re-triggered each row
Waveform morphing will morph between 2 waveforms. The morphing is done in 16 steps using variable intervals. Only 1 morph at the same time is possible. Multiple tracks can use the same morphing waveform by using the 'morph-slave' command. A morph will always complete in the background (except for morph change Cx0 and Cxy). Even after a track stops acting in 'morph-slave' mode. 'Morph-slave' mode is cancelled in a track by a note, rest (-R-), instrument or Bxy effect.
Example:
C-4 3FC14  ... .....  morph each 4 tics current instrument waveform to waveform 1
... .....  C-4 3DC00  this track will follow any morph updates.
... .....  ... ..412  normal effects still work as normal
C-3 .....  ... ..400  morph stops in the track with a note 
E-4 ..C00  ... ..C00  morph is not restarted but continued in both tracks. 'slave'
... .....  ... ..C60  morph stops and current morphed waveform is morphed into waveform 6
... .....  ... ..C44  morph restarts with original instrument waveform to waveform 4 
... .....  ... 3....  morph stops in the track with the instrument.

C00

Set this track to 'morph-slave' mode. Any morph updates are automatically updated in this track.

Cx0

Start a new morph into waveform x using the current morph waveform values. Only useful after a Cxy command. The current morph speed is maintained (x values between 1-F). Sets track into 'morph-slave' mode.

Cxy

Start a new morph into waveform x (0-F) starting from the original instrument waveform. The update interval, in tics, is set using y (1-F). Sets track into 'morph-slave' mode.


Cxy - FM drum commands

[ PSG ][ SCC ][ FM ]

NOTE:
This effect only affects the FM chip drum channels. But the drum commands can be used in any track (even PSG) and will affect the FM chip drum channels.

NOTE:
Only 1 drum macro can be played at the same time.
At default the drum macros are initialized as follows:

drum preset layout

preset     |1|2|3|4|5|6|7|8|9|A|B|C|D|E|F|
           | | | | | | | | | | | | | | | |
bass-drum  |x| |x| | |x| |x| |x|x| |x|x| |
snare-drum | |x|x| | | |x|x| | | |x|x| | |
hi-hat     | | | |x| | | | | | |x|x|x| |x|
cymbal     | | | | |x|x|x|x| | | | | |x|x|
tom        | | | | | | | | |x|x| | | |x| |

C00
Reset all percussion registers to default.
Cxy
Play the corresponding drum macro (1-20)
D00 - Pattern end
[ PSG ][ SCC ][ FM ]
Stops playing the current pattern and continues to the next pattern.
Exy - Extended commands
[ PSG ][ SCC ][ FM ]
E0y - Short arpeggio
y value sets the number of halve tones to alternate every tic (note+0.note+y). Use E00 to continue the sort arpeggio on the next step.
E1y - Fine slide up
y value sets the value to slide up. This is only done once. This command is useful on higher notes for portamento or as note detune.
E2y - Fine slide down
y value sets the value to slide down. This is only done once. This command is useful on higher notes for portamento or as note detune.
E4y - Vibrato control
Next release: This effect will be removed.
y value sets the form used on vibrato (0=sine,1=triangle,2=pulse). This setting will affect all channels.
E50 - Note link
Links the note next to this command with the previous note. The instrument macro is not restarted.
E6y - Track detune
y value sets the track detune for all notes played till set differently. Values $0..$7 are positive values and values $8..$F are negative values (-1..-7)
E7y - Sustain FM ONLY
y value set the sustain of the current note (0 is off, 1-f is on).
E8y - Global transpose
SCC
y value sets the global transpose for all notes in halve notes. Values $0..$7 are positive (0..7) values and values $8..$F are negative values (-1..-7)
---.. E82    Will add 2 halve notes to all notes played.
---.. ...
---.. E80    Global transpose is set back to original (reset).
E8y - Tone panning
TTSMS Sets the Game Gear Panning of the current channel.
0 = Silent
1 = Left
2 = Left+Right
3 = Right 
For Noise use E9y

TTFM No function
E9y - Noise panning
TTSMS Sets the Game Gear Panning of the noise channel.Can be used in any PSG channel.
0 = Silent
1 = Left
2 = Left+Right
3 = Right
ECy - Note cut delay
y value sets the delay in ticks to wait before stopping the current note.
EDy - Note delay
y value sets the delay in ticks to wait before starting the note.
EEy - Envelope
PSG ONLY
y value sets the envelope shape to use. Value EE0 will continue the current envelope command. Values $1-$f sets the envelope shape. The envelope shape is executed in 15 steps. Step speed depends on the envelope frequency (see command 8xy). Envelope shapes are restart at every EEy command (except EE0). The following envelope shapes are available:
8      \\\\\\\\\\
1-3,9  \_________  
A      \/\/\/\/\/
B      \?????????  
C      //////////
D      /?????????  
E      /\/\/\/\/\
4-7,F  /_________
EFy - Trigger
y value is set in the trigger variable. The trigger can be used to sync programs to the music.


Fxy - Replay Speed
[ PSG ][ SCC ][ FM ]
Set the speed (values 2-63) to play the music data. The xy value sets the delay in ?halve? ticks to wait between each pattern row.

CONTROLS:

General controls
Key(s)
Description
[']
Enter the order editor
[TAB]
Jump to the next track.
[TAB]+[SHIFT]
Jump to the previous track.
[ESC]
Return to the pattern edit area.
[HOME]
Jump to the beginning of the current pattern.
[CTRL]+[HOME]
Jump the the beginning of the song (first pattern in the song order).
[ENTER]
Start playback from the current order position and play it looped
[F1]
Start playback from current order position.
[F2]
Open the instrument editor.
[F4]
Open the track manager.
[F5]
Open the file dialog.
[F5]+[SHIFT]
Open the configuration editor.
[CTRL]+[D]
Open the order editor.
[CTRL]+[N]
Edit the name of the current song.
[CTRL]+[B]
Edit the composer name of the current song.
[CTRL]+[M]
Change the volume balance between PSG and SCC using the 
left/right cursor keys.
[CTRL]+[I] or [CTRL]+[TAB]
Enter the instrument menu.
[CTRL]+[P]
Set the current pattern number.
[CTRL]+[L]
Set the song length.
[CTRL]+[R]
Set the restart position when the song loops.
[CTRL]+[S]
Set the starting speed of the song
[CTRL]+[O]
Set the current octave used for note input.
[CTRL]+[T]
Set the step visualization size .
[CTRL]+[A]
Set the the default number of rows to add on entering pattern data.
[CTRL]+[0..8]
Enable/Disable the corresponding track. '0' is for FM drums.
Playback controls
Key(s)
Description
[1..8]
Enable/disable the corresponding track for playback.
[ESC]
Stop playback on current order and pattern position.
[SPACE]
Stop playback return to the order and pattern position before playback start.
[F1]
Return to normal playback after starting looped pattern playback ([ENTER]).








Pattern editor
Key(s)
Description
[ESC]
Reset cursor to the start of the current pattern.
[SPACE]
Enable/Disable the keyjazz mode.
[SHIFT]+<cursor keys>
select an area in the current pattern.
[SHIFT]+[GRAPH*]+<cursor keys>
select an area in the current pattern in step size (up/down) 
or in track size (left/right).
[GRAPH*]+<cursor keys>
move the cursor in the current pattern in step size (up/down) 
or in track size (left/right).
[CTRL]+<cursor up/down>
Jump to the next/previous pattern
[CTRL]+<cursor left/right>
Jump to the previous/next order step.
[CTRL]+[,]/[.]
Transpose the current selection in the pattern 1 (halve) note up/down.
[CTRL]+[<]/[>]
Transpose the current selection in the pattern 1 octave down/up.
[CTRL]+[1..8]
Disable/enable the corresponding track for playback.
[ALT/GRPH]+[1..8]
Disable/enable the corresponding track for solo playback.
[CTRL]+[C]
Place current selection in the pattern on the clipboard.
[CTRL]+[V]
Paste the current contents of the clipboard at the current cursor 
position of the current pattern.
[CTRL]+[Z]
Undo last change in the patterndata.
[CTRL]+[Y]
Redo the last undone change in the patterndata.
[CTRL]+[G]
Copy current pattern to the first available empty pattern.
[INS]
Insert an empty row at the cursor position of the current track. 
The contents of the track of the pattern is moved downwards.
[BCKSPC]
Delete the current row at the cursor position of the current track. 
The contents of the track of the current pattern is moved upwards. 
Inserting an empty row at the last row of the track.
[DEL]
Delete the value at current cursor position. In case of [DEL] inside a selection, 
it will erase all values inside the selection.
[NUMKEY 1..8]
Set the current edit base octave.
[SHIFT]
Enter a note with 1 octave higher.






-Note:[GRAPH] is an MSX specific key. In most emulators this key is mapped to the (left)[ALT] key.
Order editor
Key(s)
Description
[ESC]
Return to the pattern edit area.
[INS]
Insert a new position in the order at current position. 
Inserted pattern number is the pattern number from the previous 
order position + 1.
[CTRL]+[INS]
Insert a new position in the order after the last position. 
Inserted pattern number is the pattern number from the last order position + 1.
[CTRL]+[G]
Copy pattern of current position into a new pattern. 
Add the new pattern at the current position.
[R]
Set the restart position to the current order position.
<cursor keys up/down>
Jump to the previous/next order position.
<cursor keys left/right>
Change the pattern number at the current order position.


Instrument menu
Key(s)
Description
[ESC]
Return to the pattern edit area.
<cursor keys up/down>
Jump to the previous/next instrument.
<cursor keys left/right>
Jump to the previous/next in steps of 7 instruments.
[SPACE]/[ENTER]
Select the current instrument as default.
[0..9]/[A..V]
Set the corresponding instrument as default.



Instrument editor

General controls
Key(s)
Description
[ESC]
Return to the macro editor.
[CTRL]+[L]
Set the macro length (using cursor keys).
[CTRL]+[R]
Set the macro restart position (using cursor keys).
[CTRL]+[W]
Set the waveform of the current instrument.
[CTRL]+[D]
Set the name of the current instrument.
[CTRL]+[O]
Change the default octave (used for keyjazz mode).
[CTRL]+[T]
Set the default playback chip (PSG and/or SCC) (used for keyjazz mode).
[CTRL]+[F]
Jump to the waveform edit area.
[CTRL]+<cursor keys up/down>
Jump to the previous/next instrument.
[CTRL]+<cursor keys left/right>
Set the previous/next waveform for the current instrument.
[F5]
Open the instrument file dialog.
[TAB] or [CTRL]+[I]
Go to the instrument selection menu.


Macro editor
Key(s)
Description
[ESC]
Return to the pattern editor.
[R]
Set current macro row as restart position.
[CTRL]+[C]
Copy current instrument to the clipboard.
[CTRL]+[V]
Copy clipboard contents into current instrument (except the instrument name).
[T]
Enable/disable tone output for the current macro row.
[N]
Enable/disable noise output for the current macro row.
[-]
Set the deviation type to 'subtract' for the current value 
at the cursor (tone,noise or volume) for the current macro row.
[+]
Set the deviation type to 'add' for the current value 
at the cursor (tone,noise or volume) for the current macro row.
[_]/[=]
Set the deviation type to 'absolute' for the current value 
at the cursor (tone,noise or volume) for the current macro row.




Waveform editor
Key(s)
Description
[ESC]
Return to the macro editor.
<cursor keys up/down>
Increase/decrease the current waveform column in steps of 8.
[SHIFT]+<cursor keys up/down>
Increase/decrease the current waveform column in steps of 1.
[CTRL]+[C]
Copy current wave to the clipboard.
[CTRL]+[V]
Copy clipboard contents into current waveform.










Track manager

Key(s)
Description
[ESC]
Return to the pattern edit area.
[SHIFT]+<cursor keys>
Select patterns.
[CTRL]+<cursor left/right>
Select the track.
[CTRL]+[C]
Set the current selection as the source.
[CTRL]+[V]
Paste the source into the current selection or at current position and track.
[CTRL]+[S]
Swap the source with the trackdata at the current position and track.

