1 <?xml version='1.0' encoding='UTF-8'?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4 <!ENTITY legal SYSTEM "legal.xml">
7 <article id="index" lang="en">
9 <title>terminatorX - Manual</title>
11 <firstname>Alexander</firstname>
12 <surname>König</surname>
22 <holder role="mailto:alex@lisas.de">Alexander König</holder>
25 <releaseinfo>Version 3.82</releaseinfo>
27 <legalnotice id="legalnotice">
28 <para>Permission is granted to copy, distribute and/or modify this
29 document under the terms of the GNU Free Documentation License (GFDL),
30 Version 1.1 or any later version published by the Free Software
31 Foundation with no Invariant Sections, no Front-Cover Texts, and no
32 Back-Cover Texts. You can find a copy of the GFDL at this <ulink
33 type="help" url="ghelp:fdl">link</ulink> or in the file COPYING-DOCS
34 distributed with this manual.</para>
36 <para>Many of the names used by companies to distinguish their products
37 and services are claimed as trademarks. Where those names appear in any
38 ScrollKeeper documentation, and the members of the ScrollKeeper Project
39 are made aware of those trademarks, then the names are in capital
40 letters or initial capital letters.</para>
42 <para>DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED UNDER
43 THE TERMS OF THE GNU FREE DOCUMENTATION LICENSE WITH THE FURTHER
44 UNDERSTANDING THAT: <orderedlist><listitem><para>DOCUMENT IS PROVIDED ON
45 AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
46 OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE DOCUMENT
47 OR MODIFIED VERSION OF THE DOCUMENT IS FREE OF DEFECTS MERCHANTABLE, FIT
48 FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE
49 QUALITY, ACCURACY, AND PERFORMANCE OF THE DOCUMENT OR MODIFIED VERSION
50 OF THE DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR MODIFIED VERSION
51 PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL WRITER, AUTHOR OR
52 ANY CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, REPAIR OR
53 CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF
54 THIS LICENSE. NO USE OF ANY DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT
55 IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER; AND</para></listitem><listitem><para>UNDER
56 NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER IN TORT (INCLUDING
57 NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL THE AUTHOR, INITIAL WRITER,
58 ANY CONTRIBUTOR, OR ANY DISTRIBUTOR OF THE DOCUMENT OR MODIFIED VERSION
59 OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO
60 ANY PERSON FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR
61 CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION,
62 DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR
63 MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR LOSSES ARISING OUT OF OR
64 RELATING TO USE OF THE DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT,
65 EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH
66 DAMAGES.</para></listitem></orderedlist></para>
70 <sect1 id="INTRODUCTION">
71 <title>Introduction</title>
74 <title>What it is</title>
76 <para>terminatorX is a realtime audio synthesizer that allows you to
77 "scratch" on digitally sampled audio data (*.wav, *.au, *.ogg,
78 *.mp3, etc.) the way hiphop-DJs scratch on vinyl records. It features
79 multiple turntables, realtime effects (buit-in as well as <ulink
80 url="http://www.ladspa.org">LADSPA</ulink> plugin effects), a sequencer
81 and MIDI interface - all accessible through an easy-to-use gtk+ GUI.</para>
83 <para>This is software may have <ulink
84 url="http://terminatorX.cx/bugs.html">bugs</ulink> please help fixing
85 them. See <xref linkend="CONTACT" />. Please read this manual and visit
86 the <ulink url="http://www.terminatorX.cx">homepage</ulink>.</para>
89 <sect2 id="QUICKSTART">
90 <title>Quickstart</title>
92 <para>Try the following steps:</para>
94 <orderedlist inheritnum="ignore" continuation="restarts">
96 <para>If you don't have <application moreinfo="none">LADSPA</application>
97 (Linux Audio Developer's Simple Plugin API) installed, go and
98 get it from the <ulink url="http://www.ladspa.org">LADSPA-homepage</ulink>
99 and install the SDK. terminatorX requires <filename moreinfo="none">ladspa.h</filename>.</para>
103 <para>Install terminatorX (see <filename moreinfo="none">INSTALL</filename>
108 <para>If you want to use the <ulink
109 url="http://jackit.sourceforge.net">JACK</ulink> backend run jackd
110 before starting terminatorX.</para>
114 <para>Run terminatorX</para>
118 <para>Setup Audio Output via <emphasis>Options/Preferences</emphasis>.</para>
122 <para>Load an audiofile into the available turntable (you can add
123 more turntables if you want) (Hint: Click on the button that holds
124 "NONE" to load an audiofile, or drop one over the audiofile
125 display from your GNOME filemanager.</para>
129 <para>Load a LADSPA plugin of your choice by clicking the
130 turntable's <emphasis>FX</emphasis> button and enable it.</para>
134 <para>Click on the "Audio Engine"-button to start playback.</para>
138 <para>Click on the "Mouse-Grab"-button to enter grab mode.
139 The turntable with the red border has the input focus.</para>
143 <para>Press <keycap moreinfo="none">SPACE</keycap> or left mouse
144 button to scratch.</para>
148 <para>Release <keycap moreinfo="none">SPACE</keycap> or left mouse
149 button to let the scratch-file run at the turntable's default
154 <para>Press <keycap moreinfo="none">ESCAPE</keycap> to quit grab
160 <sect2 id="FEATURES">
161 <title>Features</title>
163 <para>The following list summarizes terminatorX' main features:</para>
167 <para>Scratching</para>
171 <para>Multiple turntables</para>
175 <para>Built-in Sequencer</para>
179 <para>MIDI Interface</para>
183 <para>Pitch / Volume settings for each turntable</para>
187 <para>Effects (Lowpass/Echo) configurable for each turntable</para>
191 <para>Syncing tables to one master turntable</para>
195 <para>Broad audiofile-type support</para>
199 <para>Record to disk</para>
203 <para>Save and Load turntable sets (.tX - files)</para>
207 <para>Support for LADSPA plugins.</para>
211 <para>Support for the <emphasis>JACK Audio Connection Kit</emphasis></para>
215 <para>and more</para>
220 <sect2 id="REQUIREMENTS">
221 <title>Requirements</title>
223 <para>To run terminatorX a system should meet the following
228 <para>Software</para>
232 <para>required</para>
236 <para>Linux, FreeBSD or the like</para>
240 <para>glibc2 (pthreads).</para>
244 <para>XFree86 (with DGA DirectMouse support). Note that
245 XFree86 Release 4.0 has a bug resulting in broken
246 DirectMouse support. This has been fixed by the XFree86-Team
247 with Release 4.0.1 available from your distribution or the
248 <ulink url="http://www.xfree86.org">XFree86 homepage</ulink>.</para>
252 <para>The Gimp Toolkit: gtk+ (>= 2.0). If your
253 distribution doesn't provide a current version of gtk+
254 get it from the <ulink url="http://www.gtk.org">gtk+
255 homepage</ulink>.</para>
259 <para>LADSPA - the Linux Audio Developer's Simple Plugin
260 API. Get it from the <ulink url="http://www.ladpsa.org">LADSPA
261 homepage</ulink></para>
265 <para>a compiler (gcc)</para>
271 <para>optional (but highly recommended)</para>
275 <para><ulink url="http://plugin.org.uk/releases/lrdf/">liblrdf</ulink>
276 for easier handling of LADSPA plugins</para>
280 <para><ulink url="http://www.mars.org/home/rob/proj/mpeg/">mad</ulink>
281 for loading mp3 files.</para>
285 <para><ulink url="http://www.xiph.org/ogg/vorbis/">libvorbis</ulink>
286 for loading ogg files.</para>
290 <para><ulink url="http://jackit.sourceforge.net">libjack</ulink>
291 for JACK support.</para>
295 <para><ulink url="http://xmlsoft.org/">libxml2</ulink> to
296 read terminatorX set and rc files</para>
300 <para><ulink url="http://www.gzip.org/zlib/">zlib</ulink> to
301 create compressed XML set files to save diskspaces</para>
305 <para><ulink url="http://www.68k.org/~michael/audiofile/">libaudiofile</ulink>
306 for loading misc other audio files.</para>
310 <para><ulink url="???">libcap</ulink> for capabilties
316 url="http://www-ti.informatik.uni-tuebingen.de/~hippm/mpg123.html">mpg123</ulink>
317 for mp3 pre-listening (and fallback loading if mad is not
322 <para><ulink url="http://www.xiph.org/ogg/vorbis/">ogg123</ulink>
323 for ogg pre-listening (and fallback loading if libvorbis is
324 not installed).</para>
329 url="http://home.sprynet.com/~cbagwell/sox.html">sox</ulink>
330 for misc files pre-listening (and fallback loading of misc
339 <para>Hardware</para>
343 <para>An <ulink url="http://www.alsa-project.org">ALSA</ulink>
344 or OSS compatible soundcard capable of stereo output.</para>
348 <para>A good clean mouse and pad, a good X-Pointer setup.</para>
354 <para>A note on performance: terminatorX is known to run satisfyingly on
355 pentium-class systems (or above of course). Increasing the number of
356 turntables or plugins will of course require more performant systems.</para>
359 <sect2 id="INSTALLATION">
360 <title>Installation</title>
362 <para>For GNU-standards' sake this information is now located in the
363 <filename moreinfo="none">INSTALL</filename> file that came with this
364 distribution of terminatorX.</para>
368 <sect1 id="OPERATION">
369 <title>Operation</title>
371 <para>TerminatorX' user interface is split up into the main controls
372 (master, sequencer, engine controls and menu buttons) and the individual
373 turntable's controls. Each turntable has it's own interface split
374 up into a control and a audio panel (see <xref linkend="TURNTABLECONTROLS" />).</para>
379 <para>To clean-up the user interface a bit further some functions have
380 been moved into a more standard menu bar for the main window (with
381 release 3.80). The following sub-menus are available:</para>
383 <sect3 id="FILEMENU">
384 <title><emphasis>File</emphasis> Menu</title>
386 <para>The <emphasis>File</emphasis> menu features these functions:</para>
390 <para><emphasis>New</emphasis></para>
392 <para>Erases all existing turntables and sequencer events and
393 creates a new and untouched turntable.</para>
397 <para><emphasis>Open</emphasis></para>
399 <para>Allows restoring of a previously saved terminatorX set file.</para>
403 <para><emphasis>Save</emphasis></para>
405 <para>Saves the current turntables and events in a terminatorX set
410 <para><emphasis>Save As</emphasis></para>
412 <para>Like <emphasis>Save</emphasis> but prompts for a new file
417 <para><emphasis>Quit</emphasis></para>
422 <sect3 id="TURNTABLESMENU">
423 <title><emphasis>Turntables</emphasis> Menu</title>
425 <para>The <emphasis>Turntables</emphasis> menu features these
430 <para><emphasis>Add Turntable</emphasis></para>
432 <para>Adds a new turntable to the current set of turntables.</para>
436 <para><emphasis>Assign Default MIDI Mappnigs</emphasis></para>
438 <para>Will assign the Default MIDI Mappings (see <xref
439 linkend="MIDI" />) to all standard parameters. Existing
440 mappings will not be overridden.
445 <para><emphasis>Auto Assign Default MIDI Mappings</emphasis></para>
447 <para>When this option is enabled will always re-apply the Default
448 MIDI Mappings (see <xref linkend="MIDI" />) whenever you load a
449 set, add a new turntable or create a new set. Existing
450 mappings will not be overridden.</para>
454 <para><emphasis>Clear MIDI Mappings</emphasis></para>
456 <para>Removes all currently assigned MIDI mappings.</para>
460 <para><emphasis>Record Audio to Disk</emphasis></para>
462 <para>On activation of this option, terminatorX will prompt for a
463 file name for the RIFF/Wave file to create. Once activated
464 terminatorX will start recording audio to disk the next time the
465 audio engine is started - either by pressing the Power or the Play
466 button. Recording will stop when the audio engine is stopped
467 again. The created RIFF/Wave file will be a 16Bit/Stereo wave-file
468 with the sampling rate selected for the current audio backend.</para>
473 <sect3 id="SEQUENCERMENU">
474 <title><emphasis>Sequencer</emphasis> Menu</title>
476 <para>The <emphasis>Sequencer</emphasis> (see <xref
477 linkend="SEQUENCER" /> for general information on the sequencer) menu
478 features these functions:</para>
482 <para><emphasis>Delete All</emphasis> submenus</para>
484 <para>These submenus allow you to delete sequencer events of a
485 specific parameter or all events for a complete turntable. After
486 selecting the the parameter/turntable of your choice a dialog will
487 pop-up that allows you to delete all events from either:</para>
491 <para>the beginning of the song upto the current song position</para>
495 <para>the current song position upto the end of the song</para>
499 <para>the beginning to the end of the song (all events)</para>
505 <para><emphasis>Delete All Events</emphasis></para>
507 <para>Works the same as the <emphasis>Delete All</emphasis>
508 submenus but selects <emphasis>all</emphasis> events for
509 <emphasis>all</emphasis> turntables.</para>
513 <para><emphasis>Confirm Recorded Events</emphasis></para>
515 <para>Usually terminatorX will add all recorded events of a take
516 to the song event list as soon as you hit the
517 <emphasis>Stop</emphasis> button for the sequencer. If you enable
518 <emphasis>Confirm Recorded Events</emphasis> terminatorX will ask
519 you whether the recorded events should really be fed into the song
520 list. This makes it much easier to record a certain part over and
521 over again until you get it right.</para>
526 <sect3 id="OPTIONSMENU">
527 <title><emphasis>Options</emphasis> Menu</title>
529 <para>The <emphasis>Options</emphasis> menu features these functions:</para>
533 <para><emphasis>Fullscreen</emphasis></para>
535 <para>Maximizes the terminatorX main windows to use the complete
536 screen. Note that this requires a NETWM compliant window manager
537 to work. By toggling this option again terminatorX' window can
538 be resized back to the previous state again. The setting will be
539 stored in the <filename>~/.terminatorXrc</filename> file.</para>
543 <para><emphasis>Preferences</emphasis></para>
545 <para>Will pop up the Preferences dialog. For more details on
546 configuration itself see <xref linkend="CONFIGURATION" />.</para>
551 <sect3 id="HELPMENU">
552 <title><emphasis>Help</emphasis> Menu</title>
554 <para>The <emphasis>Help</emphasis> menu features these functions:</para>
558 <para><emphasis>Contents</emphasis></para>
560 <para>Starts a <emphasis>gnome-help</emphasis> (aka
561 <emphasis>yelp</emphasis>) process to display the very manual you
562 are reading right now.</para>
566 <para><emphasis>About</emphasis></para>
568 <para>Selecting this menu item will cause a small dialog to pop up
569 that contains some information on the compile time settings for
570 the terminatorX binary as well as the license.</para>
574 <para><emphasis>Visit terminatorX.cx</emphasis></para>
576 <para>Will try to spawn a browser process to load the URL <ulink
577 url="http://terminatorX.cx">http://terminatorX.cx</ulink> - for
578 easy update checking or just unecessary bloat.</para>
584 <sect2 id="MAINCONTROLS">
585 <title>Main Controls</title>
587 <para>The controls of the master GUI are located in the top and the
588 right bar of the terminatorX main window.</para>
592 <para><emphasis>Audio Engine Power / Mouse Grab</emphasis></para>
594 <para>With the Audio Engine Button you can en- and disable the audio
595 playback engine without activating the sequencer. Unlike earlier
596 versions you will not automatically enter mouse-grab mode so you can
597 modify volume/pitch/echo settings etc. while you actually hear what
600 <para>Some functions are not available when the audio engine is on,
601 their controls will be marked insensitive when you enable the
602 engine. To actually enter grab mode you'll have to click on the
603 "Mouse Grab" button. See <xref linkend="GRABMODE" /> to find
604 out how to control the software then.</para>
608 <para><emphasis>Sequencer Play / Record / Stop</emphasis></para>
610 <para>Please read <xref linkend="SEQUENCER" /> to find out more
611 about the sequencer.</para>
615 <para><emphasis>Master Volume / Pitch</emphasis></para>
617 <para>The volume and pitch settings of the individual turntables are
618 relative to these master settings. This information will be stored
619 within the .tX set files.</para>
624 <sect2 id="TURNTABLECONTROLS">
625 <title>Turntable Controls</title>
627 <para>The turntable GUI contains multiple controls and the real time
628 displays for each turntable. To save some space on your desktop and to
629 give terminatorX the traditional audio-application look, terminatorX
630 features "knob"-widgets. These widgets work pretty
631 straight-forward: click somewhere within the widget and keep the left
632 mouse-button pressed. Now move the mouse up and down or left and right
633 to increase/decrease the control's value. All those widget are
634 coupled with a text entry field since 3.70, which allows you to enter
635 values directly.</para>
637 <para>A turntable is visualized by two panels: the control and the audio
638 panel. These are no longer combined for better layout management.</para>
640 <para>Sometimes you might find a certain audio or control panel
641 unnecessary - simply eating up space. Since release 3.73 it is possible
642 to minimize audio and control panels to the <emphasis>panel bar</emphasis>
643 with the tiny button with a blue bar icon in the upper right edge of
644 each panel. This bar works just like GNOME's window list or
645 KDE's kicker: When a panel is minimized a button in the bar will
646 appear, representing the minimized window. On clicking this button the
647 button will be removed and the minimized panel is displayed again. When
648 no panels are minimized the panel bar automatically disappears to save
649 display space.</para>
652 <title>Turntable Audio Panel</title>
654 <para>The complete audio-file loaded into a turntable is displayed in
655 the green-on-black audio-widget. When playing terminatorX will
656 indicate the current position within the sample with a red cursor (a
657 blue/green cursor indicates the turntable is muted).</para>
659 <para>Additionally there are some controls above the audio-display:</para>
663 <para><emphasis>Turntable Label</emphasis></para>
665 <para>This label indicates the turntables name. The name can be
666 set via the control panel</para>
670 <para><emphasis>File Button</emphasis></para>
672 <para>This button holds the name of the audio-file currently
673 loaded. When there's no sample loaded the button will read
674 "NONE" to indicate the current status. Click on this
675 button to get a menu from which you can load/reload a sound file
676 or run an external soundfile editor. Alternatively you can
677 drag'n'drop files over the audio-display to load them.</para>
680 <title>The File Button Menu</title>
683 <para><emphasis>Load File</emphasis></para>
685 <para>Choose this menu entry to select a soundfile from the
686 file-selection dialog that will pop-up.</para>
690 <para><emphasis>Reload File</emphasis></para>
692 <para>Choose this menu entry to re-read the audio-file.</para>
696 <para><emphasis>Edit File</emphasis></para>
698 <para>This menu entry will run the external audiofile-editor
699 (that can be specified via the options-dialog) with the
700 current audio-file as a parameter. Choose reload after editing
701 and saving the file.</para>
707 <para><emphasis>Mouse Mapping</emphasis></para>
709 <para>terminatorX allows mapping misc parameters to the mouse axis
710 of your choice. These mappings will be activated in grab mode, so
711 if you move your mouse in X or Y direction in grab mode the
712 parameters you selected from this menu will be affected (for this
713 turntable). Since Version 3.70 this mappings are no longer
714 hardcoded to built-in controls but available for all parameters
715 that qualify as "mappable". Note that this includes
716 plugins' controls as well.</para>
720 <para><emphasis>MIDI Mapping</emphasis></para>
722 <para>This button is available only if terminatorX was built with
723 ALSA MIDI support and the sequencer input port was created
724 successfully on startup. For more information on terminatorX'
725 MIDI interface see <xref linkend="MIDI" />.</para>
731 <title>Turntable Controls</title>
733 <para>These controls are now grouped within functional panels. The
734 number of panels depends on the number of plugins loaded. terminatorX
735 allows hiding the controls not required via the yellow triangle
736 button. To un-hide just click the button again. The first panels are
737 the standard controls for a turntable, then follows the dynamic
738 FX-section and below that follow the pitch and volume controls.</para>
741 <title>Main Panel</title>
745 <para><emphasis>Name Field</emphasis></para>
747 <para>The main panel features a text entry field that allows
748 setting a name for the related turntable. The Labels for the
749 controls and the audio-display will update accordingly.</para>
753 <para><emphasis>Delete Button</emphasis></para>
755 <para>Pressing this button remove the turntable from the current
756 setup. Note that all sequencer events recorded for this
757 turntable will be erased, too.</para>
761 <para><emphasis>Pitch Adj. Button</emphasis></para>
763 <para>Using two (or more) loops and terminatorX'
764 synchronization facility usually requires adjusting the pitch of
765 the loops so that the turntables play in sync. For precisely cut
766 loops this usually means making them run equally fast or one
767 running twice as fast as the other etc. Manually finding the
768 necessary pitch values usually consumes a significant amount of
769 time so the feature <emphasis>Pitch Adjust</emphasis> helps
770 speeding up this process.</para>
772 <para>Clicking this button will cause the <emphasis>Compute
773 Pitch</emphasis> dialog to pop up. With this dialog it is
774 possible to specify how many loops of this turntable should be
775 played as fast as a certain amount of loops of the master
776 turntable. After pressing the <emphasis>Ok</emphasis> button
777 terminatorX will adjust the turntable's ptich accordingly in
778 order to match the given playback speed requirements.</para>
780 <para>Note that this feature is proabably useless when loading
781 complete songs into terminatorX - it's intended for use with
782 precisely cut loops.</para>
788 <title>Trigger Panel</title>
790 <para>The trigger panel holds all controls related to triggering the
791 turntable. For more details on synchronization see <xref
792 linkend="SYNCHRONIZATION" />.</para>
796 <para><emphasis>Trigger! Button</emphasis></para>
798 <para>Pressing this button triggers the turntable now. With the
799 audio engine enabled this will cause the turntable to start
800 playing back audio from the beginning of the sample.</para>
804 <para><emphasis>Stop Button</emphasis></para>
806 <para>Guess what, this stops this turntable's
807 audio-playback.</para>
811 <para><emphasis>Master Button</emphasis></para>
813 <para>Enabling this button makes this turntable the
814 <emphasis>sync-master</emphasis>. Note that only
815 <emphasis>one</emphasis> turntable at a time can be the
820 <para><emphasis>Client Button</emphasis></para>
822 <para>This button marks the turntable as <emphasis>sync-client</emphasis>,
823 so it will be triggered with the master automatically.</para>
827 <para><emphasis>Sync-Cycles Selection</emphasis></para>
829 <para>The sync cycles determine how often a sync-client should
830 be triggered. With a setting of zero the sync-client will be
831 (re-)triggered with <emphasis>every</emphasis> trigger of the
832 sync-master. A setting of 1 will (re-)trigger the client every
833 <emphasis>second</emphasis> master-trigger and so on.</para>
837 <para>Below the effect queue a turntable shows some more controls:
838 <itemizedlist><listitem><para><emphasis>Pitch Control</emphasis></para><para>The
839 pitch control allows setting the default playback speed for that
840 turntable (the "motor" speed). Negative values will result
841 in the sample being played backwards.</para></listitem><listitem><para><emphasis>PAN
842 Control</emphasis></para><para>This parameter allows setting the
843 position of the turntable's main signal within the stereo
844 panorama.</para></listitem><listitem><para><emphasis>VU Meter</emphasis></para><para>The
845 displayed signal shows the turntable's current signal not
846 including the echo-signal which is mixed separately.</para></listitem></itemizedlist></para>
850 <sect3 id="PARAMETERMENU">
851 <title>Parameter Menu</title>
853 <para>TerminatorX can record events for nearly all parameters of a
854 turntable. All of these so-called "sequencable" parameters
855 have an extra pop-up menu since Version 3.81. Simply right-click on
856 the knob, button, slider of the parameter you want to setup, and a
857 menu with the following options will appear:<itemizedlist><listitem><para><emphasis>MIDI
858 Learn</emphasis></para><para>This options provides an easy method to
859 select the MIDI control to modify the parameter you select. If you
860 choose this menu entry, a tiny dialog box will pop up that reads
861 <emphasis>"Waiting for MIDI Event..."</emphasis>. The first
862 MIDI event terminatorX receives will now be mapped to control this
863 parameter.</para></listitem><listitem><para><emphasis>Remove MIDI
864 Binding</emphasis></para><para>If a MIDI event has been bound to a
865 parameter it can be removed by selecting this menu entry.</para></listitem><listitem><para><emphasis>Set
866 Upper MIDI Bound</emphasis></para><para>Sometimes it is preferable to
867 modify a certain parameter only within a specific value range - this
868 can be achieved with this option - by setting an upper and a lower
869 bound for the MIDI control of this parameter. When you select this
870 menu entry, the current setting of this parameter will be used as the
871 upper bound for the parameter's MIDI mapping.</para></listitem><listitem><para><emphasis>Reset
872 Upper MIDI Bound</emphasis></para><para>If an upper MIDI bound was set
873 for this parameter it can be removed by selecting this menu entry.</para></listitem><listitem><para><emphasis>Set
874 Lower MIDI Bound</emphasis></para><para>Works just like setting the
875 uper MIDI bound: when you select this menu entry, the current setting
876 of this parameter will be used as the lower bound for the
877 parameter's MIDI mapping.</para></listitem><listitem><para><emphasis>Reset
878 Lower MIDI Bound</emphasis></para><para>If a lower MIDI bound was set
879 for this parameter it can be removed by selecting this menu entry.</para></listitem><listitem><para><emphasis>Delete
880 Sequencer Events</emphasis></para><para>Just like the Sequencer menu
881 (see <xref linkend="SEQUENCERMENU" />) this entry allows you to delete
882 events recorded for this specific parameter.</para></listitem></itemizedlist></para>
886 <title>The Effect Queue</title>
888 <para>With release 3.70 the effects are no longer hardcoded into the
889 turntable. The effects are now arranged within an per-turntable
890 effect-queue. Additionally Version 3.82 introduces a second effect-queue
891 that follows the first: the queue for stereo LADSPA plugin effects.
892 The effect sequence is configurable by the user. To move
893 an effect to higher position within the queue, press the
894 <emphasis>blue upward arrow button</emphasis>. This will cause the
895 effect to be rendered <emphasis>before</emphasis> the following
896 effects. The <emphasis>blue downward arrow button</emphasis> will move
897 the effect down by one position. It will then be rendered
898 <emphasis>after</emphasis> the preceding effects.</para>
900 <para>There are two types of effects: the traditional built-in effects
901 (Lowpass and Echo) and LADSPA plugins. The built-in effects are always
902 available and cannot be removed (but disabled). There can be only one
903 instance of a built-in effect. The LADSPA plugins on the other hand
904 may be instantiated multiple times and can be removed from the effect
905 queue. Press the <emphasis>blue cross button</emphasis> to achieve
909 <title>An example for a terminatorX effect queue</title>
911 <graphic fileref="figures/signalflow.png" format="PNG" />
914 <para>Now since release 3.71 the built-in echo effect is treated
915 differently from other effects. Where all other effects feed their
916 signal back into the effect queue the echo effect doesn't touch
917 the input signal. It's echo-signal is mixed separately from the
918 turntable's main signal to allow a different panning value for the
919 echo-signal. This mode of operation does have some side-effects:
920 imagine a lowpass filter with a position after the echo effect in the
921 effect queue. This will result in the turntable's main signal
922 being lowpass-filtered but it will leave the echo-signal
923 lowpass-unfiltered.</para>
925 <para>Some may call this behaviour a bug - whereas I would consider it
926 a feature ;). Anyway if the above description didn't clear things
927 up maybe the displayed figure does. It shows a schematic effect queue
928 with the built-in effects and two LADSPA effects enabled. Now with
929 this setup you will not hear anything from the second LADSPA effect in
930 the echo-signal.</para>
932 <para>Release 3.82 introduces a menu for each LADSPA plugin. Simply
933 click on the Plugin's label to operate the menu. Aside of displaying
934 detailed information about a plugin, the menu also contains some new
935 functionality: <emphasis>Add Dry/Wet Control</emphasis>. When activated
936 the effect receives an extra Dry/Wet control that allows you to
937 modify to what extent the effect will actually effect the turntable's
938 signal. The extra control doesn't differ from the other controls:
939 you can record events for it, etc. The additional control can be
940 removed via the very same menu item that adds the control.
945 <para><emphasis>FX</emphasis> and
946 <emphasis>Stereo FX Buttons</emphasis></para>
948 <para>Press this button to load a LADSPA plugin into the effect
949 queue of the turntable. A menu holding the available
950 (terminatorX-"compatible") LADSPA-plugins will pop up - mono
951 plugins are available from the <emphasis>FX</emphasis> menu, stereo
952 plugins from the <emphasis>Stereo FX</emphasis> menu. The
953 plugins are grouped within submenus according to the modules the
954 plugins are contained in. Simply select the plugin you want to
955 load from this menu and a panel for it will pop up at the end of
956 the effect queue.</para>
958 <para>Note that due to the wide parameter ranges some LADSPA
959 plugins have they sometimes might be hard to control with the knob
960 widget. In these cases you might want to use the text field to
961 enter values. For more details on plugins see <xref
962 linkend="LADSPAPLUGINS" />.</para>
968 <title>Lowpass Panel</title>
970 <para>terminatorX features a built-in resonating lowpass filter that
971 can be configured with this panel.</para>
975 <para><emphasis>Enable Button</emphasis></para>
977 <para>Activating this button will enable the lowpass filter for
978 this turntable.</para>
982 <para><emphasis>Input Gain Control</emphasis></para>
984 <para>With this parameter you can amplify the signal that goes
985 into the lowpass filter if required.</para>
989 <para><emphasis>Frequency Control</emphasis></para>
991 <para>Use this parameter to set the cutoff frequency for the
992 lowpass filter. Minimum: 0=0Hz, Maximum: 1=22KHz.</para>
996 <para><emphasis>Resonance</emphasis></para>
998 <para>Use this parameter to set the resonance-value. Minimum: 0=no
999 resonance, Maximum: 1=max resonance.</para>
1005 <title>Echo Panel</title>
1007 <para>Additionally terminatorX features a built-in echo effect. It can
1008 be configured with this panel.</para>
1012 <para><emphasis>Enable Button</emphasis></para>
1014 <para>Activating this button will enable the echo effect for this
1019 <para><emphasis>Duration Control</emphasis></para>
1021 <para>Use this parameter to set the length of the echo. The
1022 duration parameter scales to the actual sample length: so if you
1023 set it to 0.5 you will hear the echo when the red playback cursor
1024 is half way through the sample. This is true for samples that are
1025 shorter than terminatorX' maximum echo buffer size only.</para>
1029 <para><emphasis>Feedback Control</emphasis></para>
1031 <para>Set the echo's feedback amount with this parameter.</para>
1035 <para><emphasis>Volume Control</emphasis></para>
1037 <para>This parameter can additionally amplify the echo signal.
1038 Unlike the feedback parameter above this parameter has no
1039 influence on the signal fed back into the echo-buffer, it effects
1040 merely the playback volume of the echo signal.</para>
1044 <para><emphasis>Pan Control</emphasis></para>
1046 <para>The echo effect differs from other effects as it's
1047 output signal will be mixed separately. The main goal here is to
1048 allow positioning the echo signal at a position in the stereo
1049 panorama that differs from the main panning position of the
1050 turntable to achieve a somewhat spacial effect. The easy example
1051 is: turntable's panning left, echo's panning right. As
1052 both pan parameters are sequenceable you can create nice motion
1053 effects from this starting point.</para>
1059 <sect2 id="SYNCHRONIZATION">
1060 <title>Synchronization</title>
1062 <para>Let's start off with an example: Say you have two drum loops
1063 and one bassline loaded in three turntables. Of course you want these
1064 samples to be triggered at the same time but you don't want to
1065 invest time to cut them to the exact length. Therefore you decide which
1066 of the drum loops to make the sync master. You'll have to do this
1067 before you enable the audio engine (for now). Only one turntable can be
1068 the sync master. Now you can make the other two sync clients which will
1069 cause them to be (re-)triggered whenever the master is (re-)triggered.
1070 The number you can select to the right of the <emphasis>client button</emphasis>
1071 sets the trigger delay for the button: if it's set to zero the
1072 turntable will be triggered with every master trigger, if it's set
1073 to 1 it'll be triggered every 2nd master trigger and so on.</para>
1075 <para>A nice side effect of this feature is: you can now scratch the
1076 second (sync client) drum loop and no matter whether you're
1077 scratching is good or not the beat will be triggered correctly again ;)</para>
1080 <sect2 id="GRABMODE">
1081 <title>Grab Mode Operation</title>
1083 <para>After pressing the <emphasis>Mouse Grab button</emphasis>
1084 terminatorX enters "grab mode". This mode actually blocks the
1085 mouse (as its input is now used to control the real time parameters) and
1086 therefore you'll have to know some mouse/keyboard shortcuts to
1087 control the software without the GUI.</para>
1089 <para>Press <keycap moreinfo="none">ESCAPE</keycap> to quit grab mode.</para>
1091 <para>Select the turntable with input focus: The first turntable to hold
1092 the input focus will be the first turntable. You can now use <keycap
1093 moreinfo="none">TAB</keycap> or right mouse button to switch to the next
1094 turntable. Alternatively you can use <keycap moreinfo="none">F1</keycap>
1095 to <keycap moreinfo="none">F12</keycap> to select turntable 1 to 12.</para>
1097 <para>Now the turntable that has the focus is the one you will
1098 manipulate with your mouse and keyboard inputs: Note that you can
1099 actually map different functions to the mouse x/y axis - so what
1100 actually happens when you move your mouse depends on what you select via
1101 the <emphasis>Mouse Mapping</emphasis> for each turntable.</para>
1104 <title>Keyboard Controls in Grab Mode</title>
1111 <entry>Function</entry>
1117 <entry><keycap moreinfo="none">TAB</keycap></entry>
1119 <entry>select next turntable</entry>
1123 <entry><keycap moreinfo="none">F1</keycap> to <keycap
1124 moreinfo="none">F12</keycap></entry>
1126 <entry>select turntable 1 to 12</entry>
1130 <entry><keycap moreinfo="none">RETURN</keycap></entry>
1132 <entry>triggers the turntable</entry>
1136 <entry><keycap moreinfo="none">BACKSPACE</keycap></entry>
1138 <entry>stops the turntable</entry>
1142 <entry><keycap moreinfo="none">S</keycap></entry>
1144 <entry>toggles "Sync Client"</entry>
1148 <entry><keycap moreinfo="none">SPACE</keycap></entry>
1150 <entry>while pressed turntable speed is mapped to mouse speed
1151 (scratching!)</entry>
1155 <entry><keycap moreinfo="none">ALT</keycap></entry>
1157 <entry>mute on/off</entry>
1161 <entry><keycap moreinfo="none">CTRL</keycap></entry>
1163 <entry>mute on/off (inverted)</entry>
1167 <entry><keycap moreinfo="none">F</keycap></entry>
1169 <entry>("fast") warp mode (while scratching)</entry>
1173 <entry><keycap moreinfo="none">W</keycap></entry>
1175 <entry>same as above but the audio will be muted while warping</entry>
1182 <title>Mouse Button Controls in Grab Mode</title>
1187 <entry>Mouse Button</entry>
1189 <entry>Function</entry>
1195 <entry><emphasis>Left button</emphasis></entry>
1197 <entry>same as <keycap moreinfo="none">SPACE</keycap>:
1198 scratching (triggers the turntable when stopped)</entry>
1202 <entry><emphasis>Right button</emphasis></entry>
1204 <entry>select next turntable</entry>
1208 <entry><emphasis>Middle button</emphasis></entry>
1210 <entry>mute on/off</entry>
1216 <para>Scratching works as before: press <keycap moreinfo="none">SPACE</keycap>
1217 or left mouse button to actually scratch: now your mouse controls the
1218 turntables speed. Release it to let that turntable spin at default speed
1222 <sect2 id="DRAGNDROP">
1223 <title>Drag And Drop</title>
1225 <para>Since V3.55 terminatorX provides multiple DND-Drop-Targets for use
1226 with GNOME / gmc (gmc is the GNU Midnight Commander), Nautilus or the
1227 Enlightenment File Manager (efm). You can load an audiofile into an
1228 existing turntable by dragging it from a gmc (or efm or whatever)-window
1229 and drop it over a. the <emphasis>file button</emphasis> (audio-display)
1230 or b. (the easier target ;) over the audio-display (the green on black
1231 widget that displays the audiodata).</para>
1233 <para>To add a file to the set (== to load the file into a *new*
1234 turntable) simply drop the audiofile over the "New Turntable"
1235 Button. To load a complete terminatorX-set simply drop the set file
1236 (*.tX) over the "Load Set" button.</para>
1239 <sect2 id="SEQUENCER">
1240 <title>The Sequencer</title>
1242 <para>Release 3.60 introduced the sequencer. It can record and play back
1243 events for the following parameters:</para>
1247 <para>master volume & pitch</para>
1251 <para>scratching</para>
1255 <para>(turntable) volume & pitch</para>
1259 <para>triggers</para>
1263 <para>loop (on/off)</para>
1267 <para>sync client settings</para>
1275 <para><emphasis>all</emphasis> parameters for the effects. This
1276 includes built-in effects (lowpass and echo) as well as LADSPA
1281 <para>To record events simply press the <emphasis>Record</emphasis>
1282 button of the sequencer, then press the <emphasis>Play</emphasis>
1283 button. All actions (for sequenceable parameters - see above) you now
1284 take will be recorded into the song list. Press <emphasis>Stop</emphasis>
1285 and <emphasis>Play</emphasis> again to see/hear how terminatorX plays
1286 back the events recorded before. You can now record events again for
1287 e.g. another turntable or record other parameters for the same turntable
1288 - whatever you want to do. Recording events for parameters for which
1289 events have been recorded before will result in dubbing: if you touch a
1290 parameter while recording, events previously recorded will be erased
1291 from the moment you touch the parameter until you stop recording.</para>
1293 <para>When recording long sequences/songs you can use the
1294 sequencer-scale to start recording/playback from any song-position you
1295 want. To record a single parameter value at a certain position simply
1296 move the sequencer-scale to that position, press <emphasis>Record,</emphasis>
1297 set the parameter and press <emphasis>Stop</emphasis> again.</para>
1299 <para>To selectively delete events from the sequencer see <xref
1300 linkend="SEQUENCERMENU" /> and <xref linkend="PARAMETERMENU" />.</para>
1303 <sect2 id="LADSPAPLUGINS">
1304 <title>Plugins (LADSPA)</title>
1306 <para>Since release 3.70 terminatorX supports LADSPA-plugins. LADSPA is
1307 the "Linux Audio Developer's Simple Plugin API" which was
1308 designed by developers on the Linux-Audio-Developer-Mailinglist and is
1309 maintained by Richard W.E. Furse. For more information on LADSPA, other
1310 LADSPA-hosts and LADSPA-plugins checkout the <ulink
1311 url="http://www.ladspa.org">LADSPA homepage</ulink>.</para>
1313 <para>Not every plugin is supported by terminatorX though. As the
1314 plugins are inserted into the per-turntable effect-queue, they have to
1315 be mono or (as of Version 3.82) stereo plugins. This is why terminatorX will
1316 load plugins with <emphasis>one</emphasis> or <emphasis>two</emphasis>
1317 audio-in ports and <emphasis>one</emphasis> or <emphasis>two</emphasis>
1318 audio-out ports only.</para>
1320 <para>The decision on whether a plugin is terminatorX-suitable is made
1321 on terminatorX startup, so only plugins that fit into the effect queue
1322 will be offered in the mono plugin-menu that pops up when the
1323 <emphasis>FX</emphasis> button is clicked or in the stereo plugin menu
1324 when the <emphasis>Stereo FX</emphasis> button si clicked. Depending on
1326 terminatorX binary you're using was built with or without liblrdf (<xref
1327 linkend="LIBLRDF" />) support the plugin menu will either contain
1328 sub-menus with plugin categories (with liblrdf) or just a single menu
1329 with the <emphasis>Unclassified</emphasis> category.</para>
1331 <para>On startup terminatorX will print some information on the
1332 LADSPA-plugins analysis process to the standard output if you have
1333 enabled "Verbose Plugin Loading" in the Preferences dialog.
1335 terminal you run terminatorX from for that info if you have problems
1336 loading a plugin.</para>
1338 <para>As specified in the LADSPA-standard LADSPA-plugins can be located
1339 in multiple directories across the filesystem. To enable LADSPA-hosts to
1340 find those plugins you have to set the environment variable
1341 <envar>LADSPA_PATH</envar> accordingly. Let's say you store your
1342 plugins in <filename moreinfo="none">/usr/lib/ladspa</filename> and
1343 <filename moreinfo="none">/home/yourlogin/plugins</filename> then you
1344 would have to set:</para>
1346 <para><envar>LADSPA_PATH</envar>=<filename moreinfo="none">/usr/lib/ladspa:/home/yourlogin/plugins</filename></para>
1348 <para>As a fallback terminatorX will look in the standard directories
1349 <filename moreinfo="none">/usr/lib/ladspa</filename> and <filename
1350 moreinfo="none">/usr/local/lib/ladspa</filename> if the environment
1351 variable is not set. Note that this is just a convenience-function, in
1352 order for other LADSPA-hosts to work properly, be sure to set your
1353 <envar>LADSPA_PATH</envar> correctly. It is a good idea to do that from
1354 somewhere in your system configuration (either in your rc-scripts or
1355 <filename moreinfo="none">/etc/profile</filename> or wherever you
1358 <sect3 id="LIBLRDF">
1359 <title>liblrdf support</title>
1361 <para>Release 3.80 introduces support for Steve Harris' great
1362 <ulink url="http://plugin.org.uk/releases/lrdf/">liblrdf</ulink>
1363 library which introduces an RDF based scheme to categorize LADSPA
1364 plugins. This approach allows storing additional meta-data for LADSPA
1365 plugins in separate RDF files. In order to make use of these RDF files
1366 a terminatorX binary (compiled with liblrdf support of course)
1367 requires the main <filename>ladspa.rdfs</filename> file and additional
1368 RDF files containing meta information about the LADSPA plugins
1369 installed. Steve Harris' wonderful plugin library comes with such
1370 an additional description file for example.</para>
1372 <para>By default terminatorX will search the directories
1373 <filename>/usr/share/ladspa/rdf</filename> and <filename>/usr/local/share/ladspa/rdf</filename>
1374 for RDF files. In case the files were installed to other locations it
1375 is possible to configure the LADSPA RDF path in the
1376 <emphasis>Misc</emphasis> tab of the <emphasis>Preferences</emphasis>
1379 <para>If the RDF are read successfully on startup, the LADSPA menu
1380 that pops up when clicking a turntable's <emphasis>FX</emphasis>
1381 button will feature multiple sub-menus with LADSPA plugin categories
1382 (eg <emphasis>Amplitude/Amplifier</emphasis>) in which you will find
1383 the according plugins. Plugins not categorized by the RDF files reside
1384 in the <emphasis>Unclassified</emphasis> menu.</para>
1389 <title>MIDI Interface</title>
1391 <para>Aside of controlling terminatorX with a regular mouse and keyboard
1392 it is possible to control parameters through MIDI events (since 3.80).
1393 The MIDI interface is based upon the ALSA sequencer API. On startup
1394 terminatorX creates a MIDI input port called "terminatorX". You
1395 can now use for example the <ulink
1396 url="http://pkl.net/%7Enode/alsa-patch-bay.html">alsa-patch-pay</ulink>
1397 to connect an output port of your choice (either a hardware MIDI input
1398 device or a software generating midi events) to the terminatorX input
1399 port. If the "<emphasis>Restore MIDI Connections</emphasis>"
1400 option is activated terminatorX will try to re-connect to the MIDI ports
1401 it was connected to with the last run. However this approach is purely
1402 address-based and might fail miserably with software ports, in this case
1403 just disable the configuration options re-wire manually.</para>
1405 <para>There are two ways to map MIDI events to a parameter:<itemizedlist><listitem><para>Via
1406 the <emphasis>Configure MIDI Bindings</emphasis> dialog as described
1407 below</para></listitem><listitem><para>Via the the a parameter's
1408 menu (see <xref linkend="PARAMETERMENU" />)</para></listitem></itemizedlist></para>
1410 <para>Once the connection is set up terminatorX receives MIDI events
1411 through the input port. To configure what MIDI events will have which
1412 effect on a terminatorX turntable you can bind MIDI events to parameters
1413 of your choice by clicking the <emphasis>MIDI</emphasis> button of the
1414 turntable's audio panel. As a result the <emphasis>Configure MIDI
1415 Bindings</emphasis> dialog will pop up which features a field labelled
1416 <emphasis>Selected MIDI Event</emphasis> that will frequently update to
1417 display the contents of the last MIDI event received by terminatorX. So
1418 in order to map a MIDI controller to a specific turntable parameter
1419 select the parameter of your choice from the parameter list, cause your
1420 MIDI event sending device to emit the event you want to map the
1421 parameter on and click the <emphasis>Bind</emphasis> button.</para>
1423 <para>Immediately after binding the event you should see that the
1424 <emphasis>Event</emphasis> column entry of the selected parameter is
1425 updated to match the selected event. From now on all events matching the
1426 selected event will cause the turntable parameter to be updated. The GUI
1427 for that parameter will be refreshed accordingly. Note that it is
1428 possible to map the same event to multiple parameters.</para>
1430 <para>The MIDI mappings are stored within terminatorX set files so you
1431 wont have to reconfigure your bindings every time you start up
1432 terminatorX. If you are unhappy with a chosen binding you can select the
1433 parameter and click the <emphasis>Remove Binding</emphasis> button to
1434 get rid of the parameter's MIDI mapping.</para>
1436 <para>TeriminatorX now features a default MIDI mapping that can be
1437 enabled via the <emphasis>Turntables Menu</emphasis> (see <xref
1438 linkend="TURNTABLESMENU" />). The controllers are mapped in a one
1439 channel per turntable fashion:</para>
1442 <title>Default MIDI Controller Mapping</title>
1447 <entry>Turntable Parameter</entry>
1449 <entry>MIDI Controller</entry>
1451 <entry>MIDI CC Name</entry>
1457 <entry>Volume</entry>
1461 <entry><quote>Main Volume</quote></entry>
1469 <entry><quote>Pan</quote></entry>
1473 <entry>Lowpass Cutoff Frequency</entry>
1477 <entry><quote>Effect Control 1</quote></entry>
1481 <entry>Lowpass Resonance</entry>
1485 <entry><quote>Effect Control 2</quote></entry>
1489 <entry>Lowpass Gain</entry>
1493 <entry><quote>General Purpose Controller 1</quote></entry>
1497 <entry>Speed</entry>
1501 <entry><quote>General Purpose Controller 2</quote></entry>
1505 <entry>Pitch</entry>
1509 <entry><quote>General Purpose Controller 3</quote></entry>
1513 <entry>Sync Cycles</entry>
1517 <entry><quote>General Purpose Controller 4</quote></entry>
1521 <entry>Echo Length</entry>
1525 <entry><quote>Sound Controller 6</quote></entry>
1529 <entry>Echo Feedback</entry>
1533 <entry><quote>Sound Controller 7</quote></entry>
1537 <entry>Echo Volume</entry>
1541 <entry><quote>Sound Controller 8</quote></entry>
1545 <entry>Echo Pan</entry>
1549 <entry><quote>Sound Controller 9</quote></entry>
1555 <para>The toggle parameters of a turntable (where things can only be
1556 turned on or off) are mapped to MIDI NOTE events, where the first
1557 turntable is mapped to 'C', the next to 'C#', the next
1558 to 'D' and so on. The "function" of the toggle is
1559 defined via the selected MIDI channel:</para>
1562 <title>Default MIDI Note On/Off Mapping</title>
1567 <entry>Turntable Parameter</entry>
1569 <entry>MIDI Channel</entry>
1575 <entry>Trigger</entry>
1581 <entry>Sync Client</entry>
1593 <entry>Lowpass Enable</entry>
1599 <entry>Echo Enable</entry>
1611 <entry>Motor Spin On/Off</entry>
1619 <para>If you want to use your joystick to control terminatorX - I wrote
1620 a tiny tool to create MIDI events from joystick motion called
1621 <emphasis>aseqjoy</emphasis>. It's available from the <ulink
1622 url="http://terminatorX.cx/aseqjoy.html">terminatorX website</ulink>,
1626 <sect2 id="JACKSUPPORT">
1627 <title>JACK Support</title>
1629 <para>TerminatorX Version 3.81 brings support for the
1630 <emphasis>JACK Audio Connection Kit</emphasis>. Instead of writing audio
1631 data directly to some audio device terminatorX can send data to the JACK
1632 Daemon for further processing.</para>
1634 <para>To use the JACK backend you have to ensure that the JACK Daemon is
1635 up and running before you start terminatorX. The JACK backend is only
1636 available if terminatorX was capable of connecting to the JACK Daemon on
1637 startup. By default the two output ports of terminatorX will be
1638 connected to physical ports if available. You can then re-wire the ports
1639 whatever way you want. They will not be deactivated - when
1640 terminatorX' audio engine is turned off, the audio backend emits
1641 continuous silence.</para>
1645 <sect1 id="CONFIGURATION">
1646 <title>Configuration</title>
1648 <para>The main terminatorX configuration parameters can be set up via the
1649 <emphasis>Preferences</emphasis> dialog, which can be activated from the
1650 terminatorX menu. The new <emphasis>Preferences</emphasis> dialog features
1651 multiple tabs for several aspects of configuration.</para>
1653 <para>A word on the settings in general: your settings are stored in an
1654 XML file ( <filename moreinfo="none">~/.terminatorXrc).</filename> So if
1655 you think you completely messed up your settings you will have to exit
1656 terminatorX - delete this file - and then re-run terminatorX with the
1657 default settings. Note: is this file is now an XML file you can edit with
1658 an editor of your choice.</para>
1660 <sect2 id="AUDIOTAB">
1661 <title><emphasis>Audio</emphasis> Tab</title>
1663 <para>This tab allows to select which audio backend terminatorX should
1664 use. Currently there are three options: the OSS (Open Sound System)
1665 backend, the ALSA (Advanced Linux Sound Architecture) backend and the
1666 JACK (JACK Audio Connection Kit) backend. Some of these options might
1667 not be available, if your terminatorX binary wasn't compiled to
1668 support a certain backend.</para>
1670 <para>The OSS and ALSA backends have dedicated configuration tabs, JACK
1671 requires no further configuration - for more details on JACK support see
1672 <xref linkend="JACKSUPPORT" />.</para>
1676 <title><emphasis>Audio: OSS</emphasis> Tab</title>
1678 <para>Select the audio device you are going to use from the available
1679 options (or simply enter one yourself). terminatorX renders audio
1680 block-wise. In order to achieve close-to-realtime performance it is
1681 necessary to keep this blocks as small as possible. The main parameters
1682 that determine how close-to-realtime terminatorX will perform are
1683 <emphasis>No. of Buffers</emphasis> and <emphasis>Buffersize</emphasis>.
1684 The <emphasis>No. of Buffers</emphasis> parameter determines how many
1685 buffers the audio driver should use in most cases <emphasis>2</emphasis>
1686 should be the best setting and in rare cases <emphasis>3</emphasis>
1687 might give better results.</para>
1689 <para>The value for the <emphasis>Buffersize</emphasis> setting will be
1690 evaluated as 2^buffersize by OSS. So if you set the value to
1691 <emphasis>8</emphasis> the actual buffer size will be 2^8=256 Bytes. The
1692 smaller the buffers' size the better terminatorX will perform. The
1693 default setting of <emphasis>9</emphasis> should be acceptable in most
1694 conditions, but if you here "clicks", or "drops" in
1695 audio output that are not related to your sample-material you will have
1696 to increase the buffer size. On the other hand if you believe
1697 terminatorX does not react fast enough you have to decrease this
1700 <para>Additionally you can select the sampling rate you want terminatorX
1701 to operate on - note that recording to disk will use the same sample
1705 <sect2 id="ALSATAB">
1706 <title><emphasis>Audio: ALSA</emphasis> Tab</title>
1708 <para>Using ALSA for audio output allows specifing the buffer sizes in
1709 microseconds. ALSA uses a ring-buffer to process audio. The
1710 <emphasis>Buffer Time</emphasis> option lets you set the size for the
1711 complete ring buffer, while the <emphasis>Period Time</emphasis>
1712 determines how many audio samples will be transferred to the audio
1713 device per cycle. I'm not really sure on what kind of settings to
1714 recommend, however I had best results when setting the
1715 <emphasis>Period Time</emphasis> to 3rd or half of the
1716 <emphasis>Buffer Time</emphasis>.</para>
1718 <para>It's advisable to set the <emphasis>Buffer Time</emphasis> to
1719 at least the double of the <emphasis>Period Time</emphasis>, but for a
1720 more detailed description check out the ALSA documentation.</para>
1723 <sect2 id="INPUTTAB">
1724 <title><emphasis>Input</emphasis> Tab</title>
1726 <para>Between rendering and outputting these blocks terminatorX checks
1727 for mouse motion. The problem with mice is: they don't report when
1728 they have stopped. This is why terminatorX assumes your mouse has
1729 stopped if there is no motion reported for certain amount of
1730 render/output-cycles. This value is configurable via the
1731 <emphasis>Stop-sense-cycles</emphasis> option. If you decrease your
1732 buffersize of course you shorten the cycle time as well, therefore if
1733 you here strange stop/run behaviour of the audio output while scratching
1734 after you decreased the buffer size you might have to increase the
1735 stop-sense value too.</para>
1737 <para>XInput Device: <emphasis>WARNING:</emphasis> Use this option
1738 *only* if you want to use an input device other than your default-mouse
1739 for scratching. Selecting your default pointer will cause terminatorX to
1740 crash. See the "Using a turntable" section on the terminatorX
1741 homepage for details.</para>
1744 <sect2 id="USERINTERFACETAB">
1745 <title><emphasis>User Interface</emphasis> Tab</title>
1747 <para>With <emphasis>Update Idle</emphasis> / <emphasis>Update Delay</emphasis>
1748 you can configure GUI responsiveness: Higher <emphasis>Update Idle</emphasis>
1749 will cause the wave display (position display) and flash-widgets to
1750 update less often. Higher <emphasis>Update Delay</emphasis> values will
1751 cause the parameter widgets to update less often.</para>
1755 <title><emphasis>Audio Colors</emphasis> and <emphasis>VU Colors</emphasis>
1758 <para>Since Version 3.81 it is possible to configure the colors
1759 terminatorX' audio widgets. Simply click on the color you want to
1760 modify and select the tone you prefer.</para>
1763 <sect2 id="MISCTAB">
1764 <title><emphasis>Misc</emphasis> Tab</title>
1766 <para>You can now enter the soundfile editor of your choice in the
1767 "Sound file editor" field. This editor will be started when
1768 clicking the <emphasis>Edit</emphasis>-button in the main panel of the
1769 vtt-gui. If you enter for example "myeditor" terminatorX will
1770 run "myeditor sample_in_vtt.wav".</para>
1772 <para>The <emphasis>LADSPA RDF Path</emphasis> defines where liblrdf
1773 will look for the RDF files for LADPSA Plugins.</para>
1775 <para>If <emphasis>Compress set files</emphasis> is activated
1776 terminatorX will use zlib to compress set files. This is very usefull
1777 for sets that have many events recorded.</para>
1779 <para>See <xref linkend="MIDI" /> for more details on
1780 <emphasis>Restore MIDI Connections</emphasis>. If you disable the
1781 <emphasis>Ask for "Quit" Confirmation</emphasis> option
1782 terminatorX will no longer ask if you really want to quit.</para>
1786 <sect1 id="CONTACT">
1787 <title>Contact / Download</title>
1789 <para>Find out more about terminatorX at it's <ulink
1790 url="http://www.terminatorX.cx">homepage</ulink>.</para>
1792 <para>Send me comments, bug-reports, patches or scratches (see scratches
1793 section on the terminatorX homepage) at: <email>alex@lisas.de</email></para>
git://lisas.de / terminatorX.git / blob