-
Notifications
You must be signed in to change notification settings - Fork 13
/
readme.txt
1868 lines (1469 loc) · 77.1 KB
/
readme.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
GoatTracker v2.72
-----------------
Editor by Lasse Öörni (loorni@gmail.com)
HardSID 4U support by Téli Sándor.
Uses reSID engine by Dag Lem.
Uses reSID distortion / nonlinearity by Antti Lankila.
Uses 6510 crossassembler from Exomizer2 beta by Magnus Lind.
Uses the SDL library.
GoatTracker icon by Antonio Vera.
Command quick reference by Simon Bennett.
Patches by Stefan A. Haubenthal, Valerio Cannone and Raine M. Ekman.
Distributed under GNU General Public License
(see the file COPYING for details)
Covert BitOps homepage:
http://covertbitops.c64.org
GoatTracker 2 SourceForge.net page:
http://sourceforge.net/projects/goattracker2
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 Hardware support
2.3 Keyboard commands
2.3.1 General keys
2.3.2 Pattern edit mode
2.3.2.1 Protracker note-entry mode
2.3.2.2 DMC note-entry mode
2.3.3 Song edit mode
2.3.4 Instrument edit mode
2.3.5 Table edit mode
2.3.6 Songname edit mode
2.4 Mouse control
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.4.4 Speedtable
3.5 Playback details
3.6 Miscellaneous tips
3.6.1 Limit-based modulation steps
3.6.2 Precalculated note-independent "hifi player" portamento/vibrato
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 Playroutine options
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.
- The song tries to jump directly onto a table row containing a jump (FF xx),
either with instrument pointers or 8XY, 9XY, AXY commands.
- The song tries to execute pattern commands 0XY, 8XY or EXY from the
wavetable.
These all are error conditions, and trying to pack/relocate such song should
give an error message.
5. Using delayed wavetable or no wavechange (0x 00, where x is 0-F) in the
first step of instrument wavetable is unsupported and may result in missing
notes.
6. 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 1stFrame Wave 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.
3) Try hardrestart attack parameter $F for alternative SID register write
order.
7. From v2.18 onwards, wavetable left side values have changed. Delay can
now be maximum 16 frames (values $00-$0F), and waveform register values
$00-$0F (inaudible) have been mapped to table values $E0-$EF. For example,
testbit + gate would be $E9. You need to manually convert values $08-$0F
from your old songs!
8. From v2.2 onwards, a new table (speedtable) has been added. The portamento,
vibrato and funktempo commands use it. Old songs will be converted upon
loading to use the speedtable. Note the keyboard command SHIFT+RETURN
to convert the old style parameters.
9. From v2.4 onwards, pulse modulation speed has 1 bit added accuracy, so
you need to double pulsespeeds when composing new songs. Old songs will
be converted automatically.
10. From v2.59 onwards, gateoff timer parameter high bit disables hardrestart
and bit $40 disables gateoff. Old songs & instruments will be converted
automatically.
11. From v2.62 onwards, realtime calculated portamento/vibrato speeds are
supported. This is activated by having the high bit ($80) set in the speed-
table left side. Naturally, this means that very high portamento speeds (>=
$8000) or vibrato speeds (>= $80) become unavailable, but these should not
be very useful anyway.
12. From v2.68 onwards, SID write order has been tweaked for better stability
regarding badlines. This has the consequence, however, that notes with
attack 0 & release 1 may ADSR-bug. In this case, try hardrestart attack
parameter $F for alternative SID register write order.
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
-Fxx Set custom SID clock cycles per second (0 = use PAL/NTSC default)
-Gxx Set pitch of A-4 in Hz (0 = use default frequencytable, close to 440Hz)
-Hxx Use HardSID (0 = off, 1 = HardSID ID0 2 = HardSID ID1 etc.)
-Ixx Set reSID interpolation (0 = off, 1 = on, 2 = distortion, 3 = distortion & 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
-Oxx Set pulse optimization/skipping (0 = off, 1 = on) DEFAULT=on
-Rxx Set realtime command optimization/skipping (0 = off, 1 = on) DEFAULT=on
-Sxx Set speed multiplier (0 for 25Hz, 1 for 1x, 2 for 2x etc.)
-Txx Set HardSID interactive mode sound buffer length in milliseconds
DEFAULT=20, max.buffering=0
-Uxx Set HardSID playback mode sound buffer length in milliseconds
DEFAULT=400, max.buffering=0
-Vxx Set finevibrato conversion (0 = off, 1 = on) DEFAULT=on
-Xxx Set window type (0 = window, 1 = fullscreen) DEFAULT=window
-Zxx Set random reSID write delay in cycles (0 = off) DEFAULT=off
-N Use NTSC timing
-P Use PAL timing (DEFAULT)
-W Write emulated sound output to a file SIDAUDIO.RAW
-? Show command line options
-?? Standalone online help window
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.
Finevibrato mode is on by default. You can change this behaviour with -V
option. Note that finevibrato mode only affects the conversion of old style
vibrato parameters to speedtable format.
Pulse optimization -O determines if pulsetable execution will be skipped when
getting new notes or a new pattern. By default it is on. Be warned that
turning it off will increase the rastertime requirements of packed/relocated
songs greatly!
Realtime command optimization -R determines if portamento, vibrato & instrument
vibrato will be skipped on tick 0 of each pattern row. By default it is on, as
this is how tracker programs have operated traditionally. Turning it off makes
the commands sound same regardless of tempo but will increase rastertime use.
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. 000F makes
the note start very pronounced.
Hard restart parameter with attack at maximum (F) enables the use of an
alternative playroutine, where waveform is written before ADSR. This can give
more reliable note triggering, especially for very fast releases 0 & 1, but
may change the characteristics of the note's decay & release.
2.2 Hardware support
--------------------
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://dawork.synchronus.de/
To enable better support of multispeeds and cycle-exact timing on HardSID
(currently Win32 only), download an enhanced HardSID.dll:
For HardSID ISA/PCI cards -
http://sourceforge.net/project/showfiles.php?group_id=9266&release_id=61843
For HardSID 4U -
http://www.hardsid.com
Cycle-exact HardSID buffer length is separately configurable for interactive
mode (-T option) & playback mode (-U option).
HardSID interactive mode:
Low latency mode for jamming and accurate GUI display. Interactive mode can
be activated during song/pattern playback by enabling jamming (space key).
HardSID playback mode:
High stability mode to avoid interruptions caused by other applications/poor
drivers/weaker CPU. GUI display is less accurate in this mode. Set the -U
parameter to zero to achieve the maximum stability (less accurate GUI).
2.3 Keyboard commands
---------------------
This program is mainly 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.3.1 General keys
------------------
F1 Play from beginning
F2 Play from current pos.
F3 Play one pattern from current pos.
F4 Stop playing & silence all sounds
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. Press F12 again to toggle context mode
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
SHIFT+F5 Decrease speed multiplier
SHIFT+F6 Increase speed multiplier
SHIFT+F7 Edit hardrestart ADSR parameter
SHIFT+F8 Switch between 6581 and 8580 SID models
SHIFT+,. Move song startposition on all channels and restart last playmode
TAB Cycle between editing modes (forwards)
SHIFT+TAB Cycle between editing modes (backwards)
INS Insert row (Press INS/DEL on endmark to change pattern/song length)
DEL Delete row
SHIFT+ESC Optimize musicdata, or clear musicdata & set default pattern length
ESC Exit program
2.3.2 Pattern edit mode
-----------------------
- + Select instrument
/ * Select octave
< > Select pattern
BACKQUOTE Select channel
0-9 & A-F Enter parameters
SPACE Switch between jam/editmode
RETURN (also CAPSLOCK) Insert keyoff
Enter table (when cursor is over a table-utilizing command)
Enter instrument (when cursor is over a nonzero instrument number)
SHIFT+RET. Insert keyon
Convert portamento/vibrato/funktempo old style parameter to a
speedtable entry (when cursor is over the command)
Go into an empty table entry (when parameter is zero on a
table-utilizing command)
BACKSPACE Insert rest
SHIFT+BKSP. Insert rest and clear commands
SHIFT+SPACE Play from cursor position
SHIFT+Q Transpose halfstep up
SHIFT+A Transpose halfstep down
SHIFT+W Transpose octave up
SHIFT+S Transpose octave down
SHIFT+O Shrink pattern (divide size by 2)
SHIFT+P Expand pattern (multiply size by 2)
SHIFT+J Join pattern with next pattern in orderlist
SHIFT+K Split pattern from edit position
SHIFT+H Calculate "hifi" left/right shifted speedtable entry for
portamento or vibrato
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 commands
SHIFT+Z Cycle autoadvance-mode
For pattern joining to work properly, select the pattern you want to join with
the next from the orderlist first (by pressing RETURN on it). Both joining and
splitting will rearrange pattern numbers (for example if you split pattern 00,
pattern 01 will be created and old patterns 01-xx will be shifted forward in
the pattern order)
SHIFT+SPACE will play from the pattern onwards if playback was previously
stopped, but if it is pressed while in pattern play mode, it will stay in
the current pattern.
There are 2 modes for note entering:
2.3.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.3.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.3.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
BACKSPACE Set end position for F2 key
RETURN Go to pattern
SHIFT+R Insert Repeat command (shown as "R" in the order-list)
SHIFT+CRSR LEFT/RIGHT Mark orderlist
SHIFT+1,2,3 Swap current channel orderlist with channel 1,2,3
SHIFT+X,C,V Cut,copy,paste channel orderlist
SHIFT+L Mark/unmark entire orderlist
SHIFT+SPACE Set start position on all channels
SHIFT+RET. Go to pattern on all channels
SHIFT+SPACE or SHIFT+BACKSPACE set the start/end mark on all channels to
the same position. To clear the endmark, press BACKSPACE again on it or
at/before the startmark.
2.3.4 Instrument edit mode
--------------------------
< > Select instrument
- + 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/filter/vibratopos.
SHIFT+N Edit instrument name
SHIFT+S Smart paste an instrument
SHIFT+U Unlock/lock table scrolling
SHIFT+X,C,V Cut,copy,paste instrument
SHIFT+DEL (also SHIFT+BACKSPACE) Delete instrument & tabledata
SHIFT+RET. Set tablepointer to empty position or convert old style vibrato
parameter
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/pulse/filter/vibrato param. is zero 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.
If vibrato parameter is nonzero and you press SHIFT+RETURN over it, it will
be interpreted as an old style vibrato parameter (left nybble speed, right
nybble depth) and converted to a speedtable entry.
"Smart paste" will convert instrument numbers in all patterns if you "move" an
instrument by cut/pasting it.
2.3.5 Table edit mode
---------------------
< > Select instrument
- + Select instrument
/ * Select octave
BACKQUOTE Select table
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+Q,A Transpose speedtable portamento speed halfstep up/down
SHIFT+W,S Transpose speedtable portamento speed octave up/down,
or multiply/divide pulse/filterspeed by 2
SHIFT+L Convert <limit,speed> modulation step to <time,speed>
SHIFT+N Negate speed parameter (pulse/filtertable) or relative note
(wavetable)
SHIFT+O Optimize current table (remove unused entries)
SHIFT+R Convert note between absolute/relative in wavetable
SHIFT+U Unlock/lock table scrolling
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.
Conversion between relative and absolute notes will use the basenote C-0 if
octave is 0, C-1 if octave is 1 and so on.
When table scrolling is unlocked, each table maintains its separate view
position. To indicate this mode, a "U" letter is visible in the bottom right
part of the screen. By default table scrolling is locked.
2.3.6 Songname edit mode
------------------------
Use cursor UP/DOWN to move between song, author & copyright strings, and
other keys to edit them.
2.4 Mouse control
-----------------
By clicking with the left mouse button, you can select the data to edit.
By dragging with middle or right mouse button, you can mark orderlist/pattern/
tabledata.
Some values like octave or subtune/pattern numbers can be incremented with
the left mouse button and decremented with the right.
By holding the middle/right mouse button in the status bar, a menu becomes
active. Continue to hold and click with left button to select options.
In the fileselector, confirm loading or entering a directory by double-
clicking. Doubleclick outside the selector to cancel.
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 128 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 effect commands. 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. XY is an index to a 16-bit speed value in the
speedtable.
Command 2XY: Portamento down. XY is an index to a 16-bit speed value in the
speedtable.
Command 3XY: Toneportamento. Raise or lower pitch until target note has been
reached. XY is an index to a 16-bit speed value in the
speedtable, or $00 for "tie-note" effect (move pitch instantly to
target note)
Command 4XY: Vibrato. XY is an index to the speed table, where left side
determines how long until the direction changes (speed)
and right side determines the amount of pitch change on each tick
(depth).
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. XY is an index to the speedtable, tempo will alternate
between left side value and right side value 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-$01 recall the funktempo values 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.6 (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 Pos Wavetable startposition. Value $00 stops the wavetable
execution and is not very useful.
Pulsetable Pos Pulsetable startposition. Value $00 will leave pulse
execution untouched.
Filtertable Pos 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 Param Instrument vibrato parameter. An index to the speedtable,
see command 4XY.
Vibrato Delay How many ticks until instrument vibrato starts. Value $00
turns instrument vibrato off.
HR/Gate Timer How many ticks before note start note fetch, gateoff and
hard restart happen. Can be at most tempo-1. So on tempo 4
highest acceptable value is 3. Bitvalue $80 disables hard
restart and bitvalue $40 disables gateoff.
1stFrame Wave Waveform used on init frame of the note, usually $09 (gate
+ testbit). Values $00, $FE and $FF have special meaning:
leave waveform unchanged and additionally set gate off
($FE), gate on ($FF), or gate unchanged ($00).
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 is 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 HR/Gate Timer parameter has bit $40
set, no hard restart or gateoff will be performed. When 1st Frame Wave is also
$00, no 1st frame waveform will be set and gate flag is untouched. 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.
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-0F Delay this step by 1-15 frames
10-DF Waveform values
E0-EF Inaudible waveform values $00-$0F
F0-FE Execute command 0XY-EXY. Right side is parameter.
FF Jump. Right side tells position ($00 = stop)
Wavetable right side: 00-5F Relative notes
60-7F Negative relative notes (lower pitch)
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
realtime commands & instrument vibrato to be executed together with wave-
table. Be warned that this has the potential for large rastertime usage!
You can execute pattern commands from the wavetable. Right side
is the command parameter. Note that commands 0XY (do nothing), 8XY (set
wavetable pointer) and EXY (funktempo) are illegal and should not be used.
When executing a command, no wave/note will be changed on the same frame.
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 does not depend
02: 41 AA on 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 does not 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
01: 81 CF Short noise in the beginning, sawtooth, after a short delay change
02: 21 00 sustain/release (via pattern command 6XY) to $2A.
03: 08 00
04: F6 2A
05: FF 00
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).
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 (64)
03: 40 E0 For 64 ticks, decrease pulse with speed $FFE0 (-32)
04: 40 20 For 64 ticks, increase pulse with speed $0020 (32)
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.4.4 Speedtable
----------------
The speedtable is shared by vibrato, portamento and funktempo. No jump commands
exist.
For vibrato: XX YY Left side tells how long until vibrato direction
changes (speed), right side is the value added to
pitch each tick (depth).
For portamento: XX YY A 16-bit value added to pitch each tick. Left side
is the MSB and the right side the LSB.
For funktempo: XX YY Two 8-bit tempo values that are alternated on each
pattern row, starting from the left side.
For both vibrato and portamento, if XX has the high bit ($80) set, note
independent vibrato depth / portamento speed calculation is enabled, and YY
specifies the divisor (higher value -> lower result and more rastertime taken).
Vibrato examples:
01: 03 40 Vibrato with speed $03 and depth $40. Corresponds to old vibrato
parameter $34
01: 05 04 Speed $05 and depth $04. Slow shallow vibrato, suitable for bass
notes. Not possible to achieve with old parameters.
01: 83 04 Speed $03, note-independent depth enabled, depth divisor 4 right-
shifts (division by 16).
Portamento examples:
01: 00 20 Portamento with speed $0020, corresponds to old parameter $08
(4 * $08 = $0020).
01: 01 00 Portamento with speed $0100, corresponds to old parameter $40
(4 * $40 = $0100).
01: 4F FF Portamento with speed $4fff, loops the pitch highbyte very fast
so that a SEUCK-like "space" effect is heard. Not possible to
achieve with old parameters.
01: 80 01 Note-independent speed enabled, speed divisor 1 rightshift
(division by 2).
Funktempo examples:
01: 09 06 Play tempo $09 on even pattern steps and $06 on odd steps,
corresponds to old parameter $96.
01: 24 18 The same funktempo adjusted for 4x-multispeed. Not possible to
achieve with old parameters.
Note that you can enter old style vibrato parameters, portamento speeds and
funktempo to patterns & instruments, and when cursor is over the parameter,
press SHIFT+RETURN to create a new speedtable entry corresponding to that
parameter. The parameter will now be overwritten by a speedtable pointer.
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/commands (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 realtime pattern commands 1XY-4XY
2,3 - Pulsetable execution
- Wavetable or realtime pattern commands 1XY-4XY
4 - New notes fetched from the pattern
- Gateoff and hard restart for new notes
(2 ticks before first frame, as gateoff timer indicates)
- No pulsetable execution
- Wavetable or realtime pattern commands 1XY-4XY
5 - Pulsetable execution
- Wavetable or realtime pattern commands 1XY-4XY