-*-mode: org-*-

* Introduction

     ___              ____  ___   __    ___        __    ___   2
    /____ /___/ /\  /  /   /___\  __\  /     /__/ /__\  /___\   
     ___/  __/ /  \/  /   / \    /___\ \__  /  \  \_   / \        ** preview **



Syntracker 2 aims to be a (free) MIDI / Audio sequencer. 

Its interface resembles classic 'tracker' software like 
Chris Huelsbeck's "Soundmonitor" (on Commodore 64) or 
Karsten Obarski's "Soundtracker" (on Amiga 500).

Its also the spiritual successor to my old Amiga trackers 
'Art Of Noise' (aka Chorus) and 'Syntracker' :)


* Authors

  - Syntracker is (C) 1990/2006 - 2011 by Bastian Spiegel <bs@tkscript.de>

     - Pattern font is (C) 1994-2011 by Gerd Feldkirch <gerd@feldir.ch>

  - Additional credits:

     -            'eqxmms' is (C) 2002-2006 by Felipe Rivera <liebremx at users.sourceforge.net>
     -            Freeverb is (C) 2000-2011 by 'Jezar at Dreampoint' et. al.
     - DAV 303 Bass Filter is (C) 1998-2003 by David A. Bartold, Tim Janik, Andy Sloane, and Hal Chamberlin.
     -      6 Stage Phaser is (C) 1998      by Ross Bencina <rossb@kagi.com>
     - DSF BLIT oscillator is (c) 2002      by Emanuel Landeholm <emanuel.landeholm@telia.com>
     -           PortAudio is (c) 1999-2006 by Phil Burk, Ross Bencina et. al.
     -           Freetype2 is (c) 2001-2008 by David Turner, Robert Wilhelm, and Werner Lemberg.
     -                 SDL is (C) 1998-2011 by Sam Lantinga (et. al.)
     -                zlib is (C) 1995-2011 by Jean-Loup Gailly and Mark Adler (et. al.)
     -              OpenGL is (C) 1992-2011 by Silicon Graphics Inc. (SGI) / Khronos Group


* Features

  - Event-based sequencer engine
     - 'tracker' style interface
     - song is presented as a continuous sequence of events
     - up to 256 channels
        - individual orderlist per channel
        - up to 256 tracks per channel
        - up to 256 patterns per channel
     - up to 61 instruments
        - instruments can play on any track
     - configurable track columns (up to 32 controllers)
        - patterns can contain graphical envelope cells ("BAR" cell style)
     - zoom in/out for detail step editing
     - microdelay controller
     - retrig controller (thanks to knl for helping me come to a decision about this)
     - sequencer resolution is 24..768 PPQ, 1..500 BPM
     - up to 5 note controllers per track (for chords)
     - monophonic auto-arpeggiator (for c=64 style chords)
     - note slide (maps to MIDI portamento controller)
     - detail editing of controller values (usually represented as 2-digit hex number but internally stored in 32bit floating point format)
     - up to 3 simultaneous macros per track
        - unlimited number of automations per macro
        - macros can be attached to instruments
        - macro automations can be free-running and/or synced to note-ons
        - macros usually temporarily replace a controller value but they can be configured to replace controller values permanently.
           This makes it possible to implement classic sound/protracker effects like '1', '2', 'A', 'E1', 'E2', 'EA', 'EB' as macros.
     - pattern, envelope, and pianoroll editor views
     - keyjazz takes the current step's controller updates into account
     - support for song-markers to group orderlist entries (across channels)

  - MIDI recording and playback
     - support for multiple output devices
     - user-definable parameters/controllers
        - CC, RPN, NRPN, and (in future releases) SysEx
     - special support for Korg Radias synth
        - (almost) total recall
        - incremental, realtime sysex voice param updates
           - additional controllers
           - drum timbres can be played like regular voices (i.e. no fixed note)

  - Support for VST 2.x instruments and effects
     - special support for "V2" multitimbral synthesizer

  - Builtin sampler engine
     - unlimited number of samples per sample bank
     - fast envelopes/LFOs
        - attack/sustain/release envelopes based on cubic bezier splines
        - envelope/LFO speed/intensity can modulated using controllers
        - refresh rate is 1000 Hz
        - volume, panning and frequency are interpolated per-sample
     - sample loops:
        - unlimited number of loops
        - loop duration can be independent of pitch
        - simple register-based VM for advanced loop control
     - sample offset/repeat length/loop index can be modulated after note-on (amongst other params)
     - controller updates can affect only the last started voice or all generator voices
     - granular/wavetable mode
        - for "chiptunes" or 90ies-style 'time-stretching'
     - waveforms can be shared between samples
     - builtin sample/waveform browser with preview feature
        - supports Akai .wav extension (loops, base note, ..)

  - Waveform editor
     - Basic editing functions (cut/copy/paste, reverse, normalize, fade in-out, ..)
     - Intelligent selection zooming
     - Cycle-edit mode (for wavetables)
     - Freedraw mode

  - Modular audio FX / routing engine
     - built-in basic building blocks (oscillators, waveshapers, filters, equalizer, compressor, reverb, delay)
     - support for VST FX
     - sample exact (slow but more accurate) or block-based
        - can be mixed per module and/or per input port

  - Support for sub-songs and procedural waveforms
     - each sub-song can have a user-definable waveform rendertarget
     - procedural waveforms can automatically be synthesized when loading a song

  - Most editor functions are (optionally) accessible via keyboard shortcuts

  - Extensible, chunk-based file format

  - Portable
     - custom, OpenGL based user interface
     - modular, plugin-based architecture
     - experimental Linux port available on request (no MIDI, ATM)



* Requirements

  * A rather fast x86 PC running Windows XP/Vista/7 (an experimental Linux port is available on request)

  * [win32] Recommended: A low latency ASIO driver. A buffersize of 128 samples @ 48000Hz sample rate seems to work fine.
     - Same goes for the Linux version. Onboard soundchips probably won't "cut it" (at least not the ones I tried)
        but I've made some good experience with the Native Instruments Guitar Rig interface, for example.

  * [linux] Recommended: ALSA 

  * OpenGL graphics accelerator with up-to-date drivers (must support FBO extension)



* Installation


** Win32 (basic)

  1) Run "st2.exe" to start the application

      (note) The default configuration uses SDL audio output which has a rather high latency and does not support recording / audio-input


** ASIO setup (win32)

  (note) follow these instructions if you have a low latency soundcard with ASIO (or ALSA, on Linux) drivers

  (note) if your ASIO soundcard only has 2ins / 2outs, the default configuration should work out-the-box (after enabling ASIO output, that is!)


  1) Open a console (cmd.exe, MSYS shell, etc.), make sure that the scrollback buffer size is set to ~3000 lines (to be safe)

  2) Change to the ST2 installation directory and run "st2.exe" in that console

  3) Open the file "config.tks" in a text editor.
      - update the "audio_device_index" field. See console output of "st2.exe" for the list of available devices
         (note) make sure to select an ASIO device !
      - update the "audio_num_in" field to select the number of input channels (must be less or equal to the number of entries in the
         "audio_mixer_levels" array!)
      - update the "audio_out_offset" to select the master output stereo channel pair (audio_out_offset+1 will automatically be chosen as
         the right master output channel)
      - last but not least, enable ASIO audio I/O by turning off SDL audio (simply set "b_audio_sdl" to false)


** MIDI setup (win32)

  1) Open a console (cmd.exe, MSYS shell, etc.), make sure that the scrollback buffer size is set to ~3000 lines (to be safe)

  2) Change to the ST2 installation directory and run "st2.exe" in that console

  3) Open the file "config.tks" in a text editor.
      - update the "midi_in_devicenames" array to include your master keyboard device (see console output for the list of available devices)
      - update the "midi_in_master" field and set it to the device index that matches your master keyboard



* Status

  * This software is still in its "alpha" stage. 

     - Some features have not been implemented, yet (or they simply cannot be edited via the UI).

     - Some features are work-in-progress 

     - Please save your songs frequently because this software has not been tested extensively, therefore crashes may occur!
        - It it strongly recommended to keept he "crash_autosave" option enabled. In case of a crash, your work will then automatically
           be saved to a backup file.

  * Your feedback would be very appreciated !



* Tips'n'Tricks

  - There are a lot of keyboard shortcuts. use them! 
     - All dialogs that support triadic "lctrl-x" accelerators will show you a help dialog if you do not type the third key fast enough

  - Most dialogs can be closed by simply (LMB) clicking outside the dialog area, or by (RMB) clicking into the window title bar,
     or by pressing "lctrl-x c". Finally, you can click on a tooltip to close a dialog (if you are fast enough) although I have not decided
     whether this is a bug or feature ;)

  - Most of the number-style input fields have an advanced editor dialog that is activating by RMB-click.
     - In addition to that, it is possible to change values in a dial-like fashing using RMB-drag.
     - Last but not least, you can also enter simple expressions (like 10+2, $10*4, ..)
     
  - You can use markers to break down a song into parts
     - When "Song -> Auto-sync length" is enabled, the song length and repeat length will automatically be set to the last marker.
        - (note) Use "Song -> Set song length , Repeat Offset, Repeat Length" to override song length and repeat
     - When "Song -> Marker play-mode" is enabled, pressing SPACE will loop the current part (instead of the the current pattern)

  - It is usually not necessary to manually enter note-offs. The CTL_DUR controller can be used to make the replay automatically send a 
     note-off after $xx ticks.

  - The format of the retrig-controller is $xy, where x determines the tick delta and y is used to select the number of repetitions

  - The audioinstrument retrig-mask parameter/controller expects a bit-wise OR'd mask:
      $01 : Restart volume ADSR
      $02 : Restart panning ADSR
      $04 : Restart frequency ADSR
      $10 : Restart volume LFO
      $20 : Restart panning LFO
      $40 : Restart frequency LFO

       (so, for example, $35 would restart vol+pan LFOs and vol+freq ADSRs)

  - When using instrument macros or the monophonic auto-arpeggiator, keep the following in mind:
     - The monophonic auto-arpeggiator uses macro-player #1
     - Instrument macros are played via macro-player #3

  - When editing macro automations, keep in mind that the waveform editor has a freedraw feature

  - Use the "File -> Optimize" functions to get rid of unused patterns, generators, instruments, and waveforms.
     - A pattern is considered unused if it is not used in any orderlist
     - A generator is considered unused if it has no instruments
     - A waveform is considered unused if it is not assigned to any samples/instruments

  - When calculating procedural wavetables using subsongs, keep in mind that the pitch of an oscillator is the number of cycles per second:
     If the samplerate is 48000 for example, the correct pitch for a 128-samples cycle is 375 (because 48000/128 = 375)

  - Since there is not much documentation, please check out the "test" songs. They may not sound great but will give you an idea how to
     achieve certain things.



* Keyboard shortcuts

Keyboard/mouse controls:

(us keyboard layout, german layout in () parenthesis)

** Views

  tab               : Toggle orderlist/envelope/pianoroll view
  escape            : Close current dialog
  F3                : Manage generators
  F4                : Manage instruments
  F5                : Manage macros
  F6                : Manage track layouts
  F7                : Manage waveforms

  Note: 
    The view related 'F' key functions are also available as easier-to-access-but-harder-to-remember triadic key combos (see below)
    
** Pattern editor | Cursor movement

                  down : Move cursor down one step
           rshift-down : Move cursor down 4 steps (note: lshift-down is reserved for block selection)
            lctrl-down : Move cursor down and snap to 16 step grid
                          (note) the grid size can be adjusted in "config.tks"
     lctrl-lshift-down : Move cursor to next marker (+select orderlist region)
                    up : Move cursor up one step
             rshift-up : Move cursor up 4 steps (note: lshift-up is reserved for block selection)
              lctrl-up : Move cursor up and snap to 16 step grid
                          (note) the grid size can be adjusted in "config.tks"
       lctrl-lshift-up : Move cursor to previous marker (+select orderlist region)
              pagedown : Move cursor to start of next pattern
                pageup : Move cursor to start of previous pattern
                 right : Move cursor to next column/track
           lctrl-right : Move cursor to last column or first column of next track
    lctrl-lshift-right : Move cursor to next channel
                  left : Move cursor to previous column/track
            lctrl-left : Move cursor to first column or last column of previous track
     lctrl-lshift-left : Move cursor to previous channel
               lctrl-1 : Set step advance / 1 step
               lctrl-2 : Set step advance / 2 steps
               lctrl-3 : Set step advance / 3 steps
               lctrl-4 : Set step advance / 4 steps
               lctrl-5 : Set step advance / 5 steps
               lctrl-6 : Set step advance / 6 steps
               lctrl-7 : Set step advance / 7 steps
               lctrl-8 : Set step advance / 8 steps
               lctrl-9 : Set step advance / 16 steps
               lctrl-0 : Set step advance / n steps (default "page" size, initally 16 steps)
                  HOME : Move cursor to first column
                   END : Move cursor to next column group
            lshift-END : Move cursor to previous column group
               lctrl-j : Show column selection dialog
         WHEEL UP/DOWN : Scroll 16 steps up/down
   lctrl-WHEEL UP/DOWN : Jump to previous/next orderlist entry / pattern
            MOUSE OVER : Highlight row (only for orientation)
             LMB click : Center selected row / position cursor
          LMB dblclick : Show detail editor
              RMB drag : (if mouse is over a BAR style cell): Change controller value / enter freedraw mode
              LMB drag : Select block.
                         Alternatively: If in freedraw mode (RMB drag): Delete events
             RMB click : Show context menu (if a block is currently selected)

** Pattern editor | Zoom

        lshift-US:/ DE:+ : Zoom in (-2)
  lshift-lctrl-US:/ DE:+ : Zoom in (double resolution)  
        lshift-US:{ DE:ü : Zoom out (+2)
  lshift-lctrl-US:{ DE:ü : Zoom out (half resolution)
                lshift-a : Enter step resolution (focus textfield)

** Pattern editor | Editing

          LMB-dblclick : Show detail editor for cell under mouse
                escape
              OR rctrl : Toggle edit mode
             backspace
       OR lshift-rctrl : Toggle relative shift mode (affects (lshift-)insert/delete)
             <default> : Play/insert note (note on if capslock is disabled, note off if capslock is enabled)
                delete : a) Delete current step/current ctl. event
                         b) Remove all events in selected block
          lctrl-delete : Clear current step/current ctl. event, do not shift following events
         lshift-delete : a) Delete all ctl. events of current step
                         b) Clear selected block
   lshift-lctrl-delete : Clear all ctl. events of current step, do not shift following events
                insert : Shift current ctl. events ("insert step")
         lshift-insert : Shift all ctl. events ("insert step")
             US:\ DE:< : Clear current step (current controller only)  
      lshift-DE:< US:\ : Clear current step (all controllers of current track)
               lctrl-b : Mark block start
               lctrl-e : Mark block end
       lshift-<cursor> : Quick-select block
               lctrl-a : Mark entire orderlist entry range (controller, track or pattern depending on block mode (lctrl-x b))
        lshift-lctrl-a : Select none
                          If no block is currently selected, invalidate the current orderlist selection
               lctrl-c : Copy selected block to clipboard
               lctrl-v : Paste clipboard at cursor position (replace events)
        lctrl-lshift-v : Paste clipboard at cursor position (insert events)
               lctrl-f : Detail-edit column (edit mode must be enabled)
              lshift-d : Enter default note duration (focus textfield)
             lshift-f6 : Edit track event layout
               lctrl-i : Show block interpolation dialog
             lshift-f3 : Delete all pattern events / clear pattern

** Pattern editor | Note On/Off

             US:' DE:# : All track notes off event (===)
      lshift-US:' DE:# : All generator notes off event (###)
              capslock : Toggle noteoff mode. If enabled, insert note-off events when note keys are pressed
              lshift-s : Enter default note-on velocity (focus textfield)
               lctrl-y : Toggle note on/off (if cursor is placed on a note column) or show detail edit

** Pattern editor | Replay

                 space : Play/Loop current pattern / stop replay, reset generators/controllers and goto bookmark
                          In marker-play-mode, play current part
           lctrl-space : Continue replay / stop replay and leave cursor at last replayed position
          lshift-space : Set pattern replay start offset to cursor position
                          In marker-play-mode, set marker play offset 
    lshift-lctrl-space : Toggle song/pattern replay (or start song replay)
                return : Stop replay/ Play current step. If autoscroll is disabled, queue next pattern loop.
          lctrl-return : Play/Loop current song / stop replay and leave cursor at last replayed position
               lctrl-q : Mute/Unmute current track
               lctrl-w : Toggle solo current track
        lshift-lctrl-q : Mute all tracks of current channel
        lshift-lctrl-w : Unmute all tracks of current channel
                rshift : Record pattern
          lctrl-rshift : Continue record song

** Pattern editor | Instruments and KeyJazz

       lctrl-US:[ DE:ü : Select previous instrument
       lctrl-US:] DE:+ : Select next instrument
              lshift-g : Enter instrument nr. (focus textfield)
                    F1 : Keyjazz octave down
                    F2 : Keyjazz octave up
                    F4 : Manage instruments
             lshift-F4 : Edit current instrument

** Pattern editor | Macros
 
                    F5 : Manage macros
              lshift-h : Enter macro nr. (focus textfield)

** Orderlist editor

       lshift-pagedown : Increase orderlist entry pattern nr.
         lshift-pageup : Decrease orderlist entry pattern nr.
               lctrl-. : Decrease orderlist time offset
       lctrl-US:/ DE:- : Increase orderlist time offset
               lctrl-u : Delete orderlist entry
        lctrl-lshift-u : Delete orderlist range
                          Use the range selected in the orderlist view or open a dialog window
               lctrl-o : Duplicate orderlist entry
        lctrl-lshift-o : Duplicate orderlist entries (range)
               lctrl-p : Copy orderlist range
                          Use the range selected in the orderlist view or open a dialog window
        lshift-lctrl-p : Paste orderlist range
               lctrl-d : Clone pattern and replace orderlist entry
               lctrl-n : Clone pattern and insert orderlist entry
        lshift-lctrl-n : New (empty) pattern and insert orderlist entry
               lctrl-k : Enter orderlist pattern number
               lctrl-l : Set orderlist entry duration (steps or ticks)
               lctrl-m : Toggle song marker at cursor position

    (note) If mouse is below channels, mousewheel up/down selects previous/next marker (or part)
    (note) If mouse is below channels, markers will snap to pattern starts. Otherwise they will snap to the grid.
    (note) If mouse is over a channel, dragging a marker will also move orderlist entries
           
** PianoRoll editor

             LMB-click : Set note on
      lshift-LMB-click : Set note off (black cell border)
              LMB-drag : Change note velocity or duration (up/down, left/right) 
                          (to change duration, a duration event must already exist!)
        lctrl-LMB-drag : Only change note velocity 
       lshift-LMB-drag : Only change note duration
                   RMB : Clear a note on/off event
              MMB down : Toggle (insert or remove) note on/off event(s)
               WHEELUP : Scroll piano up
               WHEELDN : Scroll piano down
           RMB-WHEELUP : Patternscroll one step back
         RMB-WHEELDOWN : Patternscroll one step forward
              RMB-drag : Seek

** Manage macros dialog

               lctrl-c : Copy selected macro to clipboard
               lctrl-v : Paste clipboard as new macro

** Common menu shortcuts

         lalt-c return : Create new channel
         lalt-t return : Create new track
         lalt-s return : Show/edit song comment
       lalt-s m return : Toggle marker playmode
    lalt-f down return : Load song
       lalt-f s return : Save song
      lalt-f up return : Quit

** Triadic keyboard accelerators

               lctrl-x : Enter triad accelerator key mode

    general:
             c         :   Close current dialog (except for pattern view)

    patternview:
             1         :   Show block interpolation dialog
             2         :   Select keyjazz instrument from current step
             3         :   Toggle mute current channel
             4         :   Toggle solo current channel
             a         :   Edit current instrument
             b         :   Change block selection mode (column,controller,track,pattern)
             c         :   Set block selection start/end or select none
             d         :   Edit macros
             e         :   Toggle pattern edit mode
             f         :   Keyjazz octave up
             g         :   Edit last edited macro automation
             h         :   Show/hide VST editor window for current instrument
             m         :   Edit metronome
             p         :   Duplicate current part (song must use markers!)
             q         :   Toggle pattern autoscroll mode
             s         :   Edit current tracklayout
             v         :   Keyjazz octave down
             w         :   Edit waveforms
             x         :   Edit instruments
             y         :   Edit generators ('z' on german kbd)
             z         :   Edit sub-songs ('y' on german kbd)
             SPACE     :   Show column selection dialog

    editmacro:
             a         :   Edit automation
             d         :   New automation
             s         :   Move automation down
             v         :   Delete automation  
             w         :   Move automation up  

    editinstrumentaudio:
             d         :   New sample
	     g         :   Edit macro
	     z         :   Edit/re-assign generator ('y' on german kbd)

    editinstrumentmidi:
             a         :   Edit user controller mapping
             d         :   Create new parameter
             g         :   Edit macro
             v         :   Delete selected parameter
	     z         :   Edit/re-assign generator ('y' on german kbd)

    editinstrumentvst:
             a         :   Edit user controller mapping
             d         :   Create new parameter
             g         :   Edit macro
             s         :   Learn new automation parameter
             v         :   Delete selected parameter
             z         :   Edit/re-assign generator ('y' on german kbd)

    managegenerators:
             a         :   Edit selected generator
             d         :   New generator
             v         :   Delete selected generator    

    manageinstruments:
             a         :   Edit selected instrument
             d         :   New instrument
             v         :   Delete selected instrument

    managemacros:
             a         :   Edit selected macro
             d         :   New macro
             v         :   Delete selected macro

    managewaveforms:
             a         :   Edit selected waveform
             d         :   Load new waveform
             v         :   Delete selected waveform

    managesubsongs:
             d         :   New sub-song
             v         :   Delete selected sub-song (if #subsongs > 1)


** SampleView controls

    lctrl-lshift-SPACE : Show all
           lctrl-SPACE : Fit selection to window
        lctrl-lshift-a : Select none
               lctrl-a : Select all
               lctrl-h : Copy selection to highlight (modifies either sampleoff/len or current loop off/len)
               lctrl-c : Copy selection to clipboard
               lctrl-x : Cut selection to clipboard
               lctrl-v : Paste clipboard at current selection start
               lctrl-r : Toggle render style
               lctrl-e : Toggle interpolation style
         WHEEL UP/DOWN : Zoom in/out
                          Select next/previous cycle (in cycle-edit mode)
              RMB drag : Scroll left/right 
              LMB drag : Mark region / autoscroll
                          Draw samples (in freedraw mode)
             RMB click : Show context menu


** BezierView (ADSR) controls

           lctrl-SPACE : Toggle show envelope
                 SPACE : Show all
                lshift : (While dragging a control point) lock angle
                  LEFT : Select previous control point
                 RIGHT : Select next control point
                  DOWN : Select previous center point
                    UP : Select next center point
               lctrl-a : Select previous control point, do not select previous center point
               lctrl-d : Select next control point, do not select next center point
               lctrl-s : Select previous center point
               lctrl-w : Select next center point
        lctrl-lshift-z : Redo
               lctrl-z : Undo
            WHEEL DOWN : Select previous control point
              WHEEL UP : Select next control point
       lalt-WHEEL DOWN : Zoom out (horizontal)
         lalt-WHEEL UP : Zoom in (horizontal)
 lalt-lctrl-WHEEL DOWN : Zoom out (vertical)
   lalt-lctrl-WHEEL UP : Zoom in (vertical)
         lalt-LMB drag : Scroll 
           WHEEL click : Lock movement to currently selected control point
          LMB dblclick : Insert new center point (+ previous/next control points)
          RMB dblclick : Delete nearest center point (+ previous/next control points)
              RMB hold : Show context menu


* Known issues

  - Audio/MIDI configuration is currently done using a textfile ("config.tks")

  - Except for this readme.txt (and the builtin tooltips), there is no documentation, yet

  - The keyboard shortcuts usually refer to a US keyboard layout
     - In future versions, the shortcuts should be configurable and there should be presets for french, german, .. keyboard layouts

  - Sometimes the PortAudio/ASIO initialization respectively opening of the stream fails (happens every ~20th. run)
    - may be an issue with my particular soundcard (delta1010lt). if you run into the same issue, please drop me a mail.

  - SDL audio is deprecated since it has a very high latency (1024 samples or more. default is 4096)

  - The piano roll editor is far from finished and should be considered an experiment (for now)

  - The macro editor is currently under construction. LFO and bezier modes have not been (fully) implemented, yet.

  - The FX / routing editor is work in progress
    - VST FX can currently not be added directly. It is currently required to add a new VST generator/instrument (which will
       then show up in the FX routing)
    - It is currently not possible to zoom in/out (for example to ease port selection)

  - The builtin VST host currently does not support VSTs that do not provide their own UI

  - The sample editor is unfinished
    - Mutex groups / multisamples can currently not by edited via the GUI

  - The .wav "exporter" is currently more a debug-feature and will be invoked the first time the song replay is stopped
    (if b_save_wav=true in config.tks)

  - External input channels (if you have a multi I/O soundcard) are currently simply being added to the mix, no audiorouting or level controls
     are available via the UI at the moment (to be precise: it is at least possible to configure input levels in the "config.tks" textfile)

  - The Linux port currently does not support MIDI (did not get around to implementing it, yet)

  - The only sample format supported by the builtin sample is .WAV. support for FLAC, AIFF and IFF is planned.

  - 'embedded' waveforms are currently always saved in 32bit floating point format (=> large module sizes)

  - There is currently no way to load or save just parts of the song (e.g. samples, instruments, ..)

  - The Korg Radias support is disabled in this release

  - The application leaks 'Thread' objects at exit (depends on the number of songs loaded/played)

  - There is no standalone player library available, yet. This is planned for 2011.

  - The application will open a console window that will display a lot of "gibberish" that can be helpful for debugging things 
     (it is advised to run the program from a shell so that it is possible to read the debug output even after the application has exited)

  - There are not any great songs to really show off the features (or simply make for a good listening). I am primarly a coder, not a musician 
     so I would be really glad if any musicians out there would be willing to help with that !



* Terminology / General program structure

  - [song]
      - stores 1..n [subsongs]
      - stores [waveforms]

  - [waveform]
      - stores sample-data (either mono or stereo)

  - [subsong]
      - stores [generators], [instrument] (references), [macros], [channels], [fx]

  - [generator]
      - associated with MIDI or audio device, or a VST instrument/effect
      - stores 0..n [instruments]
         (the instruments are mapped to indices 0..9, A..Z, a..z in a [subsong] so they can easily be
          selected in [tracks])
      - provides 1..n [voices]
      - determines the voice-allocation strategy 
         - MIDI generators always re-allocate the oldest voice (in replay terms, in practice this depends on the MIDI synthesizer)
         - Audio generators have a configurable voice-allocation strategy (oldest, lowest, highest)
      - has 0..n [params]

  - [param]
     - a generator-dependant voice parameter. 
        - a MIDIGenerator has a variable number of parameters (via user-definable MIDI CCs or NRPNs)
        - a VSTGenerator is basically a MIDIGenerator but additionally allows to map VST parameters to generator parameters
     - params have a default value range and a default presentation type
        - MIDI-style parameters usually have a 0..127 ($00..$7f) range (for example volume) or a -64..63 ($00..$7f) range
           (for example pitchbend/frequency)

  - [instrument]
      - associated with a [generator]
      - defines how to play a [voice] (the available options are generator-specific)
      - maps generator-dependant [params] to [controllers]
      - can contain a [macro]

  - [voice]
      - associated with a [generator]
      - voices are allocated during note-ons
      - actual voice behaviour depends on the [generator]/[instrument]-type

  - [macro] 
      - stores 0..n [automation]s
      - there are 62 global macros (0..9, A..Z, a..z) per [subsong]
      - each [instrument] can have a macro attached, which will start playing when a [voice] is triggered

  - [automation]
      - used to temporarily or permanantly modify [controller] values

  - [channel]
      - stores 0..n [tracks]
      - stores 0..n [patterns]
      - stores an orderlist, that determines in which order to play the [patterns]

  - [track]
      - logical grouping of 0..n [pattern] [envelopes]
      - stores a tracklayout that determines the visual presentation of the [envelopes]

  - [pattern]
      - stores 0..32 [controller] [envelopes] per [track]

  - [envelope]
      - stores 0..n delta-time encoded [controller] events

  - [controller]
      - controllers 0..32 are used for general replay parameters like volume, panning, BPM, ..
      - controllers 32..48 can be mapped to [generator]-dependant [params] ("user controllers")

  - [fx]
      - stores 2..n [fxmodules]
      - determines the audio-routing of [generators] and effects
      - each FX setup has an input [fxmodule], and an output [fxmodule]
         - by means of the FXGenerator (and an FXInstrument), it is possible to modulate the FX input ports. This can be used to
            control the built-in FX modules (for example reverb time or filter cutoff).
         - in future versions it will be possible to also control VST effects/[generators], for which no [instrument] exists

  - [fxmodule]
      - either the main input resp. output, a reference to an Audio or VST generator, or a built-in effect



* Plugin development

   Custom synths can be integrated either by writing a VST 2.x synth (for MIDI style synths),
    or by developing a Syntracker2 plugin that can access the internal tracker classes and
    use the tracker UI library for its interface.

   I will not go into details about VST 2.x development, there's lots of information on the web about that.

   So why would anyone want to implement a Syntracker2 plugin ?

   Here's a couple of reasons:

    - Portability (in the future, currently ST2 runs only on Win32 (main development) and Linux (every now and then))

    - The plugin can access all of the tracker's internal datastructures, allowing the plugin to export
       the song in a custom file-format (for example to replay the song on "real" hardware or in a game or demo)
        (note) this is advanced use, of course. plus you will probably need my help. 

   This release contains a very simple example plugin ("tkcustomsynth") that demonstrates the following:

     - 1..256 voices synthesizer. The oscillator can output a mix between pure sine and a pulse-width modulated pulse waveform.
        The amplifier section supports two volumes and panning.
     - The voice allocation of the synth maps each track of a channel to the corresponding synth voice
        (in other words, track#0 plays synth voice #0, track#1 play voice #1, and so on)

   Overview of the example plugin files:
      CustomSynth.h........................-- Defines a native C++ class which is used by the script-part of the plugin
      CustomSynth.cpp......................-- Implementation of that class
      CustomSynthGenerator.tks.............-- "generator" script interface (defines parameters, delegates voice rendering, ..)
      CustomSynthInstrument.tks............-- "instrument" script interface (stores instrument data, handles note-ons, ..)
      CustomSynthVoice.tks.................-- "voice" script interface (handles controller updates, ..)
      EditCustomSynthInstrumentDialog.xfm..-- Defines the instrument editor user interface (in an SGML-like format)
      EditCustomSynthInstrumentDialog.tks..-- Implements the instrument editor user interface
      SynthVoice.cpp.......................-- *** The juicy bits: The actual voice renderer ***
      SynthVoice.h.........................-- Stores the state of a synth voice
      customsynth.tkp......................-- Script project file (basically the list of scripts that will be included in the "compiled" .tsl file)
      customsynth.tsl......................-- "Compiled" script library (generated by the makefile)
      make.objects.........................-- List of native code object files
      makefile.common......................-- Platform-independent make rules (build/install customsynth.tsl)
      makefile.msvc........................-- Platform-dependent make rules (build/install tkcustomsynth.dll)
      tkcustomsynth.cpp....................-- Main native code plugin interface (register native classes, init/shutdown)
      tkcustomsynth.dll....................-- Native code plugin (exports "CustomSynth" class to scripts)
      tkcustomsynth.h......................-- Just an include helper used by the .cpp files

   How to build the plugin:

      First of all, you need to have the MSVC compiler compiler installed. 
       (In the future, I'll port the example plugin to Linux but today it's Win32 only)

      You will also need MSYS (minimal bash for Win32, also includes "make"). Get it here: http://www.mingw.org/wiki/msys

      Now, open the file "dev/install_msvc.mk" and look for the line that reads "VCTK=". Modify it so it matches the installation path 
      of your compiler.

      If you have the WinDDK installed (which includes msvcrt.dll), you will have to adjust the WINDDK_PATH.

      If you do NOT have WinDDK installed, the plugin will be linked with one of the versioned msvcrt.dlls (for example, msvcrt90.dll)
       and "WINDDK_PATH" must be set to "n".

      There are lots of other variables in the makefiles but you will not need to change them for now (they are simply not required
       by the synth plugin).

      Open a shell (by running "msys.bat") and change to the "dev/tkcustomsynth/" directory.

      Type "make -f makefile.msvc clean yac" to remove all auto-generated files and rebuild the script<->native code interface
       (placed in the ying_* files).

      Now type "make -f makefile.msvc bin install" to build the .dll and the .tsl files and install them to the plugins/ resp. libraries/ folders.

      Tip: I use a bash alias to spare me some typing: 

        $ alias m="make -j 1 -f makefile.msvc"


   How to run Syntracker² with the "customsynth" plugin:

      Launch the "syntracker2_customsynth.bat" batch file.

       This will add the "customsynth.tsl" library to the list of files compiled at startup.
       The script library (.tsl) will in turn load the native code plugin (tkcustomsynth.dll).

       If everything worked, you can now load/create songs that use the new "CUSTOM" generator/instrument type.
        (for example "songs/test_customsynth2-07Apr2011.st2" (just a small test, it's quite horrible music-wise :))



* History

  10Apr2011 - 6th public alpha release
  07Apr2011 - 7th internal alpha release (improved LFO editor, added waveguide param, added example synth plugin ("customsynth"))
  27Mar2011 - 5th public alpha release 
  13Mar2011 - 6th internal alpha (improved orderlist editor, audio sampler volume ramping fixes/improvements, voice allocation fixes)
  08Mar2011 - 5th internal alpha (subsongs, bar-type pattern columns, improved orderlist editor, lots of bugfixes and improvements..)
  31Oct2010 - fourth public alpha (FX autolayout, some minor feature enhancements, some fixes)
  24Oct2010 - third public alpha (macro reset behaviour, some minor feature enhancements, some fixes)
  17Oct2010 - second public alpha release (VST support, crashautosave, audio performance improvements, some fixes)
  28Sep2010 - first public alpha release
  16Sep2010 - second internal alpha release
  17Jun2010 - minor fixes
  16Jun2010 - minor fixes
  15Jun2010 - minor fixes
  11Jun2010 - first internal alpha release
  
  

* Bugs

That's it for now!

Any kind of constructive feedback is always welcome !

Please report bugs to <bs@tkscript.de> !

Greetings,
Bastian
