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

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY legal SYSTEM "legal.xml">

]>
<article id="index" lang="en">
  <articleinfo>
    <title>terminatorX - Manual</title>

    <author>
      <firstname>Alexander</firstname>

      <surname>König</surname>
    </author>

    <copyright>
      <year>1999</year>

      <year>2000</year>

      <year>2001</year>

      <year>2002</year>

      <year>2003</year>

      <holder role="mailto:alex@lisas.de">Alexander König</holder>
    </copyright>

    <releaseinfo>Version 3.81</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 &#34;AS IS&#34; 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
      &#34;scratch&#34; 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.cx/bugs.html">bugs</ulink> please help fixing
      them. See <xref linkend="CONTACT" />. Please read this manual and visit
      the <ulink url="http://www.terminatorX.cx">homepage</ulink>.</para>
    </sect2>

    <sect2 id="QUICKSTART">
      <title>Quickstart</title>

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

      <orderedlist inheritnum="ignore" continuation="restarts">
        <listitem>
          <para>If you don&#39;t have <application moreinfo="none">LADSPA</application>
          (Linux Audio Developer&#39;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 moreinfo="none">ladspa.h</filename>.</para>
        </listitem>

        <listitem>
          <para>Install terminatorX (see <filename moreinfo="none">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
          &#34;NONE&#34; 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&#39;s <emphasis>FX</emphasis> button and enable it.</para>
        </listitem>

        <listitem>
          <para>Click on the &#34;Audio Engine&#34;-button to start playback.</para>
        </listitem>

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

        <listitem>
          <para>Press <keycap moreinfo="none">SPACE</keycap> or left mouse
          button to scratch.</para>
        </listitem>

        <listitem>
          <para>Release <keycap moreinfo="none">SPACE</keycap> or left mouse
          button to let the scratch-file run at the turntable&#39;s default
          speed.</para>
        </listitem>

        <listitem>
          <para>Press <keycap moreinfo="none">ESCAPE</keycap> to quit grab
          mode.</para>
        </listitem>
      </orderedlist>
    </sect2>

    <sect2 id="FEATURES">
      <title>Features</title>

      <para>The following list summarizes terminatorX&#39; 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+ (&#62;= 2.0). If your
                  distribution doesn&#39;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&#39;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&#39; sake this information is now located in the
      <filename moreinfo="none">INSTALL</filename> file that came with this
      distribution of terminatorX.</para>
    </sect2>
  </sect1>

  <sect1 id="OPERATION">
    <title>Operation</title>

    <para>TerminatorX&#39; user interface is split up into the main controls
    (master, sequencer, engine controls and menu buttons) and the individual
    turntable&#39;s controls. Each turntable has it&#39;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>New</emphasis></para>

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

          <listitem>
            <para><emphasis>Open</emphasis></para>

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

          <listitem>
            <para><emphasis>Save</emphasis></para>

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

          <listitem>
            <para><emphasis>Save 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&#39; 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.cx</emphasis></para>

            <para>Will try to spawn a browser process to load the URL <ulink
            url="http://terminatorX.cx">http://terminatorX.cx</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&#39;ll have to click on the
          &#34;Mouse Grab&#34; 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 &#34;knob&#34;-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&#39;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&#39;s window list or
      KDE&#39;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&#39;s no sample loaded the button will read
            &#34;NONE&#34; 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&#39;n&#39;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 &#34;mappable&#34;. Note that this includes
            plugins&#39; 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&#39;
            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&#39;
              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&#39;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&#39;s intended for use with
              precisely cut loops.</para>
            </listitem>
          </itemizedlist>
        </sect4>

        <sect4>
          <title>Trigger Panel</title>

          <para>The trigger 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&#39;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 &#34;motor&#34; 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&#39;s main signal within the stereo
          panorama.</para></listitem><listitem><para><emphasis>VU Meter</emphasis></para><para>The
          displayed signal shows the turntable&#39;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 &#34;sequencable&#34; 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>&#34;Waiting for MIDI Event...&#34;</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>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&#39;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&#39;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. 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 float="0">
          <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&#39;t touch
        the input signal. It&#39;s echo-signal is mixed separately from the
        turntable&#39;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&#39;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&#39;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>For more information on a LADSPA plugin, press it&#39;s
        panel&#39;s label and a small info box will pop up.</para>

        <itemizedlist>
          <listitem>
            <para><emphasis>FX Button</emphasis></para>

            <para>Press this button to load a LADSPA plugin into the effect
            queue of the turntable. A menu holding the available
            (terminatorX-&#34;compatible&#34;) LADSPA-plugins will pop up. 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&#39; maximum echo buffer size only.</para>
          </listitem>

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

            <para>Set the echo&#39;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&#39;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&#39;s panning left, echo&#39;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&#39;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&#39;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&#39;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&#39;s set to zero the
      turntable will be triggered with every master trigger, if it&#39;s set
      to 1 it&#39;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&#39;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 &#34;grab mode&#34;. This mode actually blocks the
      mouse (as its input is now used to control the real time parameters) and
      therefore you&#39;ll have to know some mouse/keyboard shortcuts to
      control the software without the GUI.</para>

      <para>Press <keycap moreinfo="none">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
      moreinfo="none">TAB</keycap> or right mouse button to switch to the next
      turntable. Alternatively you can use <keycap moreinfo="none">F1</keycap>
      to <keycap moreinfo="none">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 moreinfo="none">TAB</keycap></entry>

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

            <row>
              <entry><keycap moreinfo="none">F1</keycap> to <keycap
              moreinfo="none">F12</keycap></entry>

              <entry>select turntable 1 to 12</entry>
            </row>

            <row>
              <entry><keycap moreinfo="none">RETURN</keycap></entry>

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

            <row>
              <entry><keycap moreinfo="none">BACKSPACE</keycap></entry>

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

            <row>
              <entry><keycap moreinfo="none">S</keycap></entry>

              <entry>toggles &#34;Sync Client&#34;</entry>
            </row>

            <row>
              <entry><keycap moreinfo="none">SPACE</keycap></entry>

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

            <row>
              <entry><keycap moreinfo="none">ALT</keycap></entry>

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

            <row>
              <entry><keycap moreinfo="none">CTRL</keycap></entry>

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

            <row>
              <entry><keycap moreinfo="none">F</keycap></entry>

              <entry>(&#34;fast&#34;) warp mode (while scratching)</entry>
            </row>

            <row>
              <entry><keycap moreinfo="none">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 moreinfo="none">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 moreinfo="none">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 &#34;New Turntable&#34;
      Button. To load a complete terminatorX-set simply drop the set file
      (*.tX) over the &#34;Load Set&#34; 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 &#38; pitch</para>
        </listitem>

        <listitem>
          <para>scratching</para>
        </listitem>

        <listitem>
          <para>(turntable) volume &#38; 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 &#34;Linux Audio Developer&#39;s Simple Plugin API&#34; 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 plugins (as is that queue) for now. This is why terminatorX will
      load plugins with <emphasis>one</emphasis> audio-in port and
      <emphasis>one</emphasis> audio-out port 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 plugin-menu that pops up when the
      <emphasis>FX</emphasis> button is clicked. Depending on whether the
      terminatorX binary you&#39;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. 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&#39;s say you store your
      plugins in <filename moreinfo="none">/usr/lib/ladspa</filename> and
      <filename moreinfo="none">/home/yourlogin/plugins</filename> then you
      would have to set:</para>

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

      <para>As a fallback terminatorX will look in the standard directories
      <filename moreinfo="none">/usr/lib/ladspa</filename> and <filename
      moreinfo="none">/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 moreinfo="none">/etc/profile</filename> or wherever you
      prefer).</para>

      <sect3 id="LIBLRDF">
        <title>liblrdf support</title>

        <para>Release 3.80 introduces support for Steve Harris&#39; 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&#39; 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&#39;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 &#34;terminatorX&#34;. 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 &#34;<emphasis>Restore MIDI Connections</emphasis>&#34;
      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&#39;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&#39;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&#39;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="2">
          <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 &#39;C&#39;, the next to &#39;C#&#39;, the next
      to &#39;D&#39; and so on. The &#34;function&#34; 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&#39;s available from the <ulink
      url="http://terminatorX.cx/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&#39; 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 moreinfo="none">~/.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&#39;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&#39; size the better terminatorX will perform. The
      default setting of <emphasis>9</emphasis> should be acceptable in most
      conditions, but if you here &#34;clicks&#34;, or &#34;drops&#34; 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&#39;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&#39;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&#39;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 &#34;Using a turntable&#34; 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&#39; 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
      &#34;Sound file editor&#34; 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 &#34;myeditor&#34; terminatorX will
      run &#34;myeditor sample_in_vtt.wav&#34;.</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 &#34;Quit&#34; 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&#39;s <ulink
    url="http://www.terminatorX.cx">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>