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



[...] About

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 - 2010 by Bastian Spiegel <bs@tkscript.de>

     - Pattern font is (C) 1994-2010 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-2010 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-2010 by Sam Lantinga (et. al.)
     -                zlib is (C) 1995-2010 by Jean-Loup Gailly and Mark Adler (et. al.)
     -              OpenGL is (C) 1992-2010 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)
     - zoom in/out for detail step editing
     - microdelay controller
     - 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
     - pattern, envelope, and pianoroll editor views
     - keyjazz takes the current step's controller updates into account

  - 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)

  - 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
     - 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)
     - granular/wavetable mode
        - for "chiptunes" 
     - waveforms can be shared between samples
     - builtin sample editor
     - builtin sample browser with preview feature
        - supports Akai .wav extension (loops, base note, ..)

  - Modular audio FX engine
     - basic building blocks (oscillators, waveshapers, filters, equalizer, compressor, reverb, delay)
     - sample exact

  - Modular waveform synthesizer
     - only the parameters are stored, the waveforms are synthesized when loading a song
     - (WIP)

  - 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)

  * 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.

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



[...] Installation / 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 "audio_device_index" member. See console output of "st2.exe" for the list of available devices
        (note) make sure to select an ASIO device !
     - update the "midi_in_devicenames" array to include your master keyboard device (see console output for the list of available devices)

     (not) if you do not want to use MIDI and your ASIO soundcard only has 2ins / 2outs, the default configuration should work out-the-box

  (I know the setup is a bit cumbersome but the configuration rarely changes)



[...] Status

This is work-in-progress. 

   * Please save your songs frequently because this software has not been tested extensively, therefore crashes may occur!

   * Your feedback would be very appreciated !



[...] Known issues

  - All configuration is currently done using a textfile ("config.tks")

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

  - 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 (on win32) is highly deprecated since it has a very high latency, causing replay timing errors

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

  - The macro editor is functional but especially the envelope editor is not very user friendly. This is one of the oldest parts of the codebase
     and definitely needs an update

  - 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 at the moment

  - 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.

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

  - The Audio FX feature is currently quite slow because it works on a per-sample basis and it is not accelerated by dynamic code generation

  - The waveform synthesizer has not got a UI, yet

  - The Korg Radias support is disabled in this release

  - The application leaks one object at exit (if the replay has been started once)

  - There is no support for VST, yet. as a workaround you can use a virtual MIDI cable to connect to a VST host.

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

  - This application expires end of November 2010. The reason for that is that this software is still in development and I want you to use 
    up-to-date versions. 

  - 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 !


[...] 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

            MOUSE OVER : Highlight row (only for orientation)
             LMB click : Center selected row / position cursor
                  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
     lctrl-lshift-down : Move cursor down 64 steps
                    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
       lctrl-lshift-up : Move cursor up 64 steps
              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

*** 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
               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

*** Pattern editor | Replay

                 space : Play/Loop current pattern / stop replay, reset generators/controllers and goto bookmark
           lctrl-space : Continue replay / stop replay and leave cursor at last replayed position
          lshift-space : Set pattern replay start offset to cursor position
    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
               lctrl-o : Duplicate orderlist entry
        lctrl-lshift-o : Duplicate orderlist entries (range)
               lctrl-p : Copy orderlist range
        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)

*** 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

*** Common menu shortcuts

         lalt-c return : Create new channel
         lalt-t return : Create new track
         lalt-s return : Show/edit song comment
    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
             m         :   Edit metronome
             q         :   Toggle pattern autoscroll mode
             s         :   Edit current tracklayout
             v         :   Keyjazz octave down
             w         :   Edit waveforms
             x         :   Edit instruments
             z         :   Edit generators ('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)

    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


** 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
              RMB drag : Scroll left/right 
              LMB drag : Mark region / autoscroll
              RMB hold : Show context menu
             lctrl-RMB : Immediately 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


[...] 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 ;)
     
  - In case the audio resp. replay thread crashes (pattern won't move when replay is active), save your song immediately and restart ST2

  - 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

  - Use "Song -> Set song length , Repeat Offset, Repeat Length" to configure song length and repeat

  - 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.



[...] History

  28Sep2010 - first public alpha release
  16Sep2010 - second internal alpha release
  17Jun2010 - minor fixes
  16Jun2010 - minor fixes
  15Jun2010 - minor fixes
  11Jun2010 - first internal alpha release
  
 

[...]

That's it for now!

Any kind of constructive feedback is always welcome !

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

Greetings,
Bastian
