
                                TEDzakker 1.2 Help
                                ==================


I. Introduction:
================

 TEDzakker is a music editor for the TED chip of the CBM264 series (Plus4,C16)
which is humble compared to C64, but still can produce listenable music.
 TEDzakker 1.2 is mainly the same as 1.1 but now it can be run directly on the
PC (Linux/Windows), with all of its advantages (and disadvantages): Workfiles
(TZW) can be associated and opened as arguments, folders can be changed in file
dialogs, -zoom, preferred folder and -drive parameters can be given just like
in SID-Wizard-1.92.
 The batch-files beside the executables can be used to start with given
arguments and the 'tedzakker' executable is a selector for different TEDzakker
player-types, or if associated with .tzw files, it's a launcher that
automatically launches the TEDzakker-xxx file having the proper player-type
for the music-workfile.
 Filenames (if opened from within TEDzakker) must be shorter than 12 characters
(before the .tzw extension) and not contain uppercase or special/accented
characters (this is a Commodore-disk limitation for file-dialog compatibility).
 Mouse is supported if you prefer accessing the different positions of the
editor screen by clicking on them. Scroll-wheel mimics PageUp/PageDown keys.
The 'Zoom' button in the top-left corner can change 2x/3x/4x zoom (window-size)
by clicking on it with left (increase) or right (decrease) mouse-button.
 Some new functions in the editor: Selectable framespeed-spread with C=+F to
restrict multispeed to border and avoid music-calls in the dislay-area, and
selectable player-zeropage-address before exporting (on Murphy's requests).
The TZR format is not exported anymore, but a runnable TED format (ted.prg)
which also contains TMF metadata (title,length,etc) for playback from tools.
The playtime is autodetected for subtunes when they're played through and for
the 1st subtune it's saved into the TZW workfile and is adjustable in menu.
(And all detected subtune-durations are saved into the TED/TMF-file too.)

I think you've guessed already where the name 'TEDzakker' is coming from:
The TED is the all-in-one graphic+sound chip for the Commodore Plus4 and
Commodore 16 computers.
This music tracker tries to squeeze out some sound from the TED-chip which has
these humble features:
-Two channels: counter-based oscillators with nonlinear 108Hz...55kHz frequency
 range (No bass?! That's a pity, though you can find some solutions later if
 you read on.)
-First channel's oscillator can produce 50% duty-cycle pulse, while the
 2nd oscillator can produce the same but it can be switched to whitenoise
 waveform too.
-Both channels share the same volume ranging from 0..8. (Values 9..F equal to
 the volume of value 8.)
 (You'll see different solutions for this limitation in TEDzakker.)
-The channels can be synchronized. (It's very important to create some
 interesting new sounds.)

Never mind, I gess I nearly pushed the chip to its limits and you can still get
some decent sounds and tunes from it with some careful tweaking...

Let's see some extra features of TEDzakker in a nutshell:
-maximum 10 subtunes (only 1 on Commodore16), 100 patterns (only 8 on C16), 58
 instruments (only 6 on C16)
-6 different player-types for different needs and rastertimes/sizes ('normal',
 'light',etc.)
-TED sound emulation on SID for C64 version (Plus4 music can be composed on
 C64, TED can be driven by C64)
 (some rarely used aspects of TED aren't emulated by SID: ultrasounds,
  freq.$3FE, phase, 'noiseloop')
-HerMIDI MIDI-interface support (notes can be played, instruments can be
 selected)
-multispeed call can eat smaller rastertime than the single-speed (50Hz) call
-multispeed is selectable for waveform/frequency/volume tables of each
 individual instrument
-note-column effects (Slide Up/Down, Vibrato, Sync, Legato, Automatic
 Tone-Portamento)
-funktempo/tempoprogram programmable by consequent tempo-effects in orderlist
-subtune-jump effect to other subtune in orderlist
-short 1ms whitenoise can be enabled for instruments (crisp soundstarts)
-SYNC and PHASE between the two channels, possible to create ringmod or PWM-like
 sounds
-bass sounds deeper than A2=108Hz by utilizing 'noiseloop' (sounds a bit thin
 though, needs doubling)
-main-volume simulation with fade-out support, volume/fadeout can be set
 externally
-note-volume fade-in/out in instrument-tables to create volume-envelopes (ADSR
 and the like)
-note-OFF table-indexes (good e.g. for ADSR 'release' simulation)
-different mixing modes to map the virtual volumes of channels to shared volume
-detune/slide effect can be set by instr.table/pattern/orderlist, it is
 permanent (saving patterns)
-normal/incremental vibrato, balanced vibrato/slide-speed strength in lower
 octaves
-gentle vibrato-amplitude setting: waits till vibrato returns to zero-crossing,
 so avoids pitch-drifting
-Instrument load/save support (each instrument has its own individual table)
-Runnable and playable tunes can be exported directly from TEDzakker editor just
 like workfiles
-Built-in cheatsheet and built-in tutorial/example-tune for all player-types

Comparison of player-types:                 (Full)
---------------------------           Extra Normal Medium Light Demo  Bare
Multispeed Entry-Point ................ X ... X(Points to the singlespeed-call.)
Multispeed selectable in Inst.Tables .. X ... X
No frameskipping to reduce rastertime . X
 Note-volume support at frameskipping . - ... X .... X
Soundstart 1ms short whitenoise-click.. X ... X .... X ...   ... X
 Soundstart-click volume-setting ...... X ... X
Tempoprogram / funktempo support ...... X ... X .... X
Subtune-support ....................... X ... X .... X ... X
 Subtune-jump support ................. X
Main-volume simulation ................ X ... X .... X ...   ... X
 External main-volume setting ......... X ... X .... X ...   ... X
 Main-volume fade-out support ......... X ...   ....   ...   ... X
Mixing modes (average/louder/prio.) ... X ... X
Synchronization / Phase support ....... X ... X .... X ...   ... X
Packed NOP support (compressed patt.) . X ... X .... X ... X ... X
Note-column effect support ............ X ... X .... X ... X
Orderlist-sequence FX support ......... X ... X .... X ... X
 Transpose-effect support ............. X ... X .... X ... X
Detune-support ........................ X ... X .... X ... X ... X
Note-OFF table-indexes ................ X ... X .... X
Instrument-table delay-cmd support .... X ... X .... X
Note-volume fade support (envelopes) .. X ... X .... X ...   ... X
Low-frequency 'noiseloop' bass sounds . X ... X
Portamento and Vibrato support ........ X ... X .... X ... X ... X
 Vibrato-restore,Incremental,GentleVib. X ... X
Balanced slide/vibrato in low octaves . X ... X
Size of player-code in bytes (Plus4)...$955..$91F...$7A7..$5A9..$65C..$41B
Approximate maximal rastertime (rows)..$24...$1E....$1C...$18...$17...$11

(Those players above keep backwards compatibility to the weaker ones, except
 multispeed-operation.)
(You can customize a player by setting individual features in player.asm and
 reassembling.)
(The player-type rastertime/size and enabled features can also be seen in the
 menu-screen.)
(On Commodore16 subtunes are not supported for any player-type.)
(When no mixing mode support in a player, 'louder' mixingmode is available only:
 louder channel wins)
('Demo' player-type is created for the usual needs of demos and sound-extras
 keeping size/time down.)



II. Usage of the Editor:
========================


 First, let's start with a little but important info: In case you get a freeze
due to some unreliable hardware, whatever, you can reset the machine and
restart TEDzakker with SYS 4109 on Plus4 and C16, or SYS 2061 on C64, hopefully
keeping your music data untouched. In PC-version use Shift+F9 for safe-restart.

 TEDzakker starts with a menu where you can perform many tasks: load/save
workfiles and instruments, export runnable and playable code (to include in
programs), turn on HerMIDI to receive MIDI-notes, load example-tune.
 Press the keys 1..E or cursor keys to select options. +/- and cursor-left/right
keys can modify values in menupoints (e.g. relocation target-address, zeropage),
RETURN/Enter can launch the menupoints. Press F8/Esc/RunStop to exit menu, and
press F8 (HELP/F7 key on real Plus4) in the editor to bring back menu.
 Advice: You'd better save your tune as 'Workfile' before any other
         disk-operations, to be on the safe side.
 Note: C16 version doesn't have a menu due to memory limitations. Press HELP(F8)
       key to load, C=+F8 to save workfile.

 The MIDI (HerMIDI) support is not as fully-functional yet as it is in
SID-Wizard. You can play monophonic notes with automatic legato where notes
overlap in time, no polyphonic mode exists yet. There is no concept of channels,
so TEDzakker receives note-events on all channels. Also, you can select
instruments, and type notes by MIDI-keyboard, but that's all for now about MIDI.

When you enter the Editor the screen layout might be familiar to you, it's
similar to SID-Wizard.
 The biggest difference is the vertical Orderlist at the left-hand side, which
could be put there thanks to the few amount of TED channels (2). If you still
prefer the horizontal orderlist, check out tedzakker-horiz.prg. (The orientation
can be changed at build/assembly-time, see later.)
 At the bottom you can see author-info, plus on its right-side the first letter
of the editor's player-type, which the opened music was composed with.
 In the middle at the pattern-editor you can edit 2 patterns simultaneously
which you most probably select by pressing RETURN in orderlist-positions. Each
pattern has 3 columns: Note, Instrument/FX, FX
Prepare in advance that composing for only 2 channels is quite a challenge and
needs a prepared mind and some practice, but well over-thought arrangements can
still give a complete music experience. I abandoned the idea of virtual 3rd
channel which is used in some players (e.g. KnaeckeTraecker's) as I think the
human brain's combinational abilities can't be substituted by machine-code, and
3rd channel would take extra memory anyway, despite being heard only
occasionally at short times when one of the main channels (unlikely) doesn't
play any note.
 To the right you can see the instrument-editor. There are no common numeric
settings (except instrument-name at the top), all parameters of the instrument's
sound will be set frame-by-frame in WF/FRQ/VOL tables. (See in 'Music Data'
section.)
 The numbers at the very top (first screen row) represent the following
informational values:
SUBT:currently edited subtune, PT:currently selected pattern on channel,
     I:currently selected instrument on channel,
FS:framespeed (single-/multispeed), SP:speed/tempo on channels, O: currently
   selected octave for piano-keys

 I prepared some VICE .vkm files (find them in subfolders of this folder), they
could make the composing in VICE easier by enabling PageUp/Down and Ins/Del,etc.
(To use the .vkm files, copy them to /usr/lib/vice/PLUS4 folder on Linux, or
VICE data folder on the different platforms, but you'd better back-up the
original files before overwriting them.)
However, I advise to use real machines, they sound so much cleaner...
(VICE 2.4 sound emulation has a little flaw at the moment: you can hear
ultrasound and $3FE, which are inaudible on real Plus4/C16. Apart from this it's
okay, but you may try Yape too, which has sound probably closer to the real
machine but key-layout might be less convenient.)

There's a built-in cheatsheet in TEDzakker (C=+H in editor), but here's a more
complete list about the keyboard-commands (nearly identical to SID-Wizard's)...
(Highly advised to watch with monospace character set for proper identations.):

a.playback:
-----------
PlayBegin  F1 - play from beginning
PlayMark   F2 - play from playmark (that's put into orderlist
           by Shift+SPACE / C=+SPACE)
PlayPatt.  F3 - play pattern (looped)
Stop/Cont. F4 / RUNSTOP - stop or continue playback (stop-mode: when rasterbar
            is red, you can jam on piano keys)
PlayPos.   Shift+SPACE in pattern-window plays patterns from current cursor-row
PutMark    Shift+SPACE in orderlist puts playmark at cursor-position on both
            channels (C=+SPACE: only one)
FollowPlay Use C= (CBM) key together with F1..F4 / RUNSTOP in order to initiate
            follow-playback.
AutoFollow C=+ESC    toggles Auto-follow mode, so you don't need to press C=
            with Function/STOP-keys.
ToggFollow Shift+ESC toggles follow mode anytime
FastForwrd ESC key   does fast-forward while held down
MuteUnmute Shift + 1/2 mutes/unmutes channel1 or channel2

b.navigation
------------
GoPattern   F5 / Shift+P - go to Pattern   (F5 toggles Pattern / Orderlist if
             already in there)
GoOrderlst  F6 / Shift+O / * - go to Orderlist (F6 toggles Orderlist / Pattern
             if already in there)
GoInstrum   F7 / Shift+I - go to Instrument (F7 toggles Instrument/Pattern if
             already in there)
             But of course you can simply navigate between parts of the screen
             easily by cursor-keys thanks to the vertical orderlist.
Tabulate    CTRL (TAB in VICE) and Shift+CONTROL can be used to move faster
             between windows/panels/tracks
GoToMenu    F8 (HELP/F7) - go to Menu (and return from menu)
DisplayHelp C= + H - displays Help till the keys are held down (permanent help
             can be called from menu)
PageUp/Dn.  / and Shift + / (PageUp/Down in VICE) can be used to go faster than
             cursor-keys.

c.selection
-----------
SelectInstr. + / - keys select instrument for jamming/editing
SelectPatt.  Shift +/- selects pattern to edit in pattern-window
SelectInst2  RETURN in Pattern on instrument-numbers selects and goes to the
              instrument
SelectPatt2  RETURN in Orderlist selects patterns, Shift+RETURN selects only one
              channel's pattern
SelectOctave C= + 0..9 selects octave for jamming / entering notes
IncDecOctave C= and + / - increments/decrements octave
SelectSubtun C= and . / , selects Subtune

d.editing
---------
ToggleJamEdit SPACE - toggles editing / jamming modes (cursor flashes faster in
               editing-mode)
PutNote       Q..P,2..9,Z..M,S..L keys are the actual 'piano' keys to put notes
               into patterns or jam them
DeleteNote    A or 1 keys deletes the note at cursor-position in edit-mode
WriteHexValue 0..F keys can be used in orderlist, pattern instrument/fx column,
               and instrument-tables
PutNoteOnOff  RETURN / Shift+RETURN in pattern puts Note-OFF or Note-ON
PutSlide      Shift + U / D puts slide-up/down into note-column of pattern,
               hex-value can be typed, 0 removes
PutVibrato    Shift+V puts vibrato into note-column of pattern, hex-value can be
               typed, 0 removes vibrato
PutLegatoSync Shift + L / S puts permanent legato or SYNC-mode in note-column,
               C= + L / S turns them off
PutPortamento Shift + T puts tone-portamento into note-column, speed can be
               typed as hex-value, 0 removes
DeletePattRow C= + DEL deletes a whole row without moving the rest below (unlike
               DEL and Shift+DEL)
SetPattLength C= + RETURN sets pattern-length pressed on a pattern-row
TransposePatt Shift + Q / W transposes pattern from cur.pos. a semitone up/down,
               C=+Q/W: octave up/down
CopyCutPaste  C= + C / X / V copies orderlist-sequence or pattern from
               cursor-position, and instrument
              (Cut/Copy/Paste functions are not included in C16 version due
               to memory limitations.)
CopyAreaEnd   Shift + C can be used in orderlist/pattern to set end of copied
               area (C=+C set its start before)
NameInstrum.  Shift + N - Name instrument (RETURN/ESC/cursor-down to exit from
               here)
NoteOffIndex  Shift+SPACE in instrument-tables puts/removes a Note-OFF index at
               cursor-position
TableMultiSpd Shift+M in instrument tables enables/disables multispeed-mode of
               distinct WF/FRQ/VOL tables

e.settings
----------
SetAutoAdvance Shift+A toggles auto-advance of cursor after typing note/value
SetFrameSpeed  Shift + F / G increments/decrements framespeed (1...8)
SetMultiSpeed  C= + F sets multispeed-mode to be restricted at border-area
SetFullJamMode C= + J - toggles full/partial jam-mode for SPACE (in fulljam mode
                no hex.values entered)
SetInsNoteMode C= + N toggles note/numeric entry and display mode in
                instrument-table

f.file-dialog
-------------
ReadDirectory F1 - Read/Re-read directory (in 'save'/'export' dialogs it's not
               done automatically, press F1 there)
NextDirPage   F3 - If the directory doesn't fit into one page, you can list the
               next page of it by F3 (Page-Down)
SelectField   CTRL (TAB in VICE) - use it to navigate between filename /
               author-info / filelist fields
SelectFile    RETURN - pressing RETURN in the file-list (after selecting by
               cursor-keys) uses that entry as filename
ReturnToMenu  F8 / STOP / ESC will return to the menu
(If an error occurs, it's displayed at the bottom of the screen. You'll be
               prompted to press any key in that case.)
(As you've probably guessed, you can edit the author-information only in
 'save'/'export' file-dialogs before saving.)
(C16 version doesn't have a complete file-dialog. Press RETURN to list directory
 or enter load/save names directly.)



III.Music Data
==============


(I don't include examples here, you can see a lot of them in the example tunes.)
(Commodore16 version doesn't allow patterns/orderlists bigger than $20 rows,
 instrument-tables bigger than 15 rows, and more than the amount of patterns,
 instruments that were mentioned in the features: max. 8 patterns and 6
 instruments.
 So don't try to load bigger music made in Plus4/C64 trackers or you'll get
 corrupt data as a result. One example-tune called 'example-bare.tzw' works for
 C16 version, as it fits into the aforementioned strict limitations.)

 In general, Normal and Extra players can produce lower notes, than what's
officially possible by TED (note A-2 or 108Hz).
This trick comes from the fact that the Noise-waveform on channel2 loops above
a certain pitch, and resembles more to a thin bass sound than white-noise.
(Similar to clavinet/slapbass/picobass sounds...got the idea?)
 I mapped the note-range C-0..G#2 to this 'noiseloop'-waveform (as I call it)
so you can easily create melodies with it.
Though the musical pitch is not always precise and is so thin that an
octave-doubling unisono on the 1st channel comes handy in cases... But at least
it adds some bass range to the TED...

Let's see the meanings of numeric values you can enter into orderlists,
patterns, and instrument-tables: $FF is the 'Jump' command everywhere
(orderlist, instrument-tables), and the value just following it represents the
target of the jump.


a.Instrument-table values:
--------------------------
  The commands entered into instrument-tables below each other are executed
 frame-by-frame when a note starts with the selected instrument. The current
 row of execution is shown on the screen (with "<") when you play a note with
 the instrument (piano-keys). The exception on the run-order is when you use
 $FF jump-command or you release the note ('---' in pattern): If a Note-OFF
 index was specified for a table by Shift+SPACE, the execution goes there.
 (That's useful for example to model a 'Release' phase of ADSR envelope in
  VOL-table.)

  As already mentioned in the keys-section, Shift+M can be used in
 instrument-tables to toggle whether they're executed on
 multispeed-framespeed-calls too. So e.g. if you make a 2x framespeed tune,
 but you don't want the volume-envelope go faster, in normal/extra players
 it can be set to 'single'-speed. Actually that's the default value for VOL
 table, while WF and FRQ are set to multispeed-mode by default (a 'square'
 shows up at table headers)

 Of course the features above don't apply to all of the playertypes. On top of
 that, Commodore16 version of TEDzakker has only 15 rows in its
 instrument-tables, we have to deal with that.

 00 is the 'END' command, the execution of instrument table ends there. More
 ends can be given for an instrument, which makes sense for Note-OFF indexes
 (or table-jumps)...

 01..0F is 'delay'/'wait' command in each table (WF/FRQ/VOL), and it delays 1..F
 frames (screen-refresh intervals). (The not-listed value-ranges shouldn't be
 used as they're are kept for upcoming expansions of the player.)

 WF (waveform-table): (Attention: Noise waveform only makes sense on 2nd
 channel! Don't be surprised if it's odd on channel1.)
 --------------------
 ($10 SYNC-bit creates some metallic sounds such as sync/ringmodulation ones on
  C64)
 20..2F : Pulse waveform (50% pulsewidth / duty cycle) with duration 00..0E
          frames; or $2F: start with 'short 1ms clicknoise'
 30..3F : Pulse waveform + SYNC (synchronizes/initializes the oscillator at
          every player-call / frame / multispeed-frame)
 40..4F : Noise waveform (only on 2nd channel. 1st channel also sets it but not
          the frequency of channel2)
 50..5F : Noise waveform + SYNC (synchronizes/initializes the oscillator at
          every player-call; has stronger effect in VICE)
 60..6F : Silence (switch off waveform to put gaps in the sound for
          chopping/staccatto, etc.)
 80..FE : Pulse waveform + PHASE (delays the counter/oscillator by $00..$7E * .
        (If you use different PHASE between channels identical in pitch, you can
         create some non-50% stable pulsewidth sounds)
        (To simulate pulsewidth-modulation, slight detune/vibrato effect on one
         of the channels is the preferred cleaner way.)
 2nd Nybble in details: 1..E: defines duration of the current WF-row in frames
            F: in first row of WF-table adds short circa 1ms whitenoise-click
               to the sound then sets waveform of 1st Nybble

 FRQ (frequency/pitch table): (remember? 00:END, 01..0F: wait/repeat, FF: jump)
 ----------------------------
 10..1F : Pitch-Slide Up (the same number as Slide-Up pattern-FX)
 20..2F : Pitch-Slide Down (the same number as Slide-Down pattern-FX)
 30..3F : Detune Upwards (permanent until 0 detune is set, good to create some
          chorus effect between identical channel-notes)
 40..5F : Relative note-shift upwards (for arpeggios/chords)
   60   : Incremental vibrato. Next value below holds: rate in 1st Nybble,
          increment in 2nd
 7F..61 : Relative note-shift downwards (for arpeggios/chords)
   80   : Vibrato. Next value below it holds: rate in 1st Nybble, amplitude in
          2nd Nybble (Don't use $00 value because it means end of table!)
 81..FE : Absolute pitch: $81..$F8:note-pitches of C-0..H-9,
                          $F9..$FE:direct TED pitches $3F9..$3FE

 VOL (note-volume/ADSR table):  (00:END, 01..0F: wait or repeat fade, FF: jump)
 -----------------------------
 10..1F : Note-Volume Fade-In (Increase), like 'Attack' of ADSR, but a
          volume-setting should preceed it
 20..2F : Note-Volume Fade-Out (Decrease), like 'Decay'/'Release' of ADSR, but
          volume-setting should preceed it
 30..3F : Set Note-Volume with 'Priorized' mixing-mode (the common volume is
          strictly set by this channel)
 40..4F : Set Note-Volume with 'Louder' mixing-mode (the common volume is set
          by the louder channel)
 50..5F : Set Note-Volume with 'Average' mixing-mode (the common volume is the
          average of channel 1 and 2)
 (When a note-volume reaches 0, its waveform is disabled and it doesn't take
  part in the mixing thereafter.)
 ($4x 'louder' mixing mode has priority over $5x 'average' mode. If both
  channels use $3x, 2nd channel is priorized.)


b.Pattern-values
----------------
 00 is the 'NOP' (no-process) value for the patterns, it's an empty note/ins/fx
 that does nothing ('...')

 The FX-values in Note-column are accessible through piano-keys and
 Shift+L/U/D/T/V/S, see above at keys-section.
 (Shift+L turns on permanent legato mode until it's turned off by placing
  legato-off with C=+L.)

 Instrument-column can select 01..3E instruments,  $3F value is temporary
 legato, just for one row.
  Above $40, instrument-column can perform the same effects as the last
 FX-column:

 Effect (FX) column Pattern-Effects: (Don't use any values above $BF, that's
 -----------------------------------  kept for pattern-compression.)
 00..0F : Duration of current pattern-row (given in frames)
 10..1F : Pitch-Slide Up (same number as Slide-Up in instrument-table, they can
          clash)
 20..2F : Pitch-Slide Down (same number as Slide-Down in instr.-table, they can
          clash)
 30..3F : Portamento (automatic slide to the note on the current pattern-row)
 40..4F : WF-table jump (e.g. selecting different phases or altering
          waveform/SYNC from pattern)
 50..5F : Note-Volume (overriding note-volume. Only extra/normal/medium players
          can perform it on the same row as the note)
 60..6F : VOL-table jump (e.g. setting different note-volume in light/bare/demo
          players on the same row as the note)
 70..7F : FRQ-table jump (e.g. using a different arpeggio-chord inside the same
          instrument)
 80..8F : Vibrato Amplitude (extra/normal has gentle-vibrato setting avoiding
          pitch-drift, can clash with instrument-table)
 90..9F : Detune upwards (permanent until detune of value 0 is set)
 A1..AF : Main Volume setting 0..F (no total silence, that saves some
          rastertime, but silence can be made in other ways)
 B0..BF : Track-tempo setting 0..F

 (As you can see there's no setting for vibrato-rate. There's a default rate of
  2 in 'extra' player, but if there's a vibrato-rate given in FRQ
  instrument-table, that will be used. It is necessary to give vibrato rate in
  other players.)
 (If you don't set any tempo in patterns/orderlists, the default tempo-value
  set at tune-initialization is 6.)
 (Main volume 1..F is mapped to the 0..8 values of TED, so mostly you get
  difference at every 2nd value when you fade.)


c.Orderlist-values: (Sequences for channel 1 and 2)
-------------------
 $00 is the 'END' value, playback ends there. (Note decay / fade-out and
     instrument-table execution still continues.)
 $01..$64 are the pattern-numbers to be played in order as they're given in
          orderlist channels (theoretical limit is $7F)

 $8F..$80:Transpose Down the channel by -1..-15 semitones (musical key-change)
 $90..$9F:Transpose Up the channel by 0..15 semitones (musical key-change)
 $A0..$AF:Main Volume setting 0..F (the same number and same effect as the
          corresponding Pattern-FX)
 $B0..$CF:Tempo / Funktempo / Tempo-Program setting $00..$1F (consequent
          tempo-settings program the funktempo/tempo-table)
 $D0..$DF:Detune upwards (permanent until detune of value 0 is set, useful to
          save memory by using the same patterns)
 $E1..$EF:Main Volume Fade-Out with speed 0..F (only in 'extra' player, from
          1 second up to cca 18 seconds)
   $FF   :Jump to orderlist position (given in next row) on the channel (if you
          type $80..$8F as jump-target, it jumps subtune)
 (Tempo-program can have maximum 8 entries, but that should be quite enough.
  Don't use consequent $BX more than 8 times.)



IV. Saving, Exporting, Usage of the exported Tunes:
===================================================

Don't forget anytime to save the tune as 'Workfile' (.tzw.prg) before exporting
it. Edit the author-info field by TABbing to it, everything before a ':' is the
author-name, everything after it is the title in the exported .ted.prg file.
Exported tunes can't be loaded back (yet). (Instruments can also be saved
individually, their extension will be '.tzi.prg'.)

 There's a convenience function in the menu to 'Export Runnable' which
automatically creates a starter-program and relocates the tune to $1300, then
saves all together as a '.ted.prg' file you can simply load and run/play later.
(It supports multispeed tunes, but doesn't have subtune-change feature yet, only
 the first subtune will be listenable.)

 To include a tune in programs/demos/etc., you first have to relocate it to the
desired address with +/- keys in the menu at 'Export Playable' menupoint, and
then press RETURN on the same menupoint to actually export it as 'playable'
(.tzp.prg). Now you can also modify the location of the 2 player zeropage-bytes.
 The exported playable can be initialized and played by the conventional scheme,
where 'PlayerAddress' is the relocated tune's base-address (load-startaddress):
PlayerAddress+0 : Initialize the player, Input: Subtune-number in Accumulator
                  ($00..$0F) (light/medium/normal/extra players)
PlayerAddress+3 : Play the tune - this 'Single-call' should be called every PAL
                  video-frame (screen-refresh / v-blank period)
PlayerAddress+6 : Multispeed-call - normal/extra players provide a distinct call
                  for multispeed, it runs only instrument-tables, while
                  tempo/pattern/orderlist advance and note/instrument-starts
                  are handled in 'single' call
PlayerAddress+9 : MainVolume set/fadeout - if Accumulator = $00..$0F , the
                                            main-volume can be set externally,
                  if Accumulator = $10..$FF , fade-out of main-volume can be
                  initiated (1..18 seconds)



V.Building/Assembling TEDzakker
===============================

 The source-codes (tedzakker.asm, player.asm, HerMIDI-Plus4.asm) are in '64tass'
format. I used 64tass v1.51.584, and any never version should be able to
assemble TEDzakker binaries with all the preprocessor-directives.
 The Makefile handles all the assembling process (likely to be given in Linux),
but if you don't have make, the TEDzakker binary with default settings (Plus4
target, Normal-player, vertical orderlist) can be assembled by the following
command-line:
64tass tedzakker.asm -o tedzakker.prg

There are some definitions that can be given from command-line with '-D'
arguments (see in Makefile, how):
-D MACHINE=0..2               ( Values:  0:Commodore 16,  1:Commodore Plus4,
                                2:Commodore 64 )
-D PLAYERTYPE=0..5            ( Values:  0:Normal, 1:Medium, 2:Light, 3:Extra,
                                4:Bare, 5:Demo )
-D HORIZONTAL_ORDERLIST=0/1   ( Values:  0:Vertical Orderlist,  1:Horizontal
                                Orderlist )

 The finer details for MACHINE can be found in 'tedzakker.asm' if you want to
refine features of Plus4/C16/C64 versions. And details for PLAYERTYPE can be
found in 'player.asm' in case you need to customize or create a new
player-type, maximum amount of instruments/patterns/subtunes can be adjusted
in 'player.asm' as well.



VI. Closing words:
==================

I wish you a nice experience with TEDzakker by exploring the yet scarcely
utilized capabilities of TED. In case you need further help don't hesitate to
reach me through PM at CSDB.

February 2023
Hermit Software Hungary (Mihaly Horvath)




================================================================================
ToDo:
-----

to add to player:
-----------------
-volume-gap (auto-staccatto)
-table-restart ON/OFF per note-start
-common table-speed (by X0..XE in WF-table?)
-tempo-program setting(teaching) also in pattern? (makes sense for on-the-fly
 setting)
(-light/bare without sync./phase support should have at least non-sync sound
 instead of silence there, for pulse-waveform)
(-no-vibrato/no-portamento players may play plain note in place of
 vibrato/portamento, for kinda forward-compatibility..)

to add to editor:
-----------------
*subtune-change feature (+/- keys) in EXEstarter
-inst-table/orderlist $FF-jump automatic corrections for insert/del before/after
-C=+U/E to find Empty/Unused pattern-number in orderlist
-step-highlighting in pattern position-numbering
-playable/runnable-tune import in menu
-colorfade when switching pages, colorthemes
-SWM/MID converter?
(-overwrite notification in savers - for VICE emulator without TDE)
(-handle workfiles not fitting in memory on C16-version (using CHRIN instead of
 standard LOAD? different decompr.alg.?))
(-PICtune PIC12F509/ATTiny microcontroller-based sound-expansion support)
================================================================================
