Mostly ALSA fixing - Alex
[terminatorX.git] / terminatorX / doc / terminatorX-manual / C / terminatorX-manual.xml
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">
5
6 ]>
7 <article lang="en" id="index">
8   <articleinfo>
9     <title>terminatorX - Manual</title>
10
11     <author>
12       <firstname>Alexander</firstname>
13
14       <surname>König</surname>
15     </author>
16
17     <copyright>
18       <year>1999</year>
19
20       <year>2000</year>
21
22       <year>2001</year>
23
24       <year>2002</year>
25
26       <year>2003</year>
27
28       <holder role="mailto:alex@lisas.de">Alexander König</holder>
29     </copyright>
30
31     <releaseinfo>Version 3.80</releaseinfo>
32
33     <legalnotice id="legalnotice">
34       <para>Permission is granted to copy, distribute and/or modify this
35       document under the terms of the GNU Free Documentation License (GFDL),
36       Version 1.1 or any later version published by the Free Software
37       Foundation with no Invariant Sections, no Front-Cover Texts, and no
38       Back-Cover Texts. You can find a copy of the GFDL at this <ulink
39       url="ghelp:fdl" type="help">link</ulink> or in the file COPYING-DOCS
40       distributed with this manual.</para>
41
42       <para>Many of the names used by companies to distinguish their products
43       and services are claimed as trademarks. Where those names appear in any
44       ScrollKeeper documentation, and the members of the ScrollKeeper Project
45       are made aware of those trademarks, then the names are in capital
46       letters or initial capital letters.</para>
47
48       <para>DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED UNDER
49       THE TERMS OF THE GNU FREE DOCUMENTATION LICENSE WITH THE FURTHER
50       UNDERSTANDING THAT: <orderedlist><listitem><para>DOCUMENT IS PROVIDED ON
51       AN &#34;AS IS&#34; BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
52       OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE DOCUMENT
53       OR MODIFIED VERSION OF THE DOCUMENT IS FREE OF DEFECTS MERCHANTABLE, FIT
54       FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE
55       QUALITY, ACCURACY, AND PERFORMANCE OF THE DOCUMENT OR MODIFIED VERSION
56       OF THE DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR MODIFIED VERSION
57       PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL WRITER, AUTHOR OR
58       ANY CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, REPAIR OR
59       CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF
60       THIS LICENSE. NO USE OF ANY DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT
61       IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER; AND</para></listitem><listitem><para>UNDER
62       NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER IN TORT (INCLUDING
63       NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL THE AUTHOR, INITIAL WRITER,
64       ANY CONTRIBUTOR, OR ANY DISTRIBUTOR OF THE DOCUMENT OR MODIFIED VERSION
65       OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO
66       ANY PERSON FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR
67       CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION,
68       DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR
69       MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR LOSSES ARISING OUT OF OR
70       RELATING TO USE OF THE DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT,
71       EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH
72       DAMAGES.</para></listitem></orderedlist></para>
73     </legalnotice>
74   </articleinfo>
75
76   <sect1 id="INTRODUCTION">
77     <title>Introduction</title>
78
79     <sect2 id="WHATITIS">
80       <title>What it is</title>
81
82       <para><application moreinfo="none">terminatorX</application> is a real
83       time audio synthesizer that allows you to &#34;scratch&#34; on digitally
84       sampled audio data (*.wav, *.au, *.mp3, *.ogg etc.) the way Hiphop DJs
85       scratch on vinyl records. It features multiple turntables, real time
86       effects (built-in as well as LADSPA plugin effects), a sequencer and an
87       easy-to-use gtk+ GUI.</para>
88
89       <para>This is <emphasis>beta</emphasis> Software please help me fix
90       bugs. See <xref linkend="CONTACT" /> (Contact/Download). Please read
91       this manual and take a look at the <ulink
92       url="http://www.terminatorX.cx">homepage</ulink>.</para>
93     </sect2>
94
95     <sect2 id="QUICKSTART">
96       <title>Quickstart</title>
97
98       <para>Try the following steps:</para>
99
100       <orderedlist inheritnum="ignore" continuation="restarts">
101         <listitem>
102           <para>If you don&#39;t have <application moreinfo="none">LADSPA</application>
103           (Linux Audio Developer&#39;s Simple Plugin API) installed, go and
104           get it from the <ulink url="http://www.ladspa.org">LADSPA-homepage</ulink>
105           and install the SDK. terminatorX requires <filename moreinfo="none">ladspa.h</filename>.</para>
106         </listitem>
107
108         <listitem>
109           <para>Install terminatorX (see <filename moreinfo="none">INSTALL</filename>
110           file)</para>
111         </listitem>
112
113         <listitem>
114           <para>Run terminatorX</para>
115         </listitem>
116
117         <listitem>
118           <para>Load an audiofile into the available turntable (you can add
119           more turntables if you want) (Hint: Click on the button that holds
120           &#34;NONE&#34; to load an audiofile, or drop one over the audiofile
121           display from your filemanager if your filemanager is efm, gmc,
122           Nautilus or compatible (kfm does <emphasis>not</emphasis> work))</para>
123         </listitem>
124
125         <listitem>
126           <para>Load a LADSPA plugin of your choice by clicking the
127           turntable&#39;s <emphasis>FX</emphasis> button and enable it.</para>
128         </listitem>
129
130         <listitem>
131           <para>Click on the &#34;Audio Engine&#34;-button to start playback.</para>
132         </listitem>
133
134         <listitem>
135           <para>Click on the &#34;Mouse-Grab&#34;-button to enter grab mode.
136           The turntable with the red border has the input focus.</para>
137         </listitem>
138
139         <listitem>
140           <para>Press <keycap moreinfo="none">SPACE</keycap> or left mouse
141           button to scratch.</para>
142         </listitem>
143
144         <listitem>
145           <para>Release <keycap moreinfo="none">SPACE</keycap> or left mouse
146           button to let the scratch-file run at the turntable&#39;s default
147           speed.</para>
148         </listitem>
149
150         <listitem>
151           <para>Press <keycap moreinfo="none">ESCAPE</keycap> to quit grab
152           mode.</para>
153         </listitem>
154       </orderedlist>
155     </sect2>
156
157     <sect2 id="FEATURES">
158       <title>Features</title>
159
160       <para>The following list summarizes terminatorX&#39; main features:</para>
161
162       <itemizedlist>
163         <listitem>
164           <para>Scratching ;)</para>
165         </listitem>
166
167         <listitem>
168           <para>Multiple turntables</para>
169         </listitem>
170
171         <listitem>
172           <para>Built-in Sequencer</para>
173         </listitem>
174
175         <listitem>
176           <para>MIDI Interface (Input)</para>
177         </listitem>
178
179         <listitem>
180           <para>Pitch / Volume settings for each turntable</para>
181         </listitem>
182
183         <listitem>
184           <para>Effects (Lowpass/Echo) configurable for each turntable</para>
185         </listitem>
186
187         <listitem>
188           <para>Syncing tables to one master turntable</para>
189         </listitem>
190
191         <listitem>
192           <para>Broad audiofile-type support through the use of sox and mpg123</para>
193         </listitem>
194
195         <listitem>
196           <para>Recording to</para>
197         </listitem>
198
199         <listitem>
200           <para>Save turntable sets (.tX - files)</para>
201         </listitem>
202
203         <listitem>
204           <para>Support for the LADSPA-plugin-standard.</para>
205         </listitem>
206
207         <listitem>
208           <para>and more</para>
209         </listitem>
210       </itemizedlist>
211     </sect2>
212
213     <sect2 id="REQUIREMENTS">
214       <title>Requirements</title>
215
216       <para>To run terminatorX a system should meet the following
217       requirements:</para>
218
219       <itemizedlist>
220         <listitem>
221           <para>Software</para>
222
223           <itemizedlist>
224             <listitem>
225               <para>required</para>
226
227               <itemizedlist>
228                 <listitem>
229                   <para>The Linux Operating System (Version &#62;= 2.0) or
230                   FreeBSD</para>
231                 </listitem>
232
233                 <listitem>
234                   <para>glibc2 (pthreads).</para>
235                 </listitem>
236
237                 <listitem>
238                   <para>XFree86 (with DGA DirectMouse support). Note that
239                   XFree86 Release 4.0 has a bug resulting in broken
240                   DirectMouse support. This has been fixed by the XFree86-Team
241                   with Release 4.0.1 available from your distribution or the
242                   <ulink url="http://www.xfree86.org">XFree86 homepage</ulink>.</para>
243                 </listitem>
244
245                 <listitem>
246                   <para>The Gimp Toolkit: gtk+ (&#62;= 2.0). If your
247                   distribution doesn&#39;t provide a current version of gtk+
248                   get it from the <ulink url="http://www.gtk.org">gtk+
249                   homepage</ulink>.</para>
250                 </listitem>
251
252                 <listitem>
253                   <para>LADSPA - the Linux Audio Developer&#39;s Simple Plugin
254                   API. Get it from the <ulink url="http://www.ladpsa.org">LADSPA
255                   homepage</ulink></para>
256                 </listitem>
257
258                 <listitem>
259                   <para>a compiler (gcc)</para>
260                 </listitem>
261               </itemizedlist>
262             </listitem>
263
264             <listitem>
265               <para>optional (but highly recommended)</para>
266
267               <itemizedlist>
268                 <listitem>
269                   <para><ulink url="http://plugin.org.uk/releases/lrdf/">liblrdf</ulink>
270                   for easier handling of LADSPA plugins</para>
271                 </listitem>
272
273                 <listitem>
274                   <para><ulink url="http://www.mars.org/home/rob/proj/mpeg/">mad</ulink>
275                   for loading mp3 files.</para>
276                 </listitem>
277
278                 <listitem>
279                   <para><ulink url="http://www.xiph.org/ogg/vorbis/">libvorbis</ulink>
280                   for loading ogg files.</para>
281                 </listitem>
282
283                 <listitem>
284                   <para><ulink url="http://www.68k.org/~michael/audiofile/">libaudiofile</ulink>
285                   for loading misc other audio files.</para>
286                 </listitem>
287
288                 <listitem>
289                   <para><ulink
290                   url="http://www-ti.informatik.uni-tuebingen.de/~hippm/mpg123.html">mpg123</ulink>
291                   for mp3 pre-listening (and fallback loading if mad is not
292                   installed).</para>
293                 </listitem>
294
295                 <listitem>
296                   <para><ulink url="http://www.xiph.org/ogg/vorbis/">ogg123</ulink>
297                   for ogg pre-listening (and fallback loading if libvorbis is
298                   not installed).</para>
299                 </listitem>
300
301                 <listitem>
302                   <para><ulink
303                   url="http://home.sprynet.com/~cbagwell/sox.html">sox</ulink>
304                   for misc files pre-listening (and fallback loading of misc
305                   files).</para>
306                 </listitem>
307               </itemizedlist>
308             </listitem>
309           </itemizedlist>
310         </listitem>
311
312         <listitem>
313           <para>Hardware</para>
314
315           <itemizedlist>
316             <listitem>
317               <para>An <ulink url="http://www.alsa-project.org">ALSA</ulink>
318               or OSS compatible soundcard capable of stereo output.</para>
319             </listitem>
320
321             <listitem>
322               <para>A good clean mouse and pad, a good X-Pointer setup.</para>
323             </listitem>
324           </itemizedlist>
325         </listitem>
326       </itemizedlist>
327
328       <para>A note on performance: terminatorX is known to run satisfyingly on
329       pentium-class systems (or above of course). Increasing the number of
330       turntables or plugins will of course require more performant systems.</para>
331     </sect2>
332
333     <sect2 id="INSTALLATION">
334       <title>Installation</title>
335
336       <para>For GNU-standards&#39; sake this information is now located in the
337       <filename moreinfo="none">INSTALL</filename> file that came with this
338       distribution of terminatorX.</para>
339     </sect2>
340   </sect1>
341
342   <sect1 id="OPERATION">
343     <title>Operation</title>
344
345     <para>With Release Version 3.70 the terminatorX has undergone some
346     redesign again. It&#39;s split up in the main controls (master, sequencer,
347     engine controls and menu buttons) and the individual turntable&#39;s
348     controls. Each turntable has it&#39;s own GUI split up into control and
349     audio panel.</para>
350
351     <sect2>
352       <title>Menu</title>
353
354       <para>To clean-up the user interface a bit further some functions have
355       been moved into a more standard menu bar for the main window (with
356       release 3.80). The following sub-menus are available:</para>
357
358       <sect3>
359         <title><emphasis>File</emphasis> Menu</title>
360
361         <para>The <emphasis>File</emphasis> menu features these functions:</para>
362
363         <itemizedlist>
364           <listitem>
365             <para><emphasis>New</emphasis></para>
366
367             <para>Erases all existing turntables and sequencer events and
368             creates a new and untouched turntable.</para>
369           </listitem>
370
371           <listitem>
372             <para><emphasis>Open</emphasis></para>
373
374             <para>Allows restoring of a previously saved terminatorX set file.</para>
375           </listitem>
376
377           <listitem>
378             <para><emphasis>Save</emphasis></para>
379
380             <para>Saves the current turntables and events in a terminatorX set
381             file.</para>
382           </listitem>
383
384           <listitem>
385             <para><emphasis>Save As</emphasis></para>
386
387             <para>Like <emphasis>Save</emphasis> but prompts for a new file
388             name.</para>
389           </listitem>
390
391           <listitem>
392             <para><emphasis>Quit</emphasis></para>
393           </listitem>
394         </itemizedlist>
395       </sect3>
396
397       <sect3>
398         <title><emphasis>Turntables</emphasis> Menu</title>
399
400         <para>The <emphasis>Turntables</emphasis> menu features these
401         functions:</para>
402
403         <itemizedlist>
404           <listitem>
405             <para><emphasis>Add Turntable</emphasis></para>
406
407             <para>Adds a new turntable to the current set of turntables.</para>
408           </listitem>
409
410           <listitem>
411             <para><emphasis>Record Audio to Disk</emphasis></para>
412
413             <para>On activation of this option, terminatorX will prompt for a
414             file name for the RIFF/Wave file to create. Once activated
415             terminatorX will start recording audio to disk the next time the
416             audio engine is started - either by pressing the Power or the Play
417             button. Recording will stop when the audio engine is stopped
418             again. The created RIFF/Wave file will be a 16Bit/Stereo wave-file
419             with the sampling rate selected for the current audio backend.</para>
420           </listitem>
421         </itemizedlist>
422       </sect3>
423
424       <sect3>
425         <title><emphasis>Options</emphasis> Menu</title>
426
427         <para>The <emphasis>Options</emphasis> menu features these functions:</para>
428
429         <itemizedlist>
430           <listitem>
431             <para><emphasis>Fullscreen</emphasis></para>
432
433             <para>Maximizes the terminatorX main windows to use the complete
434             screen. Note that this requires a NETWM compliant window manager
435             to work (GNOME2&#39;s metacity works nicely, while openbox 2.x
436             does not for example). By choosing this option again
437             terminatorX&#39; window can be resized back to the previous state
438             again. The setting will be stored in the <filename>~/.terminatorXrc</filename>
439             file.</para>
440           </listitem>
441
442           <listitem>
443             <para><emphasis>Preferences</emphasis></para>
444
445             <para>Will pop up the Preferences dialog. For more details on
446             configuration itself see the <xref linkend="CONFIGURATION" />
447             section.</para>
448           </listitem>
449         </itemizedlist>
450       </sect3>
451
452       <sect3>
453         <title><emphasis>Help</emphasis> Menu</title>
454
455         <para>The <emphasis>Help</emphasis> menu features these functions:</para>
456
457         <itemizedlist>
458           <listitem>
459             <para><emphasis>Contents</emphasis></para>
460
461             <para>Starts a <emphasis>gnome-help</emphasis> (aka
462             <emphasis>yelp</emphasis>) process to display the very manual you
463             are reading right now.</para>
464           </listitem>
465
466           <listitem>
467             <para><emphasis>About</emphasis></para>
468
469             <para>Selecting this menu item will cause a small dialog to pop up
470             that contains some information on the compile time settings for
471             the terminatorX binary as well as the license.</para>
472           </listitem>
473
474           <listitem>
475             <para><emphasis>Visit terminatorX.cx</emphasis></para>
476
477             <para>Will try to spawn a browser process to load the URL
478             &#34;http://terminatorX.cx&#34; - for easy update checking or just
479             unecessary bloat.</para>
480           </listitem>
481         </itemizedlist>
482       </sect3>
483     </sect2>
484
485     <sect2 id="MAINCONTROLS">
486       <title>Main Controls</title>
487
488       <para>The controls of the master GUI are located in the top and the
489       right bar of the terminatorX main window.</para>
490
491       <itemizedlist>
492         <listitem>
493           <para><emphasis>Audio Engine Power / Mouse Grab</emphasis></para>
494
495           <para>With the Audio Engine Button you can en- and disable the audio
496           playback engine without activating the sequencer. Unlike earlier
497           versions you will not automatically enter mouse-grab mode so you can
498           modify volume/pitch/echo settings etc. while you actually hear what
499           you do.</para>
500
501           <para>Some functions are not available when the audio engine is on,
502           their controls will be marked insensitive when you enable the
503           engine. To actually enter grab mode you&#39;ll have to click on the
504           &#34;Mouse Grab&#34; button. See <xref linkend="GRABMODE" /> (Grab
505           Mode Operation) to find out how to control the software then.</para>
506         </listitem>
507
508         <listitem>
509           <para><emphasis>Sequencer Play / Record / Stop</emphasis></para>
510
511           <para>Please read the Sequencer-Section to find out more about the
512           sequencer.</para>
513         </listitem>
514
515         <listitem>
516           <para><emphasis>Master Volume / Pitch</emphasis></para>
517
518           <para>The volume and pitch settings of the individual turntables are
519           relative to these master settings. This information will be stored
520           within the .tX set files.</para>
521         </listitem>
522       </itemizedlist>
523     </sect2>
524
525     <sect2 id="TURNtableCONTROLS">
526       <title>Turntable Controls</title>
527
528       <para>The turntable GUI contains multiple controls and the real time
529       displays for each turntable. To save some space on your desktop and to
530       give terminatorX the traditional audio-application look, terminatorX
531       features &#34;knob&#34;-widgets. These widgets work pretty
532       straight-forward: click somewhere within the widget and keep the left
533       mouse-button pressed. Now move the mouse up and down or left and right
534       to increase/decrease the control&#39;s value. All those widget are
535       coupled with a text entry field since 3.70, which allows you to enter
536       values directly.</para>
537
538       <para>A turntable is visualized by two panels: the control and the audio
539       panel. These are no longer combined for better layout management.</para>
540
541       <para>Sometimes you might find a certain audio or control panel
542       unnecessary - simply eating up space. Since release 3.73 it is possible
543       to minimize audio and control panels to the <emphasis>panel bar</emphasis>
544       with the tiny button with a blue bar icon in the upper right edge of
545       each panel. This bar works just like GNOME&#39;s window list or
546       KDE&#39;s kicker: When a panel is minimized a button in the bar will
547       appear, representing the minimized window. On clicking this button the
548       button will be removed and the minimized panel is displayed again. When
549       no panels are minimized the panel bar automatically disappears to save
550       display space.</para>
551
552       <sect3>
553         <title>Turntable Audio Panel</title>
554
555         <para>The complete audio-file loaded into a turntable is displayed in
556         the green-on-black audio-widget. When playing terminatorX will
557         indicate the current position within the sample with a red cursor (a
558         blue/green cursor indicates the turntable is muted).</para>
559
560         <para>Additionally there are some controls above the audio-display:</para>
561
562         <itemizedlist>
563           <listitem>
564             <para><emphasis>Turntable Label</emphasis></para>
565
566             <para>This label indicates the turntables name. The name can be
567             set via the control panel</para>
568           </listitem>
569
570           <listitem>
571             <para><emphasis>File Button</emphasis></para>
572
573             <para>This button holds the name of the audio-file currently
574             loaded. When there&#39;s no sample loaded the button will read
575             &#34;NONE&#34; to indicate the current status. Click on this
576             button to get a menu from which you can load/reload a sound file
577             or run an external soundfile editor. Alternatively you can
578             drag&#39;n&#39;drop files over the audio-display to load them.</para>
579
580             <itemizedlist>
581               <title>The File Button Menu</title>
582
583               <listitem>
584                 <para><emphasis>Load File</emphasis></para>
585
586                 <para>Choose this menu entry to select a soundfile from the
587                 file-selection dialog that will pop-up.</para>
588               </listitem>
589
590               <listitem>
591                 <para><emphasis>Reload File</emphasis></para>
592
593                 <para>Choose this menu entry to re-read the audio-file.</para>
594               </listitem>
595
596               <listitem>
597                 <para><emphasis>Edit File</emphasis></para>
598
599                 <para>This menu entry will run the external audiofile-editor
600                 (that can be specified via the options-dialog) with the
601                 current audio-file as a parameter. Choose reload after editing
602                 and saving the file.</para>
603               </listitem>
604             </itemizedlist>
605           </listitem>
606
607           <listitem>
608             <para><emphasis>Mouse Mapping</emphasis></para>
609
610             <para>terminatorX allows mapping misc parameters to the mouse axis
611             of your choice. These mappings will be activated in grab mode, so
612             if you move your mouse in X or Y direction in grab mode the
613             parameters you selected from this menu will be affected (for this
614             turntable). Since Version 3.70 this mappings are no longer
615             hardcoded to built-in controls but available for all parameters
616             that qualify as &#34;mappable&#34;. Note that this includes
617             plugins&#39; controls as well.</para>
618           </listitem>
619
620           <listitem>
621             <para><emphasis>MIDI Mapping</emphasis></para>
622
623             <para>This button is available only if terminatorX was built with
624             ALSA MIDI support and the sequencer input port was created
625             successfully on startup. For more information on terminatorX&#39;
626             MIDI interface see <xref linkend="MIDI" /> section.</para>
627           </listitem>
628         </itemizedlist>
629       </sect3>
630
631       <sect3>
632         <title>Turntable Controls</title>
633
634         <para>These controls are now grouped within functional panels. The
635         number of panels depends on the number of plugins loaded. terminatorX
636         allows hiding the controls not required via the yellow triangle
637         button. To un-hide just click the button again. The first panels are
638         the standard controls for a turntable, then follows the dynamic
639         FX-section and below that follow the pitch and volume controls.</para>
640
641         <sect4>
642           <title>Main Panel</title>
643
644           <itemizedlist>
645             <listitem>
646               <para><emphasis>Name Field</emphasis></para>
647
648               <para>The main panel features a text entry field that allows
649               setting a name for the related turntable. The Labels for the
650               controls and the audio-display will update accordingly.</para>
651             </listitem>
652
653             <listitem>
654               <para><emphasis>Delete Button</emphasis></para>
655
656               <para>Pressing this button remove the turntable from the current
657               setup. Note that all sequencer events recorded for this
658               turntable will be erased, too.</para>
659             </listitem>
660           </itemizedlist>
661         </sect4>
662
663         <sect4>
664           <title>Trigger Panel</title>
665
666           <para>The trigger panel holds all controls related to triggering the
667           turntable. For more details on synchronization see <xref
668           linkend="SYNCHRONIZATION" /> (synchronization).</para>
669
670           <itemizedlist>
671             <listitem>
672               <para><emphasis>Trigger! Button</emphasis></para>
673
674               <para>Pressing this button triggers the turntable now. With the
675               audio engine enabled this will cause the turntable to start
676               playing back audio from the beginning of the sample.</para>
677             </listitem>
678
679             <listitem>
680               <para><emphasis>Stop Button</emphasis></para>
681
682               <para>Guess what, this stops this turntable&#39;s
683               audio-playback.</para>
684             </listitem>
685
686             <listitem>
687               <para><emphasis>Master Button</emphasis></para>
688
689               <para>Enabling this button makes this turntable the
690               <emphasis>sync-master</emphasis>. Note that only
691               <emphasis>one</emphasis> turntable at a time can be the
692               sync-master.</para>
693             </listitem>
694
695             <listitem>
696               <para><emphasis>Client Button</emphasis></para>
697
698               <para>This button marks the turntable as <emphasis>sync-client</emphasis>,
699               so it will be triggered with the master automatically.</para>
700             </listitem>
701
702             <listitem>
703               <para><emphasis>Sync-Cycles Selection</emphasis></para>
704
705               <para>The sync cycles determine how often a sync-client should
706               be triggered. With a setting of zero the sync-client will be
707               (re-)triggered with <emphasis>every</emphasis> trigger of the
708               sync-master. A setting of 1 will (re-)trigger the client every
709               <emphasis>second</emphasis> master-trigger and so on.</para>
710             </listitem>
711           </itemizedlist>
712
713           <para>Below the effect queue a turntable shows some more controls:
714           <itemizedlist><listitem><para><emphasis>Pitch Control</emphasis></para><para>The
715           pitch control allows setting the default playback speed for that
716           turntable (the &#34;motor&#34; speed). Negative values will result
717           in the sample being played backwards.</para></listitem><listitem><para><emphasis>PAN
718           Control</emphasis></para><para>This parameter allows setting the
719           position of the turntable&#39;s main signal within the stereo
720           panorama.</para></listitem><listitem><para><emphasis>VU Meter</emphasis></para><para>The
721           displayed signal shows the turntable&#39;s current signal not
722           including the echo-signal which is mixed separately.</para></listitem></itemizedlist></para>
723         </sect4>
724       </sect3>
725
726       <sect3>
727         <title>The Effect Queue</title>
728
729         <para>With release 3.70 the effects are no longer hardcoded into the
730         turntable. The effects are now arranged within an per-turntable
731         effect-queue. The effect sequence is configurable by the user. To move
732         an effect to higher position within the queue, press the
733         <emphasis>blue upward arrow button</emphasis>. This will cause the
734         effect to be rendered <emphasis>before</emphasis> the following
735         effects. The <emphasis>blue downward arrow button</emphasis> will move
736         the effect down by one position. It will then be rendered
737         <emphasis>after</emphasis> the preceding effects.</para>
738
739         <para>There are two types of effects: the traditional built-in effects
740         (Lowpass and Echo) and LADSPA plugins. The built-in effects are always
741         available and cannot be removed (but disabled). There can be only one
742         instance of a built-in effect. The LADSPA plugins on the other hand
743         may be instantiated multiple times and can be removed from the effect
744         queue. Press the <emphasis>blue cross button</emphasis> to achieve
745         this.</para>
746
747         <figure float="0">
748           <title>An example for a terminatorX effect queue</title>
749
750           <graphic fileref="figures/signalflow.png" format="PNG" />
751         </figure>
752
753         <para>Now since release 3.71 the built-in echo effect is treated
754         differently from other effects. Where all other effects feed their
755         signal back into the effect queue the echo effect doesn&#39;t touch
756         the input signal. It&#39;s echo-signal is mixed separately from the
757         turntable&#39;s main signal to allow a different panning value for the
758         echo-signal. This mode of operation does have some side-effects:
759         imagine a lowpass filter with a position after the echo effect in the
760         effect queue. This will result in the turntable&#39;s main signal
761         being lowpass-filtered but it will leave the echo-signal
762         lowpass-unfiltered.</para>
763
764         <para>Some may call this behaviour a bug - whereas I would consider it
765         a feature ;). Anyway if the above description didn&#39;t clear things
766         up maybe the displayed figure does. It shows a schematic effect queue
767         with the built-in effects and two LADSPA effects enabled. Now with
768         this setup you will not hear anything from the second LADSPA effect in
769         the echo-signal.</para>
770
771         <para>For more information on a LADSPA plugin, press it&#39;s
772         panel&#39;s label and a small info box will pop up.</para>
773
774         <itemizedlist>
775           <listitem>
776             <para><emphasis>FX Button</emphasis></para>
777
778             <para>Press this button to load a LADSPA plugin into the effect
779             queue of the turntable. A menu holding the available
780             (terminatorX-&#34;compatible&#34;) LADSPA-plugins will pop up. The
781             plugins are grouped within submenus according to the modules the
782             plugins are contained in. Simply select the plugin you want to
783             load from this menu and a panel for it will pop up at the end of
784             the effect queue.</para>
785
786             <para>Note that due to the wide parameter ranges some LADSPA
787             plugins have they sometimes might be hard to control with the knob
788             widget. In these cases you might want to use the text field to
789             enter values. For more details on Plugins see <xref
790             linkend="LADSPAPLUGINS" /> (LADSPA).</para>
791           </listitem>
792         </itemizedlist>
793       </sect3>
794
795       <sect3>
796         <title>Lowpass Panel</title>
797
798         <para>terminatorX features a built-in resonating lowpass filter that
799         can be configured with this panel.</para>
800
801         <itemizedlist>
802           <listitem>
803             <para><emphasis>Enable Button</emphasis></para>
804
805             <para>Activating this button will enable the lowpass filter for
806             this turntable.</para>
807           </listitem>
808
809           <listitem>
810             <para><emphasis>Input Gain Control</emphasis></para>
811
812             <para>With this parameter you can amplify the signal that goes
813             into the lowpass filter if required.</para>
814           </listitem>
815
816           <listitem>
817             <para><emphasis>Frequency Control</emphasis></para>
818
819             <para>Use this parameter to set the cutoff frequency for the
820             lowpass filter. Minimum: 0=0Hz, Maximum: 1=22KHz.</para>
821           </listitem>
822
823           <listitem>
824             <para><emphasis>Resonance</emphasis></para>
825
826             <para>Use this parameter to set the resonance-value. Minimum: 0=no
827             resonance, Maximum: 1=max resonance.</para>
828           </listitem>
829         </itemizedlist>
830       </sect3>
831
832       <sect3>
833         <title>Echo Panel</title>
834
835         <para>Additionally terminatorX features a built-in echo effect. It can
836         be configured with this panel.</para>
837
838         <itemizedlist>
839           <listitem>
840             <para><emphasis>Enable Button</emphasis></para>
841
842             <para>Activating this button will enable the echo effect for this
843             turntable.</para>
844           </listitem>
845
846           <listitem>
847             <para><emphasis>Duration Control</emphasis></para>
848
849             <para>Use this parameter to set the length of the echo. The
850             duration parameter scales to the actual sample length: so if you
851             set it to 0.5 you will hear the echo when the red playback cursor
852             is half way through the sample. This is true for samples that are
853             shorter than terminatorX&#39; maximum echo buffer size only.</para>
854           </listitem>
855
856           <listitem>
857             <para><emphasis>Feedback Control</emphasis></para>
858
859             <para>Set the echo&#39;s feedback amount with this parameter.</para>
860           </listitem>
861
862           <listitem>
863             <para><emphasis>Volume Control</emphasis></para>
864
865             <para>This parameter can additionally amplify the echo signal.
866             Unlike the feedback parameter above this parameter has no
867             influence on the signal fed back into the echo-buffer, it effects
868             merely the playback volume of the echo signal.</para>
869           </listitem>
870
871           <listitem>
872             <para><emphasis>Pan Control</emphasis></para>
873
874             <para>The echo effect differs from other effects as it&#39;s
875             output signal will be mixed separately. The main goal here is to
876             allow positioning the echo signal at a position in the stereo
877             panorama that differs from the main panning position of the
878             turntable to achieve a somewhat spacial effect. The easy example
879             is: turntable&#39;s panning left, echo&#39;s panning right. As
880             both pan parameters are sequenceable you can create nice motion
881             effects from this starting point.</para>
882           </listitem>
883         </itemizedlist>
884       </sect3>
885     </sect2>
886
887     <sect2 id="SYNCHRONIZATION">
888       <title>Synchronization</title>
889
890       <para>Let&#39;s start off with an example: Say you have two drum loops
891       and one bassline loaded in three turntables. Of course you want these
892       samples to be triggered at the same time but you don&#39;t want to
893       invest time to cut them to the exact length. Therefore you decide which
894       of the drum loops to make the sync master. You&#39;ll have to do this
895       before you enable the audio engine (for now). Only one turntable can be
896       the sync master. Now you can make the other two sync clients which will
897       cause them to be (re-)triggered whenever the master is (re-)triggered.
898       The number you can select to the right of the <emphasis>client button</emphasis>
899       sets the trigger delay for the button: if it&#39;s set to zero the
900       turntable will be triggered with every master trigger, if it&#39;s set
901       to 1 it&#39;ll be triggered every 2nd master trigger and so on.</para>
902
903       <para>A nice side effect of this feature is: you can now scratch the
904       second (sync client) drum loop and no matter whether you&#39;re
905       scratching is good or not the beat will be triggered correctly again ;)</para>
906     </sect2>
907
908     <sect2 id="GRABMODE">
909       <title>Grab Mode Operation</title>
910
911       <para>After pressing the <emphasis>Mouse Grab button</emphasis>
912       terminatorX enters &#34;grab mode&#34;. This mode actually locks the
913       mouse (as this input is now used to control the real time parameters)
914       and therefore you&#39;ll have to know some mouse/keyboard shortcuts to
915       control the software without the GUI.</para>
916
917       <para>Press <keycap moreinfo="none">ESCAPE</keycap> to quit grab mode.</para>
918
919       <para>Select the turntable with input focus: The first turntable to hold
920       the input focus will be the first turntable. You can now use <keycap
921       moreinfo="none">TAB</keycap> or right mouse button to switch to the next
922       turntable. Alternatively you can use <keycap moreinfo="none">F1</keycap>
923       to <keycap moreinfo="none">F12</keycap> to select turntable 1 to 12.</para>
924
925       <para>Now the turntable that has the focus is the one you will
926       manipulate with your mouse and keyboard inputs: Note that you can
927       actually map different functions to the mouse x/y axis - so what
928       actually happens when you move your mouse depends on what you select on
929       the x/y control panels for each turntable.</para>
930
931       <table>
932         <title>Keyboard Controls in Grab Mode</title>
933
934         <tgroup cols="2">
935           <thead>
936             <row>
937               <entry>Key</entry>
938
939               <entry>Function</entry>
940             </row>
941           </thead>
942
943           <tbody>
944             <row>
945               <entry><keycap moreinfo="none">TAB</keycap></entry>
946
947               <entry>select next turntable</entry>
948             </row>
949
950             <row>
951               <entry><keycap moreinfo="none">F1</keycap> to <keycap
952               moreinfo="none">F12</keycap></entry>
953
954               <entry>select turntable 1 to 12</entry>
955             </row>
956
957             <row>
958               <entry><keycap moreinfo="none">RETURN</keycap></entry>
959
960               <entry>triggers the turntable</entry>
961             </row>
962
963             <row>
964               <entry><keycap moreinfo="none">BACKSPACE</keycap></entry>
965
966               <entry>stops the turntable</entry>
967             </row>
968
969             <row>
970               <entry><keycap moreinfo="none">S</keycap></entry>
971
972               <entry>toggles &#34;Sync Client&#34;</entry>
973             </row>
974
975             <row>
976               <entry><keycap moreinfo="none">SPACE</keycap></entry>
977
978               <entry>while pressed turntable speed is mapped to mouse speed
979               (scratching!)</entry>
980             </row>
981
982             <row>
983               <entry><keycap moreinfo="none">ALT</keycap></entry>
984
985               <entry>mute on/off</entry>
986             </row>
987
988             <row>
989               <entry><keycap moreinfo="none">CTRL</keycap></entry>
990
991               <entry>mute on/off (inverted)</entry>
992             </row>
993
994             <row>
995               <entry><keycap moreinfo="none">F</keycap></entry>
996
997               <entry>(&#34;fast&#34;) warp mode (while scratching)</entry>
998             </row>
999
1000             <row>
1001               <entry><keycap moreinfo="none">W</keycap></entry>
1002
1003               <entry>same as above but the audio will be muted while warping</entry>
1004             </row>
1005           </tbody>
1006         </tgroup>
1007       </table>
1008
1009       <table>
1010         <title>Mouse Button Controls in Grab Mode</title>
1011
1012         <tgroup cols="2">
1013           <thead>
1014             <row>
1015               <entry>Mouse Button</entry>
1016
1017               <entry>Function</entry>
1018             </row>
1019           </thead>
1020
1021           <tbody>
1022             <row>
1023               <entry><emphasis>Left button</emphasis></entry>
1024
1025               <entry>same as <keycap moreinfo="none">SPACE</keycap>:
1026               scratching (triggers the turntable when stopped)</entry>
1027             </row>
1028
1029             <row>
1030               <entry><emphasis>Right button</emphasis></entry>
1031
1032               <entry>select next turntable</entry>
1033             </row>
1034
1035             <row>
1036               <entry><emphasis>Middle button</emphasis></entry>
1037
1038               <entry>mute on/off</entry>
1039             </row>
1040           </tbody>
1041         </tgroup>
1042       </table>
1043
1044       <para>Scratching works as before: press <keycap moreinfo="none">SPACE</keycap>
1045       or left mouse button to actually scratch: now your mouse controls the
1046       turntables speed. Release it to let that turntable spin at default speed
1047       again.</para>
1048     </sect2>
1049
1050     <sect2 id="DRAGNDROP">
1051       <title>Drag And Drop</title>
1052
1053       <para>Since V3.55 terminatorX provides multiple DND-Drop-Targets for use
1054       with GNOME / gmc (gmc is the GNU Midnight Commander), Nautilus or the
1055       Enlightenment File Manager (efm). You can load an audiofile into an
1056       existing turntable by dragging it from a gmc (or efm or whatever)-window
1057       and drop it over a. the <emphasis>file button</emphasis> (audio-display)
1058       or b. (the easier target ;) over the audio-display (the green on black
1059       widget that displays the audiodata).</para>
1060
1061       <para>To add a file to the set (== to load the file into a *new*
1062       turntable) simply drop the audiofile over the &#34;New Turntable&#34;
1063       Button. To load a complete terminatorX-set simply drop the set file
1064       (*.tX) over the &#34;Load Set&#34; button.</para>
1065     </sect2>
1066
1067     <sect2 id="SEQUENCER">
1068       <title>The Sequencer</title>
1069
1070       <para>Release 3.60 introduced the sequencer. It can record and play back
1071       events for the following parameters:</para>
1072
1073       <itemizedlist>
1074         <listitem>
1075           <para>master volume &#38; pitch</para>
1076         </listitem>
1077
1078         <listitem>
1079           <para>scratching</para>
1080         </listitem>
1081
1082         <listitem>
1083           <para>(turntable) volume &#38; pitch</para>
1084         </listitem>
1085
1086         <listitem>
1087           <para>triggers</para>
1088         </listitem>
1089
1090         <listitem>
1091           <para>loop (on/off)</para>
1092         </listitem>
1093
1094         <listitem>
1095           <para>sync client settings</para>
1096         </listitem>
1097
1098         <listitem>
1099           <para>muting</para>
1100         </listitem>
1101
1102         <listitem>
1103           <para><emphasis>all</emphasis> parameters for the effects. This
1104           includes built-in effects (lowpass and echo) as well as LADSPA
1105           plugins.</para>
1106         </listitem>
1107       </itemizedlist>
1108
1109       <para>To record events simply press the <emphasis>Record</emphasis>
1110       button of the sequencer, then press the <emphasis>Play</emphasis>
1111       button. All actions (for sequenceable parameters - see above) you now
1112       take will be recorded into the song list. Press <emphasis>Stop</emphasis>
1113       and <emphasis>Play</emphasis> again to see/hear how terminatorX plays
1114       back the events recorded before. You can now record events again for
1115       e.g. another turntable or record other parameters for the same turntable
1116       - whatever you want to do. Recording events for parameters for which
1117       events have been recorded before will result in dubbing: if you touch a
1118       parameter while recording, events previously recorded will be erased
1119       from the moment you touch the parameter until you stop recording.</para>
1120
1121       <para>When recording long sequences/songs you can use the
1122       sequencer-scale to start recording/playback from any song-position you
1123       want. To record a single parameter value at a certain position simply
1124       move the sequencer-scale to that position, press <emphasis>Record,</emphasis>
1125       set the parameter and press <emphasis>Stop</emphasis> again.</para>
1126
1127       <para>There is no other the way to edit the sequencer events currently,
1128       but future releases may feature an event-list editor.</para>
1129     </sect2>
1130
1131     <sect2 id="LADSPAPLUGINS">
1132       <title>Plugins (LADSPA)</title>
1133
1134       <para>Since release 3.70 terminatorX supports LADSPA-plugins. LADSPA is
1135       the &#34;Linux Audio Developer&#39;s Simple Plugin API&#34; which was
1136       designed by developers on the Linux-Audio-Developer-Mailinglist and is
1137       maintained by Richard W.E. Furse. For more information on LADSPA, other
1138       LADSPA-hosts and LADSPA-plugins checkout the <ulink
1139       url="http://www.ladspa.org">LADSPA homepage</ulink>.</para>
1140
1141       <para>Not every plugin is supported by terminatorX though. As the
1142       plugins are inserted into the per-turntable effect-queue, they have to
1143       be mono plugins (as is that queue) for now. This is why terminatorX will
1144       load plugins with <emphasis>one</emphasis> audio-in port and
1145       <emphasis>one</emphasis> audio-out port only.</para>
1146
1147       <para>The decision on whether a plugin is terminatorX-suitable is made
1148       on terminatorX startup, so only plugins that fit into the effect queue
1149       will be offered in the plugin-menu that pops up when the
1150       <emphasis>FX</emphasis> button is clicked. Depending on whether the
1151       terminatorX binary you&#39;re using was built with or without liblrdf (<xref
1152       linkend="LIBLRDF" />) support the plugin menu will either contain
1153       sub-menus with plugin categories (with liblrdf) or just a single menu
1154       with the <emphasis>Unclassified</emphasis> category.</para>
1155
1156       <para>On startup terminatorX will print some information on the
1157       LADSPA-plugins analysis process to the standard output. Watch the
1158       terminal you run terminatorX from for that info if you have problems
1159       loading a plugin.</para>
1160
1161       <para>As specified in the LADSPA-standard LADSPA-plugins can be located
1162       in multiple directories across the filesystem. To enable LADSPA-hosts to
1163       find those plugins you have to set the environment variable
1164       <envar>LADSPA_PATH</envar> accordingly. Let&#39;s say you store your
1165       plugins in <filename moreinfo="none">/usr/lib/ladspa</filename> and
1166       <filename moreinfo="none">/home/yourlogin/plugins</filename> then you
1167       would have to set:</para>
1168
1169       <para><envar>LADSPA_PATH</envar>=<filename moreinfo="none">/usr/lib/ladspa:/home/yourlogin/plugins</filename></para>
1170
1171       <para>As a fallback terminatorX will look in the standard directories
1172       <filename moreinfo="none">/usr/lib/ladspa</filename> and <filename
1173       moreinfo="none">/usr/local/lib/ladspa</filename> if the environment
1174       variable is not set. Note that this is just a convenience-function, in
1175       order for other LADSPA-hosts to work properly, be sure to set your
1176       <envar>LADSPA_PATH</envar> correctly. It is a good idea to do that from
1177       somewhere in your system configuration (either in your rc-scripts or
1178       <filename moreinfo="none">/etc/profile</filename> or wherever you
1179       prefer).</para>
1180
1181       <sect3 id="LIBLRDF">
1182         <title>liblrdf support</title>
1183
1184         <para>Release 3.80 introduces support for Steve Harris&#39; great
1185         <ulink url="http://plugin.org.uk/releases/lrdf/">liblrdf</ulink>
1186         library which introduces an RDF based scheme to categorize LADSPA
1187         plugins. This approach allows storing additional meta-data for LADSPA
1188         plugins in separate RDF files. In order to make use of these RDF files
1189         a terminatorX binary (compiled with liblrdf support of course)
1190         requires the main <filename>ladspa.rdfs</filename> file and additional
1191         RDF files containing meta information about the LADSPA plugins
1192         installed. Steve Harris&#39; wonderful plugin library comes with such
1193         an additional description file for example.</para>
1194
1195         <para>By default terminatorX will search the directories
1196         <filename>/usr/share/ladspa/rdf</filename> and <filename>/usr/local/share/ladspa/rdf</filename>
1197         for RDF files. In case the files were installed to other locations it
1198         is possible to configure the LADSPA RDF path in the
1199         <emphasis>Misc</emphasis> tab of the <emphasis>Preferences</emphasis>
1200         dialog.</para>
1201
1202         <para>If the RDF are read successfully on startup, the LADSPA menu
1203         that pops up when clicking a turntable&#39;s <emphasis>FX</emphasis>
1204         button will feature multiple sub-menus with LADSPA plugin categories
1205         (eg <emphasis>Amplitude/Amplifier</emphasis>) in which you will find
1206         the according plugins. Plugins not categorized by the RDF files reside
1207         in the <emphasis>Unclassified</emphasis> menu.</para>
1208       </sect3>
1209     </sect2>
1210
1211     <sect2 id="MIDI">
1212       <title>MIDI Interface</title>
1213
1214       <para>Aside of controlling terminatorX with a regular mouse and keyboard
1215       it is possible to control parameters through MIDI events (since 3.80).
1216       The MIDI interface is based upon the ALSA sequencer API. On startup
1217       terminatorX creates a MIDI input port called &#34;terminatorX&#34;. You
1218       can now use for example the <ulink url="alsa-patch-bay link here">alsa-patch-pay</ulink>
1219       to connect an output port of your choice (either a hardware MIDI input
1220       device or a software generating midi events) to the terminatorX input
1221       port.</para>
1222
1223       <para>Once the connection is set up terminatorX receives MIDI events
1224       through the input port. To configure what MIDI events will have which
1225       effect on a terminatorX turntable you can bind MIDI events to parameters
1226       of your choice by clicking the <emphasis>MIDI Mapping</emphasis> button
1227       of the turntable&#39;s audio panel. As a result the
1228       <emphasis>Configure MIDI Bindings</emphasis> dialog will pop up which
1229       features a field labelled <emphasis>Selected MIDI Event</emphasis> that
1230       will frequently update to display the contents of the last MIDI event
1231       received by terminatorX. So in order to map a MIDI controller to a
1232       specific turntable parameter select the parameter of your choice from
1233       the parameter list, cause your MIDI event sending device to emit the
1234       event you want to map the parameter on and click the
1235       <emphasis>Bind</emphasis> button.</para>
1236
1237       <para>Immediately after binding the event you should see that the
1238       <emphasis>Event</emphasis> column entry of the selected parameter is
1239       updated to match the selected event. From now on all events matching the
1240       selected event will cause the turntable parameter to be updated. The GUI
1241       for that parameter will be refreshed accordingly. Note that it is
1242       possible to map the same event to multiple parameters.</para>
1243
1244       <para>The MIDI mappings are stored within terminatorX set files so you
1245       wont have to reconfigure your bindings every time you start up
1246       terminatorX. If you are unhappy with a chosen binding you can select the
1247       parameter and click the <emphasis>Remove Binding</emphasis> button to
1248       get rid of the parameter&#39;s MIDI mapping.</para>
1249
1250       <para>If you want to use your joystick to control terminatorX - I wrote
1251       a tiny tool to create MIDI events from joystick motion called
1252       <emphasis>aseqjoy</emphasis>. It&#39;s available from the <ulink
1253       url="http://terminatorX.cx/aseqjoy">terminatorX website</ulink>, too.</para>
1254     </sect2>
1255   </sect1>
1256
1257   <sect1 id="CONFIGURATION">
1258     <title>Configuration</title>
1259
1260     <para>The main terminatorX configuration parameters can be set up via the
1261     <emphasis>Preferences</emphasis> dialog, which can be activated from the
1262     terminatorX menu. The new <emphasis>Preferences</emphasis> dialog features
1263     multiple tabs for several aspects of configuration.</para>
1264
1265     <para>A word on the settings in general: your settings are stored in an
1266     XML file ( <filename moreinfo="none">~/.terminatorXrc).</filename> So if
1267     you think you completely messed up your settings you will have to exit
1268     terminatorX - delete this file - and then re-run terminatorX with the
1269     default settings. Note: is this file is now an XML file you can edit with
1270     an editor of your choice.</para>
1271
1272     <sect2>
1273       <title><emphasis>Audio</emphasis> Tab</title>
1274
1275       <para>This tab allows to select which audio backend to use. Currently
1276       there are two of these: one for the OSS (Open Sound System) backend and
1277       one for ALSA (Advanced Linux Sound Architecture) backend. Hopefully
1278       future releases will feature a JACK backend too.</para>
1279     </sect2>
1280
1281     <sect2>
1282       <title><emphasis>Audio: OSS</emphasis> Tab</title>
1283
1284       <para>Select the audio device you are going to use from the available
1285       options (or simply enter one yourself). terminatorX renders audio
1286       block-wise. In order to achieve close-to-realtime performance it is
1287       necessary to keep this blocks as small as possible. The main parameters
1288       that determine how close-to-realtime terminatorX will perform are
1289       <emphasis>No. of Buffers</emphasis> and <emphasis>Buffersize</emphasis>.
1290       The <emphasis>No. of Buffers</emphasis> parameter determines how many
1291       buffers the audio driver should use in most cases <emphasis>2</emphasis>
1292       should be the best setting and in rare cases <emphasis>3</emphasis>
1293       might give better results.</para>
1294
1295       <para>The value for the <emphasis>Buffersize</emphasis> setting will be
1296       evaluated as 2^buffersize by OSS. So if you set the value to
1297       <emphasis>8</emphasis> the actual buffer size will be 2^8=256 Bytes. The
1298       smaller the buffers&#39; size the better terminatorX will perform. The
1299       default setting of <emphasis>9</emphasis> should be acceptable in most
1300       conditions, but if you here &#34;clicks&#34;, or &#34;drops&#34; in
1301       audio output that are not related to your sample-material you will have
1302       to increase the buffer size. On the other hand if you believe
1303       terminatorX does not react fast enough you have to decrease this
1304       parameter.</para>
1305
1306       <para>Additionally you can select the sampling rate you want terminatorX
1307       to operate on - note that recording to disk will use the same sample
1308       rate.</para>
1309     </sect2>
1310
1311     <sect2>
1312       <title><emphasis>Audio: ALSA</emphasis> Tab</title>
1313
1314       <para>Using ALSA for audio output allows specifing the buffer sizes in
1315       microseconds. ALSA uses a ring-buffer to process audio. The
1316       <emphasis>Buffer Time</emphasis> option lets you set the size for the
1317       complete ring buffer, while the <emphasis>Period Time</emphasis>
1318       determines how many audio samples will be transferred to the audio
1319       device per cycle.</para>
1320
1321       <para>It&#39;s advisable to set the <emphasis>Buffer Time</emphasis> to
1322       at least the double of the <emphasis>Period Time</emphasis>, but for a
1323       more detailed description check out the ALSA documentation.</para>
1324     </sect2>
1325
1326     <sect2>
1327       <title><emphasis>Input</emphasis> Tab</title>
1328
1329       <para>Between rendering and outputting these blocks terminatorX checks
1330       for mouse motion. The problem with mice is: they don&#39;t report when
1331       they have stopped. This is why terminatorX assumes your mouse has
1332       stopped if there is no motion reported for certain amount of
1333       render/output-cycles. This value is configurable via the
1334       <emphasis>Stop-sense-cycles</emphasis> option. If you decrease your
1335       buffersize of course you shorten the cycle time as well, therefore if
1336       you here strange stop/run behaviour of the audio output while scratching
1337       after you decreased the buffer size you might have to increase the
1338       stop-sense value too.</para>
1339
1340       <para>XInput Device: <emphasis>WARNING:</emphasis> Use this option
1341       *only* if you want to use an input device other than your default-mouse
1342       for scratching. Selecting your default pointer will cause terminatorX to
1343       crash. See the &#34;Using a turntable&#34; section on the terminatorX
1344       homepage for details.</para>
1345     </sect2>
1346
1347     <sect2>
1348       <title><emphasis>User Interface</emphasis> Tab</title>
1349
1350       <para>With <emphasis>Update Idle</emphasis> / <emphasis>Update Delay</emphasis>
1351       you can configure GUI responsiveness: Higher <emphasis>Update Idle</emphasis>
1352       will cause the wave display (position display) and flash-widgets to
1353       update less often. Higher <emphasis>Update Delay</emphasis> values will
1354       cause the parameter widgets to update less often.</para>
1355     </sect2>
1356
1357     <sect2>
1358       <title><emphasis>Misc</emphasis> Tab</title>
1359
1360       <para>You can now enter the soundfile editor of your choice in the
1361       &#34;Sound file editor&#34; field. This editor will be started when
1362       clicking the <emphasis>Edit</emphasis>-button in the main panel of the
1363       vtt-gui. If you enter for example &#34;myeditor&#34; terminatorX will
1364       run &#34;myeditor sample_in_vtt.wav&#34;.</para>
1365     </sect2>
1366   </sect1>
1367
1368   <sect1 id="CONTACT">
1369     <title>Contact / Download</title>
1370
1371     <para>Find out more about terminatorX at it&#39;s <ulink
1372     url="http://www.terminatorX.cx">homepage</ulink>.</para>
1373
1374     <para>Send me comments, bug-reports, patches or scratches (see scratches
1375     section on the terminatorX homepage) at: <email>alex@lisas.de</email></para>
1376   </sect1>
1377 </article>