[terminatorX.git] / help / C / terminatorX-manual.xml

<?xml version='1.0'?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
          <!ENTITY version "3.90">
          <!ENTITY date "2014-01-31">
]>
<article id="index" lang="en">

  <articleinfo>
        <abstract role="description"><para>terminatorX is a realtime audio synthesizer that allows you
      to "scratch" on digitally sampled audio data (*.wav, *.au, *.ogg,
      *.mp3, etc.) the way hiphop-DJs scratch on vinyl records.</para></abstract>

    <title>terminatorX - Manual</title>

    <author role="maintainer"><firstname>Alexander</firstname><surname>König</surname></author>

    <copyright><year>1999</year><year>2000</year><year>2001</year><year>2002</year><year>2003</year><year>2004</year><year>2005</year><year>2006</year><year>2014</year>
    <holder role="mailto:alex@lisas.de">Alexander König</holder></copyright>
    <revhistory>
        <revision>
        <revnumber>terminatorX Manual &version;</revnumber>
        <date>&date;</date>
      </revision>
    </revhistory>
    <releaseinfo>Version &version;</releaseinfo>

    <legalnotice id="legalnotice">

      <para>Permission is granted to copy, distribute and/or modify 
      this document under the terms of the GNU Free Documentation 
      License (GFDL), Version 1.1 or any later version published by the 
      Free Software Foundation with no Invariant Sections, no 
      Front-Cover Texts, and no Back-Cover Texts. You can find a copy 
      of the GFDL at this <ulink type="help" url="ghelp:fdl">
      link</ulink> or in the file COPYING-DOCS distributed with this 
      manual.</para>

      <para>Many of the names used by companies to distinguish their 
      products and services are claimed as trademarks. Where those 
      names appear in any ScrollKeeper documentation, and the members 
      of the ScrollKeeper Project are made aware of those trademarks, 
      then the names are in capital letters or initial capital 
      letters.</para>

      <para>

        DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED 
        UNDER THE TERMS OF THE GNU FREE DOCUMENTATION LICENSE WITH THE 
        FURTHER UNDERSTANDING THAT:
        <orderedlist>

          <listitem>

            <para>DOCUMENT IS PROVIDED ON AN "AS IS" BASIS, WITHOUT 
            WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, 
            INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE DOCUMENT 
            OR MODIFIED VERSION OF THE DOCUMENT IS FREE OF DEFECTS 
            MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR 
            NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY, 
            ACCURACY, AND PERFORMANCE OF THE DOCUMENT OR MODIFIED 
            VERSION OF THE DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR 
            MODIFIED VERSION PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT 
            THE INITIAL WRITER, AUTHOR OR ANY CONTRIBUTOR) ASSUME THE 
            COST OF ANY NECESSARY SERVICING, REPAIR OR CORRECTION. THIS 
            DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF 
            THIS LICENSE. NO USE OF ANY DOCUMENT OR MODIFIED VERSION OF 
            THE DOCUMENT IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS 
            DISCLAIMER; AND</para>

          </listitem>

          <listitem>

            <para>UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, 
            WHETHER IN TORT (INCLUDING NEGLIGENCE), CONTRACT, OR 
            OTHERWISE, SHALL THE AUTHOR, INITIAL WRITER, ANY 
            CONTRIBUTOR, OR ANY DISTRIBUTOR OF THE DOCUMENT OR MODIFIED 
            VERSION OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH 
            PARTIES, BE LIABLE TO ANY PERSON FOR ANY DIRECT, INDIRECT, 
            SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY 
            CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS 
            OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR 
            MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR LOSSES ARISING 
            OUT OF OR RELATING TO USE OF THE DOCUMENT AND MODIFIED 
            VERSIONS OF THE DOCUMENT, EVEN IF SUCH PARTY SHALL HAVE 
            BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.</para>

          </listitem>

        </orderedlist>

      </para>

    </legalnotice>

  </articleinfo>

  <sect1 id="INTRODUCTION">

    <title>Introduction</title>

    <sect2 id="WHATITIS">

      <title>What it is</title>

      <para>terminatorX is a realtime audio synthesizer that allows you 
      to "scratch" on digitally sampled audio data (*.wav, *.au, *.ogg, 
      *.mp3, etc.) the way hiphop-DJs scratch on vinyl records. It 
      features multiple turntables, realtime effects (buit-in as well 
      as <ulink url="http://www.ladspa.org">LADSPA</ulink> plugin 
      effects), a sequencer and MIDI interface - all accessible through 
      an easy-to-use gtk+ GUI.</para>

      <para>This is software may have 
      <ulink url="http://terminatorX.org/bugs.html">bugs</ulink> please 
      help fixing them. See <xref linkend="CONTACT"/>. Please read this 
      manual and visit the <ulink url="http://terminatorX.org">
      homepage</ulink>.</para>

    </sect2>

    <sect2 id="QUICKSTART">

      <title>Quickstart</title>

      <para>Try the following steps:</para>

      <orderedlist>

        <listitem>

          <para>If you don't have <application>LADSPA</application> 
          (Linux Audio Developer's Simple Plugin API) installed, go and 
          get it from the <ulink url="http://www.ladspa.org">
          LADSPA-homepage</ulink> and install the SDK. terminatorX 
          requires <filename>ladspa.h</filename>.</para>

        </listitem>

        <listitem>

          <para>Install terminatorX (see <filename>INSTALL</filename> 
          file)</para>

        </listitem>

        <listitem>

          <para>If you want to use the 
          <ulink url="http://jackit.sourceforge.net">JACK</ulink> 
          backend run jackd before starting terminatorX.</para>

        </listitem>

        <listitem>

          <para>Run terminatorX</para>

        </listitem>

        <listitem>

          <para>Setup Audio Output via 
          <emphasis>Options/Preferences</emphasis>.</para>

        </listitem>

        <listitem>

          <para>Load an audiofile into the available turntable (you can 
          add more turntables if you want) (Hint: Click on the button 
          that holds "NONE" to load an audiofile, or drop one over the 
          audiofile display from your GNOME filemanager.</para>

        </listitem>

        <listitem>

          <para>Load a LADSPA plugin of your choice by clicking the 
          turntable's <emphasis>FX</emphasis> button and enable 
          it.</para>

        </listitem>

        <listitem>

          <para>Click on the "Audio Engine"-button to start 
          playback.</para>

        </listitem>

        <listitem>

          <para>Click on the "Mouse-Grab"-button to enter grab mode. 
          The turntable with the red border has the input focus.</para>

        </listitem>

        <listitem>

          <para>Press <keycap>SPACE</keycap> or left mouse button to 
          scratch.</para>

        </listitem>

        <listitem>

          <para>Release <keycap>SPACE</keycap> or left mouse button to 
          let the scratch-file run at the turntable's default 
          speed.</para>

        </listitem>

        <listitem>

          <para>Press <keycap>ESCAPE</keycap> to quit grab mode.</para>

        </listitem>

      </orderedlist>

    </sect2>

    <sect2 id="FEATURES">

      <title>Features</title>

      <para>The following list summarizes terminatorX' main 
      features:</para>

      <itemizedlist>

        <listitem>

          <para>Scratching</para>

        </listitem>

        <listitem>

          <para>Multiple turntables</para>

        </listitem>

        <listitem>

          <para>Built-in Sequencer</para>

        </listitem>

        <listitem>

          <para>MIDI Interface</para>

        </listitem>

        <listitem>

          <para>Pitch / Volume settings for each turntable</para>

        </listitem>

        <listitem>

          <para>Effects (Lowpass/Echo) configurable for each 
          turntable</para>

        </listitem>

        <listitem>

          <para>Syncing tables to one master turntable</para>

        </listitem>

        <listitem>

          <para>Broad audiofile-type support</para>

        </listitem>

        <listitem>

          <para>Record to disk</para>

        </listitem>

        <listitem>

          <para>Save and Load turntable sets (.tX - files)</para>

        </listitem>

        <listitem>

          <para>Support for LADSPA plugins.</para>

        </listitem>

        <listitem>

          <para>Support for the <emphasis>JACK Audio Connection 
          Kit</emphasis></para>

        </listitem>

        <listitem>

          <para>and more</para>

        </listitem>

      </itemizedlist>

    </sect2>

    <sect2 id="REQUIREMENTS">

      <title>Requirements</title>

      <para>To run terminatorX a system should meet the following 
      requirements:</para>

      <itemizedlist>

        <listitem>

          <para>Software</para>

          <itemizedlist>

            <listitem>

              <para>required</para>

              <itemizedlist>

                <listitem>

                  <para>Linux, FreeBSD or the like</para>

                </listitem>

                <listitem>

                  <para>glibc2 (pthreads).</para>

                </listitem>

                <listitem>

                  <para>XFree86 (with DGA DirectMouse support). Note 
                  that XFree86 Release 4.0 has a bug resulting in 
                  broken DirectMouse support. This has been fixed by 
                  the XFree86-Team with Release 4.0.1 available from 
                  your distribution or the 
                  <ulink url="http://www.xfree86.org">XFree86 
                  homepage</ulink>.</para>

                </listitem>

                <listitem>

                  <para>The Gimp Toolkit: gtk+ (&gt;= 2.0). If your 
                  distribution doesn't provide a current version of 
                  gtk+ get it from the <ulink url="http://www.gtk.org">
                  gtk+ homepage</ulink>.</para>

                </listitem>

                <listitem>

                  <para>LADSPA - the Linux Audio Developer's Simple 
                  Plugin API. Get it from the 
                  <ulink url="http://www.ladpsa.org">LADSPA 
                  homepage</ulink></para>

                </listitem>

                <listitem>

                  <para>a compiler (gcc)</para>

                </listitem>

              </itemizedlist>

            </listitem>

            <listitem>

              <para>optional (but highly recommended)</para>

              <itemizedlist>

                <listitem>

                  <para>
                  <ulink url="http://plugin.org.uk/releases/lrdf/">liblrdf</ulink> 
                  for easier handling of LADSPA plugins</para>

                </listitem>

                <listitem>

                  <para>
                  <ulink url="http://www.mars.org/home/rob/proj/mpeg/">mad</ulink> 
                  for loading mp3 files.</para>

                </listitem>

                <listitem>

                  <para>
                  <ulink url="http://www.xiph.org/ogg/vorbis/">libvorbis</ulink> 
                  for loading ogg files.</para>

                </listitem>

                <listitem>

                  <para>
                  <ulink url="http://jackit.sourceforge.net">libjack</ulink> 
                  for JACK support.</para>

                </listitem>

                <listitem>

                  <para>
                  <ulink url="http://xmlsoft.org/">libxml2</ulink> to 
                  read terminatorX set and rc files</para>

                </listitem>

                <listitem>

                  <para>
                  <ulink url="http://www.gzip.org/zlib/">zlib</ulink> 
                  to create compressed XML set files to save 
                  diskspaces</para>

                </listitem>

                <listitem>

                  <para>
                  <ulink url="http://www.68k.org/~michael/audiofile/">libaudiofile</ulink> 
                  for loading misc other audio files.</para>

                </listitem>

                <listitem>

                  <para><ulink url="???">libcap</ulink> for capabilties 
                  support.</para>

                </listitem>

                <listitem>

                  <para>
                  <ulink url="http://www-ti.informatik.uni-tuebingen.de/~hippm/mpg123.html">mpg123</ulink> 
                  for mp3 pre-listening (and fallback loading if mad is 
                  not installed).</para>

                </listitem>

                <listitem>

                  <para>
                  <ulink url="http://www.xiph.org/ogg/vorbis/">ogg123</ulink> 
                  for ogg pre-listening (and fallback loading if 
                  libvorbis is not installed).</para>

                </listitem>

                <listitem>

                  <para>
                  <ulink url="http://home.sprynet.com/~cbagwell/sox.html">sox</ulink> 
                  for misc files pre-listening (and fallback loading of 
                  misc files).</para>

                </listitem>

              </itemizedlist>

            </listitem>

          </itemizedlist>

        </listitem>

        <listitem>

          <para>Hardware</para>

          <itemizedlist>

            <listitem>

              <para>An <ulink url="http://www.alsa-project.org">
              ALSA</ulink> or OSS compatible soundcard capable of 
              stereo output.</para>

            </listitem>

            <listitem>

              <para>A good clean mouse and pad, a good X-Pointer 
              setup.</para>

            </listitem>

          </itemizedlist>

        </listitem>

      </itemizedlist>

      <para>A note on performance: terminatorX is known to run 
      satisfyingly on pentium-class systems (or above of course). 
      Increasing the number of turntables or plugins will of course 
      require more performant systems.</para>

    </sect2>

    <sect2 id="INSTALLATION">

      <title>Installation</title>

      <para>For GNU-standards' sake this information is now located in 
      the <filename>INSTALL</filename> file that came with this 
      distribution of terminatorX.</para>

    </sect2>

  </sect1>

  <sect1 id="OPERATION">

    <title>Operation</title>

    <para>TerminatorX' user interface is split up into the main 
    controls (master, sequencer, engine controls and menu buttons) and 
    the individual turntable's controls. Each turntable has it's own 
    interface split up into a control and a audio panel (see 
    <xref linkend="TURNTABLECONTROLS"/>).</para>

    <sect2 id="MENU">

      <title>Menu</title>

      <para>To clean-up the user interface a bit further some functions 
      have been moved into a more standard menu bar for the main window 
      (with release 3.80). The following sub-menus are available:</para>

      <sect3 id="FILEMENU">

        <title><emphasis>File</emphasis> Menu</title>

        <para>The <emphasis>File</emphasis> menu features these 
        functions:</para>

        <itemizedlist>

          <listitem>

            <para><emphasis>Load Audio File</emphasis></para>

            <para>The "official" position functionality is located at 
            the file button (that reads "NONE" on startup) for each 
            turntable. However, a lot of people expect to find this 
            functionality in the menu, so you can load an audio file 
            from here, too.</para>

          </listitem>

          <listitem>

            <para><emphasis>New Set</emphasis></para>

            <para>Erases all existing turntables and sequencer events 
            and creates a new and untouched turntable.</para>

          </listitem>

          <listitem>

            <para><emphasis>Open Set File</emphasis></para>

            <para>Allows restoring of a previously saved terminatorX 
            set file.</para>

          </listitem>

          <listitem>

            <para><emphasis>Save Set</emphasis></para>

            <para>Saves the current turntables and events in a 
            terminatorX set file.</para>

          </listitem>

          <listitem>

            <para><emphasis>Save Set As</emphasis></para>

            <para>Like <emphasis>Save</emphasis> but prompts for a new 
            file name.</para>

          </listitem>

          <listitem>

            <para><emphasis>Quit</emphasis></para>

          </listitem>

        </itemizedlist>

      </sect3>

      <sect3 id="TURNTABLESMENU">

        <title><emphasis>Turntables</emphasis> Menu</title>

        <para>The <emphasis>Turntables</emphasis> menu features these 
        functions:</para>

        <itemizedlist>

          <listitem>

            <para><emphasis>Add Turntable</emphasis></para>

            <para>Adds a new turntable to the current set of 
            turntables.</para>

          </listitem>

          <listitem>

            <para><emphasis>Assign Default MIDI 
            Mappnigs</emphasis></para>

            <para>Will assign the Default MIDI Mappings (see 
            <xref linkend="MIDI"/>) to all standard parameters. 
            Existing mappings will not be overridden.</para>

          </listitem>

          <listitem>

            <para><emphasis>Auto Assign Default MIDI 
            Mappings</emphasis></para>

            <para>When this option is enabled will always re-apply the 
            Default MIDI Mappings (see <xref linkend="MIDI"/>) whenever 
            you load a set, add a new turntable or create a new set. 
            Existing mappings will not be overridden.</para>

          </listitem>

          <listitem>

            <para><emphasis>Clear MIDI Mappings</emphasis></para>

            <para>Removes all currently assigned MIDI mappings.</para>

          </listitem>

          <listitem>

            <para><emphasis>Record Audio to Disk</emphasis></para>

            <para>On activation of this option, terminatorX will prompt 
            for a file name for the RIFF/Wave file to create. Once 
            activated terminatorX will start recording audio to disk 
            the next time the audio engine is started - either by 
            pressing the Power or the Play button. Recording will stop 
            when the audio engine is stopped again. The created 
            RIFF/Wave file will be a 16Bit/Stereo wave-file with the 
            sampling rate selected for the current audio backend.</para>

          </listitem>

        </itemizedlist>

      </sect3>

      <sect3 id="SEQUENCERMENU">

        <title><emphasis>Sequencer</emphasis> Menu</title>

        <para>The <emphasis>Sequencer</emphasis> (see 
        <xref linkend="SEQUENCER"/> for general information on the 
        sequencer) menu features these functions:</para>

        <itemizedlist>

          <listitem>

            <para><emphasis>Delete All</emphasis> submenus</para>

            <para>These submenus allow you to delete sequencer events 
            of a specific parameter or all events for a complete 
            turntable. After selecting the the parameter/turntable of 
            your choice a dialog will pop-up that allows you to delete 
            all events from either:</para>

            <itemizedlist>

              <listitem>

                <para>the beginning of the song upto the current song 
                position</para>

              </listitem>

              <listitem>

                <para>the current song position upto the end of the 
                song</para>

              </listitem>

              <listitem>

                <para>the beginning to the end of the song (all 
                events)</para>

              </listitem>

            </itemizedlist>

          </listitem>

          <listitem>

            <para><emphasis>Delete All Events</emphasis></para>

            <para>Works the same as the <emphasis>Delete All</emphasis> 
            submenus but selects <emphasis>all</emphasis> events for 
            <emphasis>all</emphasis> turntables.</para>

          </listitem>

          <listitem>

            <para><emphasis>Confirm Recorded Events</emphasis></para>

            <para>Usually terminatorX will add all recorded events of a 
            take to the song event list as soon as you hit the 
            <emphasis>Stop</emphasis> button for the sequencer. If you 
            enable <emphasis>Confirm Recorded Events</emphasis> 
            terminatorX will ask you whether the recorded events should 
            really be fed into the song list. This makes it much easier 
            to record a certain part over and over again until you get 
            it right.</para>

          </listitem>

        </itemizedlist>

      </sect3>

      <sect3 id="OPTIONSMENU">

        <title><emphasis>Options</emphasis> Menu</title>

        <para>The <emphasis>Options</emphasis> menu features these 
        functions:</para>

        <itemizedlist>

          <listitem>

            <para><emphasis>Fullscreen</emphasis></para>

            <para>Maximizes the terminatorX main windows to use the 
            complete screen. Note that this requires a NETWM compliant 
            window manager to work. By toggling this option again 
            terminatorX' window can be resized back to the previous 
            state again. The setting will be stored in the <filename>
            ~/.terminatorXrc</filename> file.</para>

          </listitem>

          <listitem>

            <para><emphasis>Preferences</emphasis></para>

            <para>Will pop up the Preferences dialog. For more details 
            on configuration itself see <xref linkend="CONFIGURATION"/> 
            .</para>

          </listitem>

        </itemizedlist>

      </sect3>

      <sect3 id="HELPMENU">

        <title><emphasis>Help</emphasis> Menu</title>

        <para>The <emphasis>Help</emphasis> menu features these 
        functions:</para>

        <itemizedlist>

          <listitem>

            <para><emphasis>Contents</emphasis></para>

            <para>Starts a <emphasis>gnome-help</emphasis> (aka 
            <emphasis>yelp</emphasis>) process to display the very 
            manual you are reading right now.</para>

          </listitem>

          <listitem>

            <para><emphasis>About</emphasis></para>

            <para>Selecting this menu item will cause a small dialog to 
            pop up that contains some information on the compile time 
            settings for the terminatorX binary as well as the 
            license.</para>

          </listitem>

          <listitem>

            <para><emphasis>Visit terminatorX.org</emphasis></para>

            <para>Will try to spawn a browser process to load the URL 
            <ulink url="http://terminatorX.org">
            http://terminatorX.org</ulink> - for easy update checking or 
            just unecessary bloat.</para>

          </listitem>

        </itemizedlist>

      </sect3>

    </sect2>

    <sect2 id="MAINCONTROLS">

      <title>Main Controls</title>

      <para>The controls of the master GUI are located in the top and 
      the right bar of the terminatorX main window.</para>

      <itemizedlist>

        <listitem>

          <para><emphasis>Audio Engine Power / Mouse 
          Grab</emphasis></para>

          <para>With the Audio Engine Button you can en- and disable 
          the audio playback engine without activating the sequencer. 
          Unlike earlier versions you will not automatically enter 
          mouse-grab mode so you can modify volume/pitch/echo settings 
          etc. while you actually hear what you do.</para>

          <para>Some functions are not available when the audio engine 
          is on, their controls will be marked insensitive when you 
          enable the engine. To actually enter grab mode you'll have to 
          click on the "Mouse Grab" button. See 
          <xref linkend="GRABMODE"/> to find out how to control the 
          software then.</para>

        </listitem>

        <listitem>

          <para><emphasis>Sequencer Play / Record / 
          Stop</emphasis></para>

          <para>Please read <xref linkend="SEQUENCER"/> to find out 
          more about the sequencer.</para>

        </listitem>

        <listitem>

          <para><emphasis>Master Volume / Pitch</emphasis></para>

          <para>The volume and pitch settings of the individual 
          turntables are relative to these master settings. This 
          information will be stored within the .tX set files.</para>

        </listitem>

      </itemizedlist>

    </sect2>

    <sect2 id="TURNTABLECONTROLS">

      <title>Turntable Controls</title>

      <para>The turntable GUI contains multiple controls and the real 
      time displays for each turntable. To save some space on your 
      desktop and to give terminatorX the traditional audio-application 
      look, terminatorX features "knob"-widgets. These widgets work 
      pretty straight-forward: click somewhere within the widget and 
      keep the left mouse-button pressed. Now move the mouse up and 
      down or left and right to increase/decrease the control's value. 
      All those widget are coupled with a text entry field since 3.70, 
      which allows you to enter values directly.</para>

      <para>A turntable is visualized by two panels: the control and 
      the audio panel. These are no longer combined for better layout 
      management.</para>

      <para>Sometimes you might find a certain audio or control panel 
      unnecessary - simply eating up space. Since release 3.73 it is 
      possible to minimize audio and control panels to the 
      <emphasis>panel bar</emphasis> with the tiny button with a blue 
      bar icon in the upper right edge of each panel. This bar works 
      just like GNOME's window list or KDE's kicker: When a panel is 
      minimized a button in the bar will appear, representing the 
      minimized window. On clicking this button the button will be 
      removed and the minimized panel is displayed again. When no 
      panels are minimized the panel bar automatically disappears to 
      save display space.</para>

      <sect3>

        <title>Turntable Audio Panel</title>

        <para>The complete audio-file loaded into a turntable is 
        displayed in the green-on-black audio-widget. When playing 
        terminatorX will indicate the current position within the 
        sample with a red cursor (a blue/green cursor indicates the 
        turntable is muted).</para>

        <para>Additionally there are some controls above the 
        audio-display:</para>

        <itemizedlist>

          <listitem>

            <para><emphasis>Turntable Label</emphasis></para>

            <para>This label indicates the turntables name. The name 
            can be set via the control panel</para>

          </listitem>

          <listitem>

            <para><emphasis>File Button</emphasis></para>

            <para>This button holds the name of the audio-file 
            currently loaded. When there's no sample loaded the button 
            will read "NONE" to indicate the current status. Click on 
            this button to get a menu from which you can load/reload a 
            sound file or run an external soundfile editor. 
            Alternatively you can drag'n'drop files over the 
            audio-display to load them.</para>

            <itemizedlist>

              <title>The File Button Menu</title>

              <listitem>

                <para><emphasis>Load File</emphasis></para>

                <para>Choose this menu entry to select a soundfile from 
                the file-selection dialog that will pop-up.</para>

              </listitem>

              <listitem>

                <para><emphasis>Reload File</emphasis></para>

                <para>Choose this menu entry to re-read the 
                audio-file.</para>

              </listitem>

              <listitem>

                <para><emphasis>Edit File</emphasis></para>

                <para>This menu entry will run the external 
                audiofile-editor (that can be specified via the 
                options-dialog) with the current audio-file as a 
                parameter. Choose reload after editing and saving the 
                file.</para>

              </listitem>

            </itemizedlist>

          </listitem>

          <listitem>

            <para><emphasis>Mouse Mapping</emphasis></para>

            <para>terminatorX allows mapping misc parameters to the 
            mouse axis of your choice. These mappings will be activated 
            in grab mode, so if you move your mouse in X or Y direction 
            in grab mode the parameters you selected from this menu 
            will be affected (for this turntable). Since Version 3.70 
            this mappings are no longer hardcoded to built-in controls 
            but available for all parameters that qualify as 
            "mappable". Note that this includes plugins' controls as 
            well.</para>

          </listitem>

          <listitem>

            <para><emphasis>MIDI Mapping</emphasis></para>

            <para>This button is available only if terminatorX was 
            built with ALSA MIDI support and the sequencer input port 
            was created successfully on startup. For more information 
            on terminatorX' MIDI interface see <xref linkend="MIDI"/> 
            .</para>

          </listitem>

        </itemizedlist>

      </sect3>

      <sect3>

        <title>Turntable Controls</title>

        <para>These controls are now grouped within functional panels. 
        The number of panels depends on the number of plugins loaded. 
        terminatorX allows hiding the controls not required via the 
        yellow triangle button. To un-hide just click the button again. 
        The first panels are the standard controls for a turntable, 
        then follows the dynamic FX-section and below that follow the 
        pitch and volume controls.</para>

        <sect4>

          <title>Main Panel</title>

          <itemizedlist>

            <listitem>

              <para><emphasis>Name Field</emphasis></para>

              <para>The main panel features a text entry field that 
              allows setting a name for the related turntable. The 
              Labels for the controls and the audio-display will update 
              accordingly.</para>

            </listitem>

            <listitem>

              <para><emphasis>Delete Button</emphasis></para>

              <para>Pressing this button remove the turntable from the 
              current setup. Note that all sequencer events recorded 
              for this turntable will be erased, too.</para>

            </listitem>

            <listitem>

              <para><emphasis>Pitch Adj. Button</emphasis></para>

              <para>Using two (or more) loops and terminatorX' 
              synchronization facility usually requires adjusting the 
              pitch of the loops so that the turntables play in sync. 
              For precisely cut loops this usually means making them 
              run equally fast or one running twice as fast as the 
              other etc. Manually finding the necessary pitch values 
              usually consumes a significant amount of time so the 
              feature <emphasis>Pitch Adjust</emphasis> helps speeding 
              up this process.</para>

              <para>Clicking this button will cause the 
              <emphasis>Compute Pitch</emphasis> dialog to pop up. With 
              this dialog it is possible to specify how many loops of 
              this turntable should be played as fast as a certain 
              amount of loops of the master turntable. After pressing 
              the <emphasis>Ok</emphasis> button terminatorX will 
              adjust the turntable's ptich accordingly in order to 
              match the given playback speed requirements.</para>

              <para>Note that this feature is proabably useless when 
              loading complete songs into terminatorX - it's intended 
              for use with precisely cut loops.</para>

            </listitem>

          </itemizedlist>

        </sect4>

        <sect4>

          <title>Playback Panel</title>

          <para>The playback panel holds all controls related to 
          triggering the turntable. For more details on synchronization 
          see <xref linkend="SYNCHRONIZATION"/>.</para>

          <itemizedlist>

            <listitem>

              <para><emphasis>Trigger! Button</emphasis></para>

              <para>Pressing this button triggers the turntable now. 
              With the audio engine enabled this will cause the 
              turntable to start playing back audio from the beginning 
              of the sample.</para>

            </listitem>

            <listitem>

              <para><emphasis>Stop Button</emphasis></para>

              <para>Guess what, this stops this turntable's 
              audio-playback.</para>

            </listitem>

            <listitem>

              <para><emphasis>Master Button</emphasis></para>

              <para>Enabling this button makes this turntable the 
              <emphasis>sync-master</emphasis>. Note that only 
              <emphasis>one</emphasis> turntable at a time can be the 
              sync-master.</para>

            </listitem>

            <listitem>

              <para><emphasis>Client Button</emphasis></para>

              <para>This button marks the turntable as 
              <emphasis>sync-client</emphasis>, so it will be triggered 
              with the master automatically.</para>

            </listitem>

            <listitem>

              <para><emphasis>Sync-Cycles Selection</emphasis></para>

              <para>The sync cycles determine how often a sync-client 
              should be triggered. With a setting of zero the 
              sync-client will be (re-)triggered with 
              <emphasis>every</emphasis> trigger of the sync-master. A 
              setting of 1 will (re-)trigger the client every 
              <emphasis>second</emphasis> master-trigger and so 
              on.</para>

            </listitem>

          </itemizedlist>

          <para>

            Below the effect queue a turntable shows some more controls:
            <itemizedlist>

              <listitem>

                <para><emphasis>Pitch Control</emphasis></para>

                <para>The pitch control allows setting the default 
                playback speed for that turntable (the "motor" speed). 
                Negative values will result in the sample being played 
                backwards.</para>

              </listitem>

              <listitem>

                <para><emphasis>PAN Control</emphasis></para>

                <para>This parameter allows setting the position of the 
                turntable's main signal within the stereo 
                panorama.</para>

              </listitem>

              <listitem>

                <para><emphasis>VU Meter</emphasis></para>

                <para>The displayed signal shows the turntable's 
                current signal not including the echo-signal which is 
                mixed separately.</para>

              </listitem>

            </itemizedlist>

          </para>

        </sect4>

      </sect3>

      <sect3 id="PARAMETERMENU">

        <title>Parameter Menu</title>

        <para>

          TerminatorX can record events for nearly all parameters of a 
          turntable. All of these so-called "sequencable" parameters 
          have an extra pop-up menu since Version 3.81. Simply 
          right-click on the knob, button, slider of the parameter you 
          want to setup, and a menu with the following options will 
          appear:
          <itemizedlist>

            <listitem>

              <para><emphasis>MIDI Learn</emphasis></para>

              <para>This options provides an easy method to select the 
              MIDI control to modify the parameter you select. If you 
              choose this menu entry, a tiny dialog box will pop up 
              that reads <emphasis>"Waiting for MIDI 
              Event..."</emphasis>. The first MIDI event terminatorX 
              receives will now be mapped to control this 
              parameter.</para>

            </listitem>

            <listitem>

              <para><emphasis>Remove MIDI Binding</emphasis></para>

              <para>If a MIDI event has been bound to a parameter it 
              can be removed by selecting this menu entry.</para>

            </listitem>

            <listitem>

              <para><emphasis>Map MIDI Reverse</emphasis></para>

              <para>This option can be turned either on or off: when 
              enabled the maximum value of the MIDI controller will be 
              mapped to the minimum value of the controlled parameter 
              and the other way round.</para>

              <para>Note that this allows mapping a MIDI controller as 
              a crossfader: simply map the same MIDI controller to two 
              different turntables's volume controls (or optionally 
              extra amplifier plugins) and reverse one of these MIDI 
              mappings.</para>

            </listitem>

            <listitem>

              <para><emphasis>Set Upper MIDI Bound</emphasis></para>

              <para>Sometimes it is preferable to modify a certain 
              parameter only within a specific value range - this can 
              be achieved with this option - by setting an upper and a 
              lower bound for the MIDI control of this parameter. When 
              you select this menu entry, the current setting of this 
              parameter will be used as the upper bound for the 
              parameter's MIDI mapping.</para>

            </listitem>

            <listitem>

              <para><emphasis>Reset Upper MIDI Bound</emphasis></para>

              <para>If an upper MIDI bound was set for this parameter 
              it can be removed by selecting this menu entry.</para>

            </listitem>

            <listitem>

              <para><emphasis>Set Lower MIDI Bound</emphasis></para>

              <para>Works just like setting the uper MIDI bound: when 
              you select this menu entry, the current setting of this 
              parameter will be used as the lower bound for the 
              parameter's MIDI mapping.</para>

            </listitem>

            <listitem>

              <para><emphasis>Reset Lower MIDI Bound</emphasis></para>

              <para>If a lower MIDI bound was set for this parameter it 
              can be removed by selecting this menu entry.</para>

            </listitem>

            <listitem>

              <para><emphasis>Delete Sequencer Events</emphasis></para>

              <para>Just like the Sequencer menu (see 
              <xref linkend="SEQUENCERMENU"/>) this entry allows you to 
              delete events recorded for this specific parameter.</para>

            </listitem>

          </itemizedlist>

        </para>

      </sect3>

      <sect3>

        <title>The Effect Queue</title>

        <para>With release 3.70 the effects are no longer hardcoded 
        into the turntable. The effects are now arranged within an 
        per-turntable effect-queue. Additionally Version 3.82 
        introduces a second effect-queue that follows the first: the 
        queue for stereo LADSPA plugin effects. The effect sequence is 
        configurable by the user. To move an effect to higher position 
        within the queue, press the <emphasis>blue upward arrow 
        button</emphasis>. This will cause the effect to be rendered 
        <emphasis>before</emphasis> the following effects. The 
        <emphasis>blue downward arrow button</emphasis> will move the 
        effect down by one position. It will then be rendered 
        <emphasis>after</emphasis> the preceding effects.</para>

        <para>There are two types of effects: the traditional built-in 
        effects (Lowpass and Echo) and LADSPA plugins. The built-in 
        effects are always available and cannot be removed (but 
        disabled). There can be only one instance of a built-in effect. 
        The LADSPA plugins on the other hand may be instantiated 
        multiple times and can be removed from the effect queue. Press 
        the <emphasis>blue cross button</emphasis> to achieve 
        this.</para>

        <figure>

          <title>An example for a terminatorX effect queue</title>

          <graphic fileref="figures/signalflow.png" format="PNG"/>
        </figure>

        <para>Now since release 3.71 the built-in echo effect is 
        treated differently from other effects. Where all other effects 
        feed their signal back into the effect queue the echo effect 
        doesn't touch the input signal. It's echo-signal is mixed 
        separately from the turntable's main signal to allow a 
        different panning value for the echo-signal. This mode of 
        operation does have some side-effects: imagine a lowpass filter 
        with a position after the echo effect in the effect queue. This 
        will result in the turntable's main signal being 
        lowpass-filtered but it will leave the echo-signal 
        lowpass-unfiltered.</para>

        <para>Some may call this behaviour a bug - whereas I would 
        consider it a feature ;). Anyway if the above description 
        didn't clear things up maybe the displayed figure does. It 
        shows a schematic effect queue with the built-in effects and 
        two LADSPA effects enabled. Now with this setup you will not 
        hear anything from the second LADSPA effect in the 
        echo-signal.</para>

        <para>Release 3.82 introduces a menu for each LADSPA plugin. 
        Simply click on the Plugin's label to operate the menu. Aside 
        of displaying detailed information about a plugin, the menu 
        also contains some new functionality: <emphasis>Add Dry/Wet 
        Control</emphasis>. When activated the effect receives an extra 
        Dry/Wet control that allows you to modify to what extent the 
        effect will actually effect the turntable's signal. The extra 
        control doesn't differ from the other controls: you can record 
        events for it, etc. The additional control can be removed via 
        the very same menu item that adds the control.</para>

        <itemizedlist>

          <listitem>

            <para><emphasis>FX</emphasis> and <emphasis>Stereo FX 
            Buttons</emphasis></para>

            <para>Press this button to load a LADSPA plugin into the 
            effect queue of the turntable. A menu holding the available 
            (terminatorX-"compatible") LADSPA-plugins will pop up - 
            mono plugins are available from the <emphasis>FX</emphasis> 
            menu, stereo plugins from the <emphasis>Stereo 
            FX</emphasis> menu. The plugins are grouped within submenus 
            according to the modules the plugins are contained in. 
            Simply select the plugin you want to load from this menu 
            and a panel for it will pop up at the end of the effect 
            queue.</para>

            <para>Note that due to the wide parameter ranges some 
            LADSPA plugins have they sometimes might be hard to control 
            with the knob widget. In these cases you might want to use 
            the text field to enter values. For more details on plugins 
            see <xref linkend="LADSPAPLUGINS"/>.</para>

          </listitem>

        </itemizedlist>

      </sect3>

      <sect3>

        <title>Lowpass Panel</title>

        <para>terminatorX features a built-in resonating lowpass filter 
        that can be configured with this panel.</para>

        <itemizedlist>

          <listitem>

            <para><emphasis>Enable Button</emphasis></para>

            <para>Activating this button will enable the lowpass filter 
            for this turntable.</para>

          </listitem>

          <listitem>

            <para><emphasis>Input Gain Control</emphasis></para>

            <para>With this parameter you can amplify the signal that 
            goes into the lowpass filter if required.</para>

          </listitem>

          <listitem>

            <para><emphasis>Frequency Control</emphasis></para>

            <para>Use this parameter to set the cutoff frequency for 
            the lowpass filter. Minimum: 0=0Hz, Maximum: 1=22KHz.</para>

          </listitem>

          <listitem>

            <para><emphasis>Resonance</emphasis></para>

            <para>Use this parameter to set the resonance-value. 
            Minimum: 0=no resonance, Maximum: 1=max resonance.</para>

          </listitem>

        </itemizedlist>

      </sect3>

      <sect3>

        <title>Echo Panel</title>

        <para>Additionally terminatorX features a built-in echo effect. 
        It can be configured with this panel.</para>

        <itemizedlist>

          <listitem>

            <para><emphasis>Enable Button</emphasis></para>

            <para>Activating this button will enable the echo effect 
            for this turntable.</para>

          </listitem>

          <listitem>

            <para><emphasis>Duration Control</emphasis></para>

            <para>Use this parameter to set the length of the echo. The 
            duration parameter scales to the actual sample length: so 
            if you set it to 0.5 you will hear the echo when the red 
            playback cursor is half way through the sample. This is 
            true for samples that are shorter than terminatorX' maximum 
            echo buffer size only.</para>

          </listitem>

          <listitem>

            <para><emphasis>Feedback Control</emphasis></para>

            <para>Set the echo's feedback amount with this 
            parameter.</para>

          </listitem>

          <listitem>

            <para><emphasis>Volume Control</emphasis></para>

            <para>This parameter can additionally amplify the echo 
            signal. Unlike the feedback parameter above this parameter 
            has no influence on the signal fed back into the 
            echo-buffer, it effects merely the playback volume of the 
            echo signal.</para>

          </listitem>

          <listitem>

            <para><emphasis>Pan Control</emphasis></para>

            <para>The echo effect differs from other effects as it's 
            output signal will be mixed separately. The main goal here 
            is to allow positioning the echo signal at a position in 
            the stereo panorama that differs from the main panning 
            position of the turntable to achieve a somewhat spacial 
            effect. The easy example is: turntable's panning left, 
            echo's panning right. As both pan parameters are 
            sequenceable you can create nice motion effects from this 
            starting point.</para>

          </listitem>

        </itemizedlist>

      </sect3>

    </sect2>

    <sect2 id="SYNCHRONIZATION">

      <title>Synchronization</title>

      <para>Let's start off with an example: Say you have two drum 
      loops and one bassline loaded in three turntables. Of course you 
      want these samples to be triggered at the same time but you don't 
      want to invest time to cut them to the exact length. Therefore 
      you decide which of the drum loops to make the sync master. 
      You'll have to do this before you enable the audio engine (for 
      now). Only one turntable can be the sync master. Now you can make 
      the other two sync clients which will cause them to be 
      (re-)triggered whenever the master is (re-)triggered. The number 
      you can select to the right of the <emphasis>client 
      button</emphasis> sets the trigger delay for the button: if it's 
      set to zero the turntable will be triggered with every master 
      trigger, if it's set to 1 it'll be triggered every 2nd master 
      trigger and so on.</para>

      <para>A nice side effect of this feature is: you can now scratch 
      the second (sync client) drum loop and no matter whether you're 
      scratching is good or not the beat will be triggered correctly 
      again ;)</para>

    </sect2>

    <sect2 id="GRABMODE">

      <title>Grab Mode Operation</title>

      <para>After pressing the <emphasis>Mouse Grab button</emphasis> 
      terminatorX enters "grab mode". This mode actually blocks the 
      mouse (as its input is now used to control the real time 
      parameters) and therefore you'll have to know some mouse/keyboard 
      shortcuts to control the software without the GUI.</para>

      <para>Press <keycap>ESCAPE</keycap> to quit grab mode.</para>

      <para>Select the turntable with input focus: The first turntable 
      to hold the input focus will be the first turntable. You can now 
      use <keycap>TAB</keycap> or right mouse button to switch to the 
      next turntable. Alternatively you can use <keycap>F1</keycap> to 
      <keycap>F12</keycap> to select turntable 1 to 12.</para>

      <para>Now the turntable that has the focus is the one you will 
      manipulate with your mouse and keyboard inputs: Note that you can 
      actually map different functions to the mouse x/y axis - so what 
      actually happens when you move your mouse depends on what you 
      select via the <emphasis>Mouse Mapping</emphasis> for each 
      turntable.</para>

      <table>

        <title>Keyboard Controls in Grab Mode</title>

        <tgroup cols="2">

          <thead>

            <row><entry>Key</entry><entry>Function</entry></row>

          </thead>

          <tbody>

            <row><entry><keycap>TAB</keycap></entry><entry>select next 
            turntable</entry></row>

            <row><entry><keycap>F1</keycap> to <keycap>
            F12</keycap></entry><entry>select turntable 1 to 
            12</entry></row>

            <row><entry><keycap>RETURN</keycap></entry><entry>triggers 
            the turntable</entry></row>

            <row><entry><keycap>BACKSPACE</keycap></entry><entry>stops 
            the turntable</entry></row>

            <row><entry><keycap>S</keycap></entry><entry>toggles "Sync 
            Client"</entry></row>

            <row><entry><keycap>SPACE</keycap></entry><entry>while 
            pressed turntable speed is mapped to mouse speed 
            (scratching!)</entry></row>

            <row><entry><keycap>ALT</keycap></entry><entry>mute 
            on/off</entry></row>

            <row><entry><keycap>CTRL</keycap></entry><entry>mute on/off 
            (inverted)</entry></row>

            <row><entry><keycap>F</keycap></entry><entry>("fast") warp 
            mode (while scratching)</entry></row>

            <row><entry><keycap>W</keycap></entry><entry>same as above 
            but the audio will be muted while warping</entry></row>

          </tbody>

        </tgroup>

      </table>

      <table>

        <title>Mouse Button Controls in Grab Mode</title>

        <tgroup cols="2">

          <thead>

            <row><entry>Mouse 
            Button</entry><entry>Function</entry></row>

          </thead>

          <tbody>

            <row><entry><emphasis>Left 
            button</emphasis></entry><entry>same as <keycap>
            SPACE</keycap>: scratching (triggers the turntable when 
            stopped)</entry></row>

            <row><entry><emphasis>Right 
            button</emphasis></entry><entry>select next 
            turntable</entry></row>

            <row><entry><emphasis>Middle 
            button</emphasis></entry><entry>mute on/off</entry></row>

          </tbody>

        </tgroup>

      </table>

      <para>Scratching works as before: press <keycap>SPACE</keycap> or 
      left mouse button to actually scratch: now your mouse controls 
      the turntables speed. Release it to let that turntable spin at 
      default speed again.</para>

    </sect2>

    <sect2 id="DRAGNDROP">

      <title>Drag And Drop</title>

      <para>Since V3.55 terminatorX provides multiple DND-Drop-Targets 
      for use with GNOME / gmc (gmc is the GNU Midnight Commander), 
      Nautilus or the Enlightenment File Manager (efm). You can load an 
      audiofile into an existing turntable by dragging it from a gmc 
      (or efm or whatever)-window and drop it over a. the 
      <emphasis>file button</emphasis> (audio-display) or b. (the 
      easier target ;) over the audio-display (the green on black 
      widget that displays the audiodata).</para>

      <para>To add a file to the set (== to load the file into a *new* 
      turntable) simply drop the audiofile over the "New Turntable" 
      Button. To load a complete terminatorX-set simply drop the set 
      file (*.tX) over the "Load Set" button.</para>

    </sect2>

    <sect2 id="SEQUENCER">

      <title>The Sequencer</title>

      <para>Release 3.60 introduced the sequencer. It can record and 
      play back events for the following parameters:</para>

      <itemizedlist>

        <listitem>

          <para>master volume &amp; pitch</para>

        </listitem>

        <listitem>

          <para>scratching</para>

        </listitem>

        <listitem>

          <para>(turntable) volume &amp; pitch</para>

        </listitem>

        <listitem>

          <para>triggers</para>

        </listitem>

        <listitem>

          <para>loop (on/off)</para>

        </listitem>

        <listitem>

          <para>sync client settings</para>

        </listitem>

        <listitem>

          <para>muting</para>

        </listitem>

        <listitem>

          <para><emphasis>all</emphasis> parameters for the effects. 
          This includes built-in effects (lowpass and echo) as well as 
          LADSPA plugins.</para>

        </listitem>

      </itemizedlist>

      <para>To record events simply press the 
      <emphasis>Record</emphasis> button of the sequencer, then press 
      the <emphasis>Play</emphasis> button. All actions (for 
      sequenceable parameters - see above) you now take will be 
      recorded into the song list. Press <emphasis>Stop</emphasis> and 
      <emphasis>Play</emphasis> again to see/hear how terminatorX plays 
      back the events recorded before. You can now record events again 
      for e.g. another turntable or record other parameters for the 
      same turntable - whatever you want to do. Recording events for 
      parameters for which events have been recorded before will result 
      in dubbing: if you touch a parameter while recording, events 
      previously recorded will be erased from the moment you touch the 
      parameter until you stop recording.</para>

      <para>When recording long sequences/songs you can use the 
      sequencer-scale to start recording/playback from any 
      song-position you want. To record a single parameter value at a 
      certain position simply move the sequencer-scale to that 
      position, press <emphasis>Record,</emphasis> set the parameter 
      and press <emphasis>Stop</emphasis> again.</para>

      <para>To selectively delete events from the sequencer see 
      <xref linkend="SEQUENCERMENU"/> and 
      <xref linkend="PARAMETERMENU"/>.</para>

    </sect2>

    <sect2 id="LADSPAPLUGINS">

      <title>Plugins (LADSPA)</title>

      <para>Since release 3.70 terminatorX supports LADSPA-plugins. 
      LADSPA is the "Linux Audio Developer's Simple Plugin API" which 
      was designed by developers on the 
      Linux-Audio-Developer-Mailinglist and is maintained by Richard 
      W.E. Furse. For more information on LADSPA, other LADSPA-hosts 
      and LADSPA-plugins checkout the 
      <ulink url="http://www.ladspa.org">LADSPA homepage</ulink>.</para>

      <para>Not every plugin is supported by terminatorX though. As the 
      plugins are inserted into the per-turntable effect-queue, they 
      have to be mono or (as of Version 3.82) stereo plugins. This is 
      why terminatorX will load plugins with <emphasis>one</emphasis> 
      or <emphasis>two</emphasis> audio-in ports and 
      <emphasis>one</emphasis> or <emphasis>two</emphasis> audio-out 
      ports only.</para>

      <para>The decision on whether a plugin is terminatorX-suitable is 
      made on terminatorX startup, so only plugins that fit into the 
      effect queue will be offered in the mono plugin-menu that pops up 
      when the <emphasis>FX</emphasis> button is clicked or in the 
      stereo plugin menu when the <emphasis>Stereo FX</emphasis> button 
      si clicked. Depending on whether the terminatorX binary you're 
      using was built with or without liblrdf ( 
      <xref linkend="LIBLRDF"/>) support the plugin menu will either 
      contain sub-menus with plugin categories (with liblrdf) or just a 
      single menu with the <emphasis>Unclassified</emphasis> 
      category.</para>

      <para>On startup terminatorX will print some information on the 
      LADSPA-plugins analysis process to the standard output if you 
      have enabled "Verbose Plugin Loading" in the Preferences dialog. 
      Watch the terminal you run terminatorX from for that info if you 
      have problems loading a plugin.</para>

      <para>As specified in the LADSPA-standard LADSPA-plugins can be 
      located in multiple directories across the filesystem. To enable 
      LADSPA-hosts to find those plugins you have to set the 
      environment variable <envar>LADSPA_PATH</envar> accordingly. 
      Let's say you store your plugins in <filename>
      /usr/lib/ladspa</filename> and <filename>
      /home/yourlogin/plugins</filename> then you would have to 
      set:</para>

      <para><envar>LADSPA_PATH</envar>= <filename>
      /usr/lib/ladspa:/home/yourlogin/plugins</filename></para>

      <para>As a fallback terminatorX will look in the standard 
      directories <filename>/usr/lib/ladspa</filename> and <filename>
      /usr/local/lib/ladspa</filename> if the environment variable is 
      not set. Note that this is just a convenience-function, in order 
      for other LADSPA-hosts to work properly, be sure to set your 
      <envar>LADSPA_PATH</envar> correctly. It is a good idea to do 
      that from somewhere in your system configuration (either in your 
      rc-scripts or <filename>/etc/profile</filename> or wherever you 
      prefer).</para>

      <sect3 id="LIBLRDF">

        <title>liblrdf support</title>

        <para>Release 3.80 introduces support for Steve Harris' great 
        <ulink url="http://plugin.org.uk/releases/lrdf/">
        liblrdf</ulink> library which introduces an RDF based scheme to 
        categorize LADSPA plugins. This approach allows storing 
        additional meta-data for LADSPA plugins in separate RDF files. 
        In order to make use of these RDF files a terminatorX binary 
        (compiled with liblrdf support of course) requires the main 
        <filename>ladspa.rdfs</filename> file and additional RDF files 
        containing meta information about the LADSPA plugins installed. 
        Steve Harris' wonderful plugin library comes with such an 
        additional description file for example.</para>

        <para>By default terminatorX will search the directories 
        <filename>/usr/share/ladspa/rdf</filename> and <filename>
        /usr/local/share/ladspa/rdf</filename> for RDF files. In case 
        the files were installed to other locations it is possible to 
        configure the LADSPA RDF path in the <emphasis>Misc</emphasis> 
        tab of the <emphasis>Preferences</emphasis> dialog.</para>

        <para>If the RDF are read successfully on startup, the LADSPA 
        menu that pops up when clicking a turntable's 
        <emphasis>FX</emphasis> button will feature multiple sub-menus 
        with LADSPA plugin categories (eg 
        <emphasis>Amplitude/Amplifier</emphasis>) in which you will 
        find the according plugins. Plugins not categorized by the RDF 
        files reside in the <emphasis>Unclassified</emphasis> 
        menu.</para>

      </sect3>

    </sect2>

    <sect2 id="MIDI">

      <title>MIDI Interface</title>

      <para>Aside of controlling terminatorX with a regular mouse and 
      keyboard it is possible to control parameters through MIDI events 
      (since 3.80). The MIDI interface is based upon the ALSA sequencer 
      API. On startup terminatorX creates a MIDI input port called 
      "terminatorX". You can now use for example the 
      <ulink url="http://pkl.net/%7Enode/alsa-patch-bay.html">
      alsa-patch-pay</ulink> to connect an output port of your choice 
      (either a hardware MIDI input device or a software generating 
      midi events) to the terminatorX input port. If the 
      "<emphasis>Restore MIDI Connections</emphasis>" option is 
      activated terminatorX will try to re-connect to the MIDI ports it 
      was connected to with the last run. However this approach is 
      purely address-based and might fail miserably with software 
      ports, in this case just disable the configuration options 
      re-wire manually.</para>

      <para>

        There are two ways to map MIDI events to a parameter:
        <itemizedlist>

          <listitem>

            <para>Via the <emphasis>Configure MIDI Bindings</emphasis> 
            dialog as described below</para>

          </listitem>

          <listitem>

            <para>Via the the a parameter's menu (see 
            <xref linkend="PARAMETERMENU"/>)</para>

          </listitem>

        </itemizedlist>

      </para>

      <para>Once the connection is set up terminatorX receives MIDI 
      events through the input port. To configure what MIDI events will 
      have which effect on a terminatorX turntable you can bind MIDI 
      events to parameters of your choice by clicking the 
      <emphasis>MIDI</emphasis> button of the turntable's audio panel. 
      As a result the <emphasis>Configure MIDI Bindings</emphasis> 
      dialog will pop up which features a field labelled 
      <emphasis>Selected MIDI Event</emphasis> that will frequently 
      update to display the contents of the last MIDI event received by 
      terminatorX. So in order to map a MIDI controller to a specific 
      turntable parameter select the parameter of your choice from the 
      parameter list, cause your MIDI event sending device to emit the 
      event you want to map the parameter on and click the 
      <emphasis>Bind</emphasis> button.</para>

      <para>Immediately after binding the event you should see that the 
      <emphasis>Event</emphasis> column entry of the selected parameter 
      is updated to match the selected event. From now on all events 
      matching the selected event will cause the turntable parameter to 
      be updated. The GUI for that parameter will be refreshed 
      accordingly. Note that it is possible to map the same event to 
      multiple parameters.</para>

      <para>The MIDI mappings are stored within terminatorX set files 
      so you wont have to reconfigure your bindings every time you 
      start up terminatorX. If you are unhappy with a chosen binding 
      you can select the parameter and click the <emphasis>Remove 
      Binding</emphasis> button to get rid of the parameter's MIDI 
      mapping.</para>

      <para>TeriminatorX now features a default MIDI mapping that can 
      be enabled via the <emphasis>Turntables Menu</emphasis> (see 
      <xref linkend="TURNTABLESMENU"/>). The controllers are mapped in 
      a one channel per turntable fashion:</para>

      <table>

        <title>Default MIDI Controller Mapping</title>

        <tgroup cols="3">

          <thead>

            <row><entry>Turntable Parameter</entry><entry>MIDI 
            Controller</entry><entry>MIDI CC Name</entry></row>

          </thead>

          <tbody>

            <row><entry>Volume</entry><entry>7</entry><entry><quote>Main 
            Volume</quote></entry></row>

            <row><entry>Pan</entry><entry>10</entry><entry><quote>Pan</quote></entry></row>

            <row><entry>Lowpass Cutoff 
            Frequency</entry><entry>12</entry><entry><quote>Effect 
            Control 1</quote></entry></row>

            <row><entry>Lowpass 
            Resonance</entry><entry>13</entry><entry><quote>Effect 
            Control 2</quote></entry></row>

            <row><entry>Lowpass 
            Gain</entry><entry>16</entry><entry><quote>General Purpose 
            Controller 1</quote></entry></row>

            <row><entry>Speed</entry><entry>17</entry><entry><quote>General 
            Purpose Controller 2</quote></entry></row>

            <row><entry>Pitch</entry><entry>18</entry><entry><quote>General 
            Purpose Controller 3</quote></entry></row>

            <row><entry>Sync 
            Cycles</entry><entry>19</entry><entry><quote>General 
            Purpose Controller 4</quote></entry></row>

            <row><entry>Echo 
            Length</entry><entry>75</entry><entry><quote>Sound 
            Controller 6</quote></entry></row>

            <row><entry>Echo 
            Feedback</entry><entry>76</entry><entry><quote>Sound 
            Controller 7</quote></entry></row>

            <row><entry>Echo 
            Volume</entry><entry>77</entry><entry><quote>Sound 
            Controller 8</quote></entry></row>

            <row><entry>Echo 
            Pan</entry><entry>78</entry><entry><quote>Sound Controller 
            9</quote></entry></row>

          </tbody>

        </tgroup>

      </table>

      <para>The toggle parameters of a turntable (where things can only 
      be turned on or off) are mapped to MIDI NOTE events, where the 
      first turntable is mapped to 'C', the next to 'C#', the next to 
      'D' and so on. The "function" of the toggle is defined via the 
      selected MIDI channel:</para>

      <table>

        <title>Default MIDI Note On/Off Mapping</title>

        <tgroup cols="2">

          <thead>

            <row><entry>Turntable Parameter</entry><entry>MIDI 
            Channel</entry></row>

          </thead>

          <tbody>

            <row><entry>Trigger</entry><entry>0</entry></row>

            <row><entry>Sync Client</entry><entry>1</entry></row>

            <row><entry>Loop</entry><entry>2</entry></row>

            <row><entry>Lowpass Enable</entry><entry>3</entry></row>

            <row><entry>Echo Enable</entry><entry>4</entry></row>

            <row><entry>Mute</entry><entry>5</entry></row>

            <row><entry>Motor Spin On/Off</entry><entry>6</entry></row>

          </tbody>

        </tgroup>

      </table>

      <para>If you want to use your joystick to control terminatorX - I 
      wrote a tiny tool to create MIDI events from joystick motion 
      called <emphasis>aseqjoy</emphasis>. It's available from the 
      <ulink url="http://terminatorX.org/aseqjoy.html">terminatorX 
      website</ulink>, too.</para>

    </sect2>

    <sect2 id="JACKSUPPORT">

      <title>JACK Support</title>

      <para>TerminatorX Version 3.81 brings support for the 
      <emphasis>JACK Audio Connection Kit</emphasis>. Instead of 
      writing audio data directly to some audio device terminatorX can 
      send data to the JACK Daemon for further processing.</para>

      <para>To use the JACK backend you have to ensure that the JACK 
      Daemon is up and running before you start terminatorX. The JACK 
      backend is only available if terminatorX was capable of 
      connecting to the JACK Daemon on startup. By default the two 
      output ports of terminatorX will be connected to physical ports 
      if available. You can then re-wire the ports whatever way you 
      want. They will not be deactivated - when terminatorX' audio 
      engine is turned off, the audio backend emits continuous 
      silence.</para>

    </sect2>

  </sect1>

  <sect1 id="CONFIGURATION">

    <title>Configuration</title>

    <para>The main terminatorX configuration parameters can be set up 
    via the <emphasis>Preferences</emphasis> dialog, which can be 
    activated from the terminatorX menu. The new 
    <emphasis>Preferences</emphasis> dialog features multiple tabs for 
    several aspects of configuration.</para>

    <para>A word on the settings in general: your settings are stored 
    in an XML file ( <filename>~/.terminatorXrc</filename>). So if you 
    think you completely messed up your settings you will have to exit 
    terminatorX - delete this file - and then re-run terminatorX with 
    the default settings. Note: is this file is now an XML file you can 
    edit with an editor of your choice.</para>

    <sect2 id="AUDIOTAB">

      <title><emphasis>Audio</emphasis> Tab</title>

      <para>This tab allows to select which audio backend terminatorX 
      should use. Currently there are three options: the OSS (Open 
      Sound System) backend, the ALSA (Advanced Linux Sound 
      Architecture) backend and the JACK (JACK Audio Connection Kit) 
      backend. Some of these options might not be available, if your 
      terminatorX binary wasn't compiled to support a certain 
      backend.</para>

      <para>The OSS and ALSA backends have dedicated configuration 
      tabs, JACK requires no further configuration - for more details 
      on JACK support see <xref linkend="JACKSUPPORT"/>.</para>

    </sect2>

    <sect2 id="OSSTAB">

      <title><emphasis>Audio: OSS</emphasis> Tab</title>

      <para>Select the audio device you are going to use from the 
      available options (or simply enter one yourself). terminatorX 
      renders audio block-wise. In order to achieve close-to-realtime 
      performance it is necessary to keep this blocks as small as 
      possible. The main parameters that determine how 
      close-to-realtime terminatorX will perform are <emphasis>No. of 
      Buffers</emphasis> and <emphasis>Buffersize</emphasis>. The 
      <emphasis>No. of Buffers</emphasis> parameter determines how many 
      buffers the audio driver should use in most cases 
      <emphasis>2</emphasis> should be the best setting and in rare 
      cases <emphasis>3</emphasis> might give better results.</para>

      <para>The value for the <emphasis>Buffersize</emphasis> setting 
      will be evaluated as 2^buffersize by OSS. So if you set the value 
      to <emphasis>8</emphasis> the actual buffer size will be 2^8=256 
      Bytes. The smaller the buffers' size the better terminatorX will 
      perform. The default setting of <emphasis>9</emphasis> should be 
      acceptable in most conditions, but if you here "clicks", or 
      "drops" in audio output that are not related to your 
      sample-material you will have to increase the buffer size. On the 
      other hand if you believe terminatorX does not react fast enough 
      you have to decrease this parameter.</para>

      <para>Additionally you can select the sampling rate you want 
      terminatorX to operate on - note that recording to disk will use 
      the same sample rate.</para>

    </sect2>

    <sect2 id="ALSATAB">

      <title><emphasis>Audio: ALSA</emphasis> Tab</title>

      <para>Using ALSA for audio output allows specifing the buffer 
      sizes in microseconds. ALSA uses a ring-buffer to process audio. 
      The <emphasis>Buffer Time</emphasis> option lets you set the size 
      for the complete ring buffer, while the <emphasis>Period 
      Time</emphasis> determines how many audio samples will be 
      transferred to the audio device per cycle. I'm not really sure on 
      what kind of settings to recommend, however I had best results 
      when setting the <emphasis>Period Time</emphasis> to 3rd or half 
      of the <emphasis>Buffer Time</emphasis>.</para>

      <para>It's advisable to set the <emphasis>Buffer Time</emphasis> 
      to at least the double of the <emphasis>Period Time</emphasis>, 
      but for a more detailed description check out the ALSA 
      documentation.</para>

    </sect2>

    <sect2 id="INPUTTAB">

      <title><emphasis>Input</emphasis> Tab</title>

      <para>Between rendering and outputting these blocks terminatorX 
      checks for mouse motion. The problem with mice is: they don't 
      report when they have stopped. This is why terminatorX assumes 
      your mouse has stopped if there is no motion reported for certain 
      amount of render/output-cycles. This value is configurable via 
      the <emphasis>Stop-sense-cycles</emphasis> option. If you 
      decrease your buffersize of course you shorten the cycle time as 
      well, therefore if you here strange stop/run behaviour of the 
      audio output while scratching after you decreased the buffer size 
      you might have to increase the stop-sense value too.</para>

      <para>XInput Device: <emphasis>WARNING:</emphasis> Use this 
      option *only* if you want to use an input device other than your 
      default-mouse for scratching. Selecting your default pointer will 
      cause terminatorX to crash. See the "Using a turntable" section 
      on the terminatorX homepage for details.</para>

    </sect2>

    <sect2 id="USERINTERFACETAB">

      <title><emphasis>User Interface</emphasis> Tab</title>

      <para>With <emphasis>Update Idle</emphasis> / <emphasis>Update 
      Delay</emphasis> you can configure GUI responsiveness: Higher 
      <emphasis>Update Idle</emphasis> will cause the wave display 
      (position display) and flash-widgets to update less often. Higher 
      <emphasis>Update Delay</emphasis> values will cause the parameter 
      widgets to update less often.</para>

    </sect2>

    <sect2 id="colors">

      <title><emphasis>Audio Colors</emphasis> and <emphasis>VU 
      Colors</emphasis> Tab</title>

      <para>Since Version 3.81 it is possible to configure the colors 
      terminatorX' audio widgets. Simply click on the color you want to 
      modify and select the tone you prefer.</para>

    </sect2>

    <sect2 id="MISCTAB">

      <title><emphasis>Misc</emphasis> Tab</title>

      <para>You can now enter the soundfile editor of your choice in 
      the "Sound file editor" field. This editor will be started when 
      clicking the <emphasis>Edit</emphasis>-button in the main panel 
      of the vtt-gui. If you enter for example "myeditor" terminatorX 
      will run "myeditor sample_in_vtt.wav".</para>

      <para>The <emphasis>LADSPA RDF Path</emphasis> defines where 
      liblrdf will look for the RDF files for LADPSA Plugins.</para>

      <para>If <emphasis>Compress set files</emphasis> is activated 
      terminatorX will use zlib to compress set files. This is very 
      usefull for sets that have many events recorded.</para>

      <para>See <xref linkend="MIDI"/> for more details on 
      <emphasis>Restore MIDI Connections</emphasis>. If you disable the 
      <emphasis>Ask for "Quit" Confirmation</emphasis> option 
      terminatorX will no longer ask if you really want to quit.</para>

    </sect2>

  </sect1>

  <sect1 id="CONTACT">

    <title>Contact / Download</title>

    <para>Find out more about terminatorX at it's 
    <ulink url="http://terminatorX.org">homepage</ulink>.</para>

    <para>Send me comments, bug-reports, patches or scratches (see 
    scratches section on the terminatorX homepage) at: 
    <email>alex@lisas.de</email></para>

  </sect1>

</article>