Fixing things - Alex
[terminatorX.git] / 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>terminatorX is a realtime audio synthesizer that allows you to
83       &#34;scratch&#34; on digitally sampled audio data (*.wav, *.au, *.ogg,
84       *.mp3, etc.) the way hiphop-DJs scratch on vinyl records. It features
85       multiple turntables, realtime effects (buit-in as well as <ulink
86       url="http://www.ladspa.org">LADSPA</ulink> plugin effects), a sequencer
87       and MIDI interface - all accessible through an 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://xmlsoft.org/">libxml2</ulink> to
285                   read terminatorX set and rc files</para>
286                 </listitem>
287
288                 <listitem>
289                   <para><ulink url="http://www.gzip.org/zlib/">zlib</ulink> to
290                   create compressed XML set files to save diskspaces</para>
291                 </listitem>
292
293                 <listitem>
294                   <para><ulink url="http://www.68k.org/~michael/audiofile/">libaudiofile</ulink>
295                   for loading misc other audio files.</para>
296                 </listitem>
297
298                 <listitem>
299                   <para><ulink
300                   url="http://www-ti.informatik.uni-tuebingen.de/~hippm/mpg123.html">mpg123</ulink>
301                   for mp3 pre-listening (and fallback loading if mad is not
302                   installed).</para>
303                 </listitem>
304
305                 <listitem>
306                   <para><ulink url="http://www.xiph.org/ogg/vorbis/">ogg123</ulink>
307                   for ogg pre-listening (and fallback loading if libvorbis is
308                   not installed).</para>
309                 </listitem>
310
311                 <listitem>
312                   <para><ulink
313                   url="http://home.sprynet.com/~cbagwell/sox.html">sox</ulink>
314                   for misc files pre-listening (and fallback loading of misc
315                   files).</para>
316                 </listitem>
317               </itemizedlist>
318             </listitem>
319           </itemizedlist>
320         </listitem>
321
322         <listitem>
323           <para>Hardware</para>
324
325           <itemizedlist>
326             <listitem>
327               <para>An <ulink url="http://www.alsa-project.org">ALSA</ulink>
328               or OSS compatible soundcard capable of stereo output.</para>
329             </listitem>
330
331             <listitem>
332               <para>A good clean mouse and pad, a good X-Pointer setup.</para>
333             </listitem>
334           </itemizedlist>
335         </listitem>
336       </itemizedlist>
337
338       <para>A note on performance: terminatorX is known to run satisfyingly on
339       pentium-class systems (or above of course). Increasing the number of
340       turntables or plugins will of course require more performant systems.</para>
341     </sect2>
342
343     <sect2 id="INSTALLATION">
344       <title>Installation</title>
345
346       <para>For GNU-standards&#39; sake this information is now located in the
347       <filename moreinfo="none">INSTALL</filename> file that came with this
348       distribution of terminatorX.</para>
349     </sect2>
350   </sect1>
351
352   <sect1 id="OPERATION">
353     <title>Operation</title>
354
355     <para>With Release Version 3.70 the terminatorX has undergone some
356     redesign again. It&#39;s split up in the main controls (master, sequencer,
357     engine controls and menu buttons) and the individual turntable&#39;s
358     controls. Each turntable has it&#39;s own GUI split up into control and
359     audio panel.</para>
360
361     <sect2>
362       <title>Menu</title>
363
364       <para>To clean-up the user interface a bit further some functions have
365       been moved into a more standard menu bar for the main window (with
366       release 3.80). The following sub-menus are available:</para>
367
368       <sect3>
369         <title><emphasis>File</emphasis> Menu</title>
370
371         <para>The <emphasis>File</emphasis> menu features these functions:</para>
372
373         <itemizedlist>
374           <listitem>
375             <para><emphasis>New</emphasis></para>
376
377             <para>Erases all existing turntables and sequencer events and
378             creates a new and untouched turntable.</para>
379           </listitem>
380
381           <listitem>
382             <para><emphasis>Open</emphasis></para>
383
384             <para>Allows restoring of a previously saved terminatorX set file.</para>
385           </listitem>
386
387           <listitem>
388             <para><emphasis>Save</emphasis></para>
389
390             <para>Saves the current turntables and events in a terminatorX set
391             file.</para>
392           </listitem>
393
394           <listitem>
395             <para><emphasis>Save As</emphasis></para>
396
397             <para>Like <emphasis>Save</emphasis> but prompts for a new file
398             name.</para>
399           </listitem>
400
401           <listitem>
402             <para><emphasis>Quit</emphasis></para>
403           </listitem>
404         </itemizedlist>
405       </sect3>
406
407       <sect3>
408         <title><emphasis>Turntables</emphasis> Menu</title>
409
410         <para>The <emphasis>Turntables</emphasis> menu features these
411         functions:</para>
412
413         <itemizedlist>
414           <listitem>
415             <para><emphasis>Add Turntable</emphasis></para>
416
417             <para>Adds a new turntable to the current set of turntables.</para>
418           </listitem>
419
420           <listitem>
421             <para><emphasis>Record Audio to Disk</emphasis></para>
422
423             <para>On activation of this option, terminatorX will prompt for a
424             file name for the RIFF/Wave file to create. Once activated
425             terminatorX will start recording audio to disk the next time the
426             audio engine is started - either by pressing the Power or the Play
427             button. Recording will stop when the audio engine is stopped
428             again. The created RIFF/Wave file will be a 16Bit/Stereo wave-file
429             with the sampling rate selected for the current audio backend.</para>
430           </listitem>
431         </itemizedlist>
432       </sect3>
433
434       <sect3>
435         <title><emphasis>Options</emphasis> Menu</title>
436
437         <para>The <emphasis>Options</emphasis> menu features these functions:</para>
438
439         <itemizedlist>
440           <listitem>
441             <para><emphasis>Fullscreen</emphasis></para>
442
443             <para>Maximizes the terminatorX main windows to use the complete
444             screen. Note that this requires a NETWM compliant window manager
445             to work (GNOME2&#39;s metacity works nicely, while openbox 2.x
446             does not for example). By choosing this option again
447             terminatorX&#39; window can be resized back to the previous state
448             again. The setting will be stored in the <filename>~/.terminatorXrc</filename>
449             file.</para>
450           </listitem>
451
452           <listitem>
453             <para><emphasis>Preferences</emphasis></para>
454
455             <para>Will pop up the Preferences dialog. For more details on
456             configuration itself see the <xref linkend="CONFIGURATION" />
457             section.</para>
458           </listitem>
459         </itemizedlist>
460       </sect3>
461
462       <sect3>
463         <title><emphasis>Help</emphasis> Menu</title>
464
465         <para>The <emphasis>Help</emphasis> menu features these functions:</para>
466
467         <itemizedlist>
468           <listitem>
469             <para><emphasis>Contents</emphasis></para>
470
471             <para>Starts a <emphasis>gnome-help</emphasis> (aka
472             <emphasis>yelp</emphasis>) process to display the very manual you
473             are reading right now.</para>
474           </listitem>
475
476           <listitem>
477             <para><emphasis>About</emphasis></para>
478
479             <para>Selecting this menu item will cause a small dialog to pop up
480             that contains some information on the compile time settings for
481             the terminatorX binary as well as the license.</para>
482           </listitem>
483
484           <listitem>
485             <para><emphasis>Visit terminatorX.cx</emphasis></para>
486
487             <para>Will try to spawn a browser process to load the URL
488             &#34;http://terminatorX.cx&#34; - for easy update checking or just
489             unecessary bloat.</para>
490           </listitem>
491         </itemizedlist>
492       </sect3>
493     </sect2>
494
495     <sect2 id="MAINCONTROLS">
496       <title>Main Controls</title>
497
498       <para>The controls of the master GUI are located in the top and the
499       right bar of the terminatorX main window.</para>
500
501       <itemizedlist>
502         <listitem>
503           <para><emphasis>Audio Engine Power / Mouse Grab</emphasis></para>
504
505           <para>With the Audio Engine Button you can en- and disable the audio
506           playback engine without activating the sequencer. Unlike earlier
507           versions you will not automatically enter mouse-grab mode so you can
508           modify volume/pitch/echo settings etc. while you actually hear what
509           you do.</para>
510
511           <para>Some functions are not available when the audio engine is on,
512           their controls will be marked insensitive when you enable the
513           engine. To actually enter grab mode you&#39;ll have to click on the
514           &#34;Mouse Grab&#34; button. See <xref linkend="GRABMODE" /> (Grab
515           Mode Operation) to find out how to control the software then.</para>
516         </listitem>
517
518         <listitem>
519           <para><emphasis>Sequencer Play / Record / Stop</emphasis></para>
520
521           <para>Please read the <link linkend="SEQUENCER">sequencer</link>
522           section to find out more about the sequencer.</para>
523         </listitem>
524
525         <listitem>
526           <para><emphasis>Master Volume / Pitch</emphasis></para>
527
528           <para>The volume and pitch settings of the individual turntables are
529           relative to these master settings. This information will be stored
530           within the .tX set files.</para>
531         </listitem>
532       </itemizedlist>
533     </sect2>
534
535     <sect2 id="TURNtableCONTROLS">
536       <title>Turntable Controls</title>
537
538       <para>The turntable GUI contains multiple controls and the real time
539       displays for each turntable. To save some space on your desktop and to
540       give terminatorX the traditional audio-application look, terminatorX
541       features &#34;knob&#34;-widgets. These widgets work pretty
542       straight-forward: click somewhere within the widget and keep the left
543       mouse-button pressed. Now move the mouse up and down or left and right
544       to increase/decrease the control&#39;s value. All those widget are
545       coupled with a text entry field since 3.70, which allows you to enter
546       values directly.</para>
547
548       <para>A turntable is visualized by two panels: the control and the audio
549       panel. These are no longer combined for better layout management.</para>
550
551       <para>Sometimes you might find a certain audio or control panel
552       unnecessary - simply eating up space. Since release 3.73 it is possible
553       to minimize audio and control panels to the <emphasis>panel bar</emphasis>
554       with the tiny button with a blue bar icon in the upper right edge of
555       each panel. This bar works just like GNOME&#39;s window list or
556       KDE&#39;s kicker: When a panel is minimized a button in the bar will
557       appear, representing the minimized window. On clicking this button the
558       button will be removed and the minimized panel is displayed again. When
559       no panels are minimized the panel bar automatically disappears to save
560       display space.</para>
561
562       <sect3>
563         <title>Turntable Audio Panel</title>
564
565         <para>The complete audio-file loaded into a turntable is displayed in
566         the green-on-black audio-widget. When playing terminatorX will
567         indicate the current position within the sample with a red cursor (a
568         blue/green cursor indicates the turntable is muted).</para>
569
570         <para>Additionally there are some controls above the audio-display:</para>
571
572         <itemizedlist>
573           <listitem>
574             <para><emphasis>Turntable Label</emphasis></para>
575
576             <para>This label indicates the turntables name. The name can be
577             set via the control panel</para>
578           </listitem>
579
580           <listitem>
581             <para><emphasis>File Button</emphasis></para>
582
583             <para>This button holds the name of the audio-file currently
584             loaded. When there&#39;s no sample loaded the button will read
585             &#34;NONE&#34; to indicate the current status. Click on this
586             button to get a menu from which you can load/reload a sound file
587             or run an external soundfile editor. Alternatively you can
588             drag&#39;n&#39;drop files over the audio-display to load them.</para>
589
590             <itemizedlist>
591               <title>The File Button Menu</title>
592
593               <listitem>
594                 <para><emphasis>Load File</emphasis></para>
595
596                 <para>Choose this menu entry to select a soundfile from the
597                 file-selection dialog that will pop-up.</para>
598               </listitem>
599
600               <listitem>
601                 <para><emphasis>Reload File</emphasis></para>
602
603                 <para>Choose this menu entry to re-read the audio-file.</para>
604               </listitem>
605
606               <listitem>
607                 <para><emphasis>Edit File</emphasis></para>
608
609                 <para>This menu entry will run the external audiofile-editor
610                 (that can be specified via the options-dialog) with the
611                 current audio-file as a parameter. Choose reload after editing
612                 and saving the file.</para>
613               </listitem>
614             </itemizedlist>
615           </listitem>
616
617           <listitem>
618             <para><emphasis>Mouse Mapping</emphasis></para>
619
620             <para>terminatorX allows mapping misc parameters to the mouse axis
621             of your choice. These mappings will be activated in grab mode, so
622             if you move your mouse in X or Y direction in grab mode the
623             parameters you selected from this menu will be affected (for this
624             turntable). Since Version 3.70 this mappings are no longer
625             hardcoded to built-in controls but available for all parameters
626             that qualify as &#34;mappable&#34;. Note that this includes
627             plugins&#39; controls as well.</para>
628           </listitem>
629
630           <listitem>
631             <para><emphasis>MIDI Mapping</emphasis></para>
632
633             <para>This button is available only if terminatorX was built with
634             ALSA MIDI support and the sequencer input port was created
635             successfully on startup. For more information on terminatorX&#39;
636             MIDI interface see <xref linkend="MIDI" /> section.</para>
637           </listitem>
638         </itemizedlist>
639       </sect3>
640
641       <sect3>
642         <title>Turntable Controls</title>
643
644         <para>These controls are now grouped within functional panels. The
645         number of panels depends on the number of plugins loaded. terminatorX
646         allows hiding the controls not required via the yellow triangle
647         button. To un-hide just click the button again. The first panels are
648         the standard controls for a turntable, then follows the dynamic
649         FX-section and below that follow the pitch and volume controls.</para>
650
651         <sect4>
652           <title>Main Panel</title>
653
654           <itemizedlist>
655             <listitem>
656               <para><emphasis>Name Field</emphasis></para>
657
658               <para>The main panel features a text entry field that allows
659               setting a name for the related turntable. The Labels for the
660               controls and the audio-display will update accordingly.</para>
661             </listitem>
662
663             <listitem>
664               <para><emphasis>Delete Button</emphasis></para>
665
666               <para>Pressing this button remove the turntable from the current
667               setup. Note that all sequencer events recorded for this
668               turntable will be erased, too.</para>
669             </listitem>
670
671             <listitem>
672               <para><emphasis>Pitch Adj. Button</emphasis></para>
673
674               <para>Using two (or more) loops and terminatorX&#39;
675               synchronization facility usually requires adjusting the pitch of
676               the loops so that the turntables play in sync. For precisely cut
677               loops this usually means making them run equally fast or one
678               running twice as fast as the other etc. Manually finding the
679               necessary pitch values usually consumes a significant amount of
680               time so the feature <emphasis>Pitch Adjust</emphasis> helps
681               speeding up this process.</para>
682
683               <para>Clicking this button will cause the <emphasis>Compute
684               Pitch</emphasis> dialog to pop up. With this dialog it is
685               possible to specify how many loops of this turntable should be
686               played as fast as a certain amount of loops of the master
687               turntable. After pressing the <emphasis>Ok</emphasis> button
688               terminatorX will adjust the turntable&#39;s ptich accordingly in
689               order to match the given playback speed requirements.</para>
690
691               <para>Note that this feature is proabably useless when loading
692               complete songs into terminatorX - it&#39;s intended for use with
693               precisely cut loops.</para>
694             </listitem>
695           </itemizedlist>
696         </sect4>
697
698         <sect4>
699           <title>Trigger Panel</title>
700
701           <para>The trigger panel holds all controls related to triggering the
702           turntable. For more details on synchronization see <xref
703           linkend="SYNCHRONIZATION" /> (synchronization).</para>
704
705           <itemizedlist>
706             <listitem>
707               <para><emphasis>Trigger! Button</emphasis></para>
708
709               <para>Pressing this button triggers the turntable now. With the
710               audio engine enabled this will cause the turntable to start
711               playing back audio from the beginning of the sample.</para>
712             </listitem>
713
714             <listitem>
715               <para><emphasis>Stop Button</emphasis></para>
716
717               <para>Guess what, this stops this turntable&#39;s
718               audio-playback.</para>
719             </listitem>
720
721             <listitem>
722               <para><emphasis>Master Button</emphasis></para>
723
724               <para>Enabling this button makes this turntable the
725               <emphasis>sync-master</emphasis>. Note that only
726               <emphasis>one</emphasis> turntable at a time can be the
727               sync-master.</para>
728             </listitem>
729
730             <listitem>
731               <para><emphasis>Client Button</emphasis></para>
732
733               <para>This button marks the turntable as <emphasis>sync-client</emphasis>,
734               so it will be triggered with the master automatically.</para>
735             </listitem>
736
737             <listitem>
738               <para><emphasis>Sync-Cycles Selection</emphasis></para>
739
740               <para>The sync cycles determine how often a sync-client should
741               be triggered. With a setting of zero the sync-client will be
742               (re-)triggered with <emphasis>every</emphasis> trigger of the
743               sync-master. A setting of 1 will (re-)trigger the client every
744               <emphasis>second</emphasis> master-trigger and so on.</para>
745             </listitem>
746           </itemizedlist>
747
748           <para>Below the effect queue a turntable shows some more controls:
749           <itemizedlist><listitem><para><emphasis>Pitch Control</emphasis></para><para>The
750           pitch control allows setting the default playback speed for that
751           turntable (the &#34;motor&#34; speed). Negative values will result
752           in the sample being played backwards.</para></listitem><listitem><para><emphasis>PAN
753           Control</emphasis></para><para>This parameter allows setting the
754           position of the turntable&#39;s main signal within the stereo
755           panorama.</para></listitem><listitem><para><emphasis>VU Meter</emphasis></para><para>The
756           displayed signal shows the turntable&#39;s current signal not
757           including the echo-signal which is mixed separately.</para></listitem></itemizedlist></para>
758         </sect4>
759       </sect3>
760
761       <sect3>
762         <title>The Effect Queue</title>
763
764         <para>With release 3.70 the effects are no longer hardcoded into the
765         turntable. The effects are now arranged within an per-turntable
766         effect-queue. The effect sequence is configurable by the user. To move
767         an effect to higher position within the queue, press the
768         <emphasis>blue upward arrow button</emphasis>. This will cause the
769         effect to be rendered <emphasis>before</emphasis> the following
770         effects. The <emphasis>blue downward arrow button</emphasis> will move
771         the effect down by one position. It will then be rendered
772         <emphasis>after</emphasis> the preceding effects.</para>
773
774         <para>There are two types of effects: the traditional built-in effects
775         (Lowpass and Echo) and LADSPA plugins. The built-in effects are always
776         available and cannot be removed (but disabled). There can be only one
777         instance of a built-in effect. The LADSPA plugins on the other hand
778         may be instantiated multiple times and can be removed from the effect
779         queue. Press the <emphasis>blue cross button</emphasis> to achieve
780         this.</para>
781
782         <figure float="0">
783           <title>An example for a terminatorX effect queue</title>
784
785           <graphic fileref="figures/signalflow.png" format="PNG" />
786         </figure>
787
788         <para>Now since release 3.71 the built-in echo effect is treated
789         differently from other effects. Where all other effects feed their
790         signal back into the effect queue the echo effect doesn&#39;t touch
791         the input signal. It&#39;s echo-signal is mixed separately from the
792         turntable&#39;s main signal to allow a different panning value for the
793         echo-signal. This mode of operation does have some side-effects:
794         imagine a lowpass filter with a position after the echo effect in the
795         effect queue. This will result in the turntable&#39;s main signal
796         being lowpass-filtered but it will leave the echo-signal
797         lowpass-unfiltered.</para>
798
799         <para>Some may call this behaviour a bug - whereas I would consider it
800         a feature ;). Anyway if the above description didn&#39;t clear things
801         up maybe the displayed figure does. It shows a schematic effect queue
802         with the built-in effects and two LADSPA effects enabled. Now with
803         this setup you will not hear anything from the second LADSPA effect in
804         the echo-signal.</para>
805
806         <para>For more information on a LADSPA plugin, press it&#39;s
807         panel&#39;s label and a small info box will pop up.</para>
808
809         <itemizedlist>
810           <listitem>
811             <para><emphasis>FX Button</emphasis></para>
812
813             <para>Press this button to load a LADSPA plugin into the effect
814             queue of the turntable. A menu holding the available
815             (terminatorX-&#34;compatible&#34;) LADSPA-plugins will pop up. The
816             plugins are grouped within submenus according to the modules the
817             plugins are contained in. Simply select the plugin you want to
818             load from this menu and a panel for it will pop up at the end of
819             the effect queue.</para>
820
821             <para>Note that due to the wide parameter ranges some LADSPA
822             plugins have they sometimes might be hard to control with the knob
823             widget. In these cases you might want to use the text field to
824             enter values. For more details on Plugins see <xref
825             linkend="LADSPAPLUGINS" /> (LADSPA).</para>
826           </listitem>
827         </itemizedlist>
828       </sect3>
829
830       <sect3>
831         <title>Lowpass Panel</title>
832
833         <para>terminatorX features a built-in resonating lowpass filter that
834         can be configured with this panel.</para>
835
836         <itemizedlist>
837           <listitem>
838             <para><emphasis>Enable Button</emphasis></para>
839
840             <para>Activating this button will enable the lowpass filter for
841             this turntable.</para>
842           </listitem>
843
844           <listitem>
845             <para><emphasis>Input Gain Control</emphasis></para>
846
847             <para>With this parameter you can amplify the signal that goes
848             into the lowpass filter if required.</para>
849           </listitem>
850
851           <listitem>
852             <para><emphasis>Frequency Control</emphasis></para>
853
854             <para>Use this parameter to set the cutoff frequency for the
855             lowpass filter. Minimum: 0=0Hz, Maximum: 1=22KHz.</para>
856           </listitem>
857
858           <listitem>
859             <para><emphasis>Resonance</emphasis></para>
860
861             <para>Use this parameter to set the resonance-value. Minimum: 0=no
862             resonance, Maximum: 1=max resonance.</para>
863           </listitem>
864         </itemizedlist>
865       </sect3>
866
867       <sect3>
868         <title>Echo Panel</title>
869
870         <para>Additionally terminatorX features a built-in echo effect. It can
871         be configured with this panel.</para>
872
873         <itemizedlist>
874           <listitem>
875             <para><emphasis>Enable Button</emphasis></para>
876
877             <para>Activating this button will enable the echo effect for this
878             turntable.</para>
879           </listitem>
880
881           <listitem>
882             <para><emphasis>Duration Control</emphasis></para>
883
884             <para>Use this parameter to set the length of the echo. The
885             duration parameter scales to the actual sample length: so if you
886             set it to 0.5 you will hear the echo when the red playback cursor
887             is half way through the sample. This is true for samples that are
888             shorter than terminatorX&#39; maximum echo buffer size only.</para>
889           </listitem>
890
891           <listitem>
892             <para><emphasis>Feedback Control</emphasis></para>
893
894             <para>Set the echo&#39;s feedback amount with this parameter.</para>
895           </listitem>
896
897           <listitem>
898             <para><emphasis>Volume Control</emphasis></para>
899
900             <para>This parameter can additionally amplify the echo signal.
901             Unlike the feedback parameter above this parameter has no
902             influence on the signal fed back into the echo-buffer, it effects
903             merely the playback volume of the echo signal.</para>
904           </listitem>
905
906           <listitem>
907             <para><emphasis>Pan Control</emphasis></para>
908
909             <para>The echo effect differs from other effects as it&#39;s
910             output signal will be mixed separately. The main goal here is to
911             allow positioning the echo signal at a position in the stereo
912             panorama that differs from the main panning position of the
913             turntable to achieve a somewhat spacial effect. The easy example
914             is: turntable&#39;s panning left, echo&#39;s panning right. As
915             both pan parameters are sequenceable you can create nice motion
916             effects from this starting point.</para>
917           </listitem>
918         </itemizedlist>
919       </sect3>
920     </sect2>
921
922     <sect2 id="SYNCHRONIZATION">
923       <title>Synchronization</title>
924
925       <para>Let&#39;s start off with an example: Say you have two drum loops
926       and one bassline loaded in three turntables. Of course you want these
927       samples to be triggered at the same time but you don&#39;t want to
928       invest time to cut them to the exact length. Therefore you decide which
929       of the drum loops to make the sync master. You&#39;ll have to do this
930       before you enable the audio engine (for now). Only one turntable can be
931       the sync master. Now you can make the other two sync clients which will
932       cause them to be (re-)triggered whenever the master is (re-)triggered.
933       The number you can select to the right of the <emphasis>client button</emphasis>
934       sets the trigger delay for the button: if it&#39;s set to zero the
935       turntable will be triggered with every master trigger, if it&#39;s set
936       to 1 it&#39;ll be triggered every 2nd master trigger and so on.</para>
937
938       <para>A nice side effect of this feature is: you can now scratch the
939       second (sync client) drum loop and no matter whether you&#39;re
940       scratching is good or not the beat will be triggered correctly again ;)</para>
941     </sect2>
942
943     <sect2 id="GRABMODE">
944       <title>Grab Mode Operation</title>
945
946       <para>After pressing the <emphasis>Mouse Grab button</emphasis>
947       terminatorX enters &#34;grab mode&#34;. This mode actually locks the
948       mouse (as this input is now used to control the real time parameters)
949       and therefore you&#39;ll have to know some mouse/keyboard shortcuts to
950       control the software without the GUI.</para>
951
952       <para>Press <keycap moreinfo="none">ESCAPE</keycap> to quit grab mode.</para>
953
954       <para>Select the turntable with input focus: The first turntable to hold
955       the input focus will be the first turntable. You can now use <keycap
956       moreinfo="none">TAB</keycap> or right mouse button to switch to the next
957       turntable. Alternatively you can use <keycap moreinfo="none">F1</keycap>
958       to <keycap moreinfo="none">F12</keycap> to select turntable 1 to 12.</para>
959
960       <para>Now the turntable that has the focus is the one you will
961       manipulate with your mouse and keyboard inputs: Note that you can
962       actually map different functions to the mouse x/y axis - so what
963       actually happens when you move your mouse depends on what you select on
964       the x/y control panels for each turntable.</para>
965
966       <table>
967         <title>Keyboard Controls in Grab Mode</title>
968
969         <tgroup cols="2">
970           <thead>
971             <row>
972               <entry>Key</entry>
973
974               <entry>Function</entry>
975             </row>
976           </thead>
977
978           <tbody>
979             <row>
980               <entry><keycap moreinfo="none">TAB</keycap></entry>
981
982               <entry>select next turntable</entry>
983             </row>
984
985             <row>
986               <entry><keycap moreinfo="none">F1</keycap> to <keycap
987               moreinfo="none">F12</keycap></entry>
988
989               <entry>select turntable 1 to 12</entry>
990             </row>
991
992             <row>
993               <entry><keycap moreinfo="none">RETURN</keycap></entry>
994
995               <entry>triggers the turntable</entry>
996             </row>
997
998             <row>
999               <entry><keycap moreinfo="none">BACKSPACE</keycap></entry>
1000
1001               <entry>stops the turntable</entry>
1002             </row>
1003
1004             <row>
1005               <entry><keycap moreinfo="none">S</keycap></entry>
1006
1007               <entry>toggles &#34;Sync Client&#34;</entry>
1008             </row>
1009
1010             <row>
1011               <entry><keycap moreinfo="none">SPACE</keycap></entry>
1012
1013               <entry>while pressed turntable speed is mapped to mouse speed
1014               (scratching!)</entry>
1015             </row>
1016
1017             <row>
1018               <entry><keycap moreinfo="none">ALT</keycap></entry>
1019
1020               <entry>mute on/off</entry>
1021             </row>
1022
1023             <row>
1024               <entry><keycap moreinfo="none">CTRL</keycap></entry>
1025
1026               <entry>mute on/off (inverted)</entry>
1027             </row>
1028
1029             <row>
1030               <entry><keycap moreinfo="none">F</keycap></entry>
1031
1032               <entry>(&#34;fast&#34;) warp mode (while scratching)</entry>
1033             </row>
1034
1035             <row>
1036               <entry><keycap moreinfo="none">W</keycap></entry>
1037
1038               <entry>same as above but the audio will be muted while warping</entry>
1039             </row>
1040           </tbody>
1041         </tgroup>
1042       </table>
1043
1044       <table>
1045         <title>Mouse Button Controls in Grab Mode</title>
1046
1047         <tgroup cols="2">
1048           <thead>
1049             <row>
1050               <entry>Mouse Button</entry>
1051
1052               <entry>Function</entry>
1053             </row>
1054           </thead>
1055
1056           <tbody>
1057             <row>
1058               <entry><emphasis>Left button</emphasis></entry>
1059
1060               <entry>same as <keycap moreinfo="none">SPACE</keycap>:
1061               scratching (triggers the turntable when stopped)</entry>
1062             </row>
1063
1064             <row>
1065               <entry><emphasis>Right button</emphasis></entry>
1066
1067               <entry>select next turntable</entry>
1068             </row>
1069
1070             <row>
1071               <entry><emphasis>Middle button</emphasis></entry>
1072
1073               <entry>mute on/off</entry>
1074             </row>
1075           </tbody>
1076         </tgroup>
1077       </table>
1078
1079       <para>Scratching works as before: press <keycap moreinfo="none">SPACE</keycap>
1080       or left mouse button to actually scratch: now your mouse controls the
1081       turntables speed. Release it to let that turntable spin at default speed
1082       again.</para>
1083     </sect2>
1084
1085     <sect2 id="DRAGNDROP">
1086       <title>Drag And Drop</title>
1087
1088       <para>Since V3.55 terminatorX provides multiple DND-Drop-Targets for use
1089       with GNOME / gmc (gmc is the GNU Midnight Commander), Nautilus or the
1090       Enlightenment File Manager (efm). You can load an audiofile into an
1091       existing turntable by dragging it from a gmc (or efm or whatever)-window
1092       and drop it over a. the <emphasis>file button</emphasis> (audio-display)
1093       or b. (the easier target ;) over the audio-display (the green on black
1094       widget that displays the audiodata).</para>
1095
1096       <para>To add a file to the set (== to load the file into a *new*
1097       turntable) simply drop the audiofile over the &#34;New Turntable&#34;
1098       Button. To load a complete terminatorX-set simply drop the set file
1099       (*.tX) over the &#34;Load Set&#34; button.</para>
1100     </sect2>
1101
1102     <sect2 id="SEQUENCER">
1103       <title>The Sequencer</title>
1104
1105       <para>Release 3.60 introduced the sequencer. It can record and play back
1106       events for the following parameters:</para>
1107
1108       <itemizedlist>
1109         <listitem>
1110           <para>master volume &#38; pitch</para>
1111         </listitem>
1112
1113         <listitem>
1114           <para>scratching</para>
1115         </listitem>
1116
1117         <listitem>
1118           <para>(turntable) volume &#38; pitch</para>
1119         </listitem>
1120
1121         <listitem>
1122           <para>triggers</para>
1123         </listitem>
1124
1125         <listitem>
1126           <para>loop (on/off)</para>
1127         </listitem>
1128
1129         <listitem>
1130           <para>sync client settings</para>
1131         </listitem>
1132
1133         <listitem>
1134           <para>muting</para>
1135         </listitem>
1136
1137         <listitem>
1138           <para><emphasis>all</emphasis> parameters for the effects. This
1139           includes built-in effects (lowpass and echo) as well as LADSPA
1140           plugins.</para>
1141         </listitem>
1142       </itemizedlist>
1143
1144       <para>To record events simply press the <emphasis>Record</emphasis>
1145       button of the sequencer, then press the <emphasis>Play</emphasis>
1146       button. All actions (for sequenceable parameters - see above) you now
1147       take will be recorded into the song list. Press <emphasis>Stop</emphasis>
1148       and <emphasis>Play</emphasis> again to see/hear how terminatorX plays
1149       back the events recorded before. You can now record events again for
1150       e.g. another turntable or record other parameters for the same turntable
1151       - whatever you want to do. Recording events for parameters for which
1152       events have been recorded before will result in dubbing: if you touch a
1153       parameter while recording, events previously recorded will be erased
1154       from the moment you touch the parameter until you stop recording.</para>
1155
1156       <para>When recording long sequences/songs you can use the
1157       sequencer-scale to start recording/playback from any song-position you
1158       want. To record a single parameter value at a certain position simply
1159       move the sequencer-scale to that position, press <emphasis>Record,</emphasis>
1160       set the parameter and press <emphasis>Stop</emphasis> again.</para>
1161
1162       <para>There is no other the way to edit the sequencer events currently,
1163       but future releases may feature an event-list editor.</para>
1164     </sect2>
1165
1166     <sect2 id="LADSPAPLUGINS">
1167       <title>Plugins (LADSPA)</title>
1168
1169       <para>Since release 3.70 terminatorX supports LADSPA-plugins. LADSPA is
1170       the &#34;Linux Audio Developer&#39;s Simple Plugin API&#34; which was
1171       designed by developers on the Linux-Audio-Developer-Mailinglist and is
1172       maintained by Richard W.E. Furse. For more information on LADSPA, other
1173       LADSPA-hosts and LADSPA-plugins checkout the <ulink
1174       url="http://www.ladspa.org">LADSPA homepage</ulink>.</para>
1175
1176       <para>Not every plugin is supported by terminatorX though. As the
1177       plugins are inserted into the per-turntable effect-queue, they have to
1178       be mono plugins (as is that queue) for now. This is why terminatorX will
1179       load plugins with <emphasis>one</emphasis> audio-in port and
1180       <emphasis>one</emphasis> audio-out port only.</para>
1181
1182       <para>The decision on whether a plugin is terminatorX-suitable is made
1183       on terminatorX startup, so only plugins that fit into the effect queue
1184       will be offered in the plugin-menu that pops up when the
1185       <emphasis>FX</emphasis> button is clicked. Depending on whether the
1186       terminatorX binary you&#39;re using was built with or without liblrdf (<xref
1187       linkend="LIBLRDF" />) support the plugin menu will either contain
1188       sub-menus with plugin categories (with liblrdf) or just a single menu
1189       with the <emphasis>Unclassified</emphasis> category.</para>
1190
1191       <para>On startup terminatorX will print some information on the
1192       LADSPA-plugins analysis process to the standard output. Watch the
1193       terminal you run terminatorX from for that info if you have problems
1194       loading a plugin.</para>
1195
1196       <para>As specified in the LADSPA-standard LADSPA-plugins can be located
1197       in multiple directories across the filesystem. To enable LADSPA-hosts to
1198       find those plugins you have to set the environment variable
1199       <envar>LADSPA_PATH</envar> accordingly. Let&#39;s say you store your
1200       plugins in <filename moreinfo="none">/usr/lib/ladspa</filename> and
1201       <filename moreinfo="none">/home/yourlogin/plugins</filename> then you
1202       would have to set:</para>
1203
1204       <para><envar>LADSPA_PATH</envar>=<filename moreinfo="none">/usr/lib/ladspa:/home/yourlogin/plugins</filename></para>
1205
1206       <para>As a fallback terminatorX will look in the standard directories
1207       <filename moreinfo="none">/usr/lib/ladspa</filename> and <filename
1208       moreinfo="none">/usr/local/lib/ladspa</filename> if the environment
1209       variable is not set. Note that this is just a convenience-function, in
1210       order for other LADSPA-hosts to work properly, be sure to set your
1211       <envar>LADSPA_PATH</envar> correctly. It is a good idea to do that from
1212       somewhere in your system configuration (either in your rc-scripts or
1213       <filename moreinfo="none">/etc/profile</filename> or wherever you
1214       prefer).</para>
1215
1216       <sect3 id="LIBLRDF">
1217         <title>liblrdf support</title>
1218
1219         <para>Release 3.80 introduces support for Steve Harris&#39; great
1220         <ulink url="http://plugin.org.uk/releases/lrdf/">liblrdf</ulink>
1221         library which introduces an RDF based scheme to categorize LADSPA
1222         plugins. This approach allows storing additional meta-data for LADSPA
1223         plugins in separate RDF files. In order to make use of these RDF files
1224         a terminatorX binary (compiled with liblrdf support of course)
1225         requires the main <filename>ladspa.rdfs</filename> file and additional
1226         RDF files containing meta information about the LADSPA plugins
1227         installed. Steve Harris&#39; wonderful plugin library comes with such
1228         an additional description file for example.</para>
1229
1230         <para>By default terminatorX will search the directories
1231         <filename>/usr/share/ladspa/rdf</filename> and <filename>/usr/local/share/ladspa/rdf</filename>
1232         for RDF files. In case the files were installed to other locations it
1233         is possible to configure the LADSPA RDF path in the
1234         <emphasis>Misc</emphasis> tab of the <emphasis>Preferences</emphasis>
1235         dialog.</para>
1236
1237         <para>If the RDF are read successfully on startup, the LADSPA menu
1238         that pops up when clicking a turntable&#39;s <emphasis>FX</emphasis>
1239         button will feature multiple sub-menus with LADSPA plugin categories
1240         (eg <emphasis>Amplitude/Amplifier</emphasis>) in which you will find
1241         the according plugins. Plugins not categorized by the RDF files reside
1242         in the <emphasis>Unclassified</emphasis> menu.</para>
1243       </sect3>
1244     </sect2>
1245
1246     <sect2 id="MIDI">
1247       <title>MIDI Interface</title>
1248
1249       <para>Aside of controlling terminatorX with a regular mouse and keyboard
1250       it is possible to control parameters through MIDI events (since 3.80).
1251       The MIDI interface is based upon the ALSA sequencer API. On startup
1252       terminatorX creates a MIDI input port called &#34;terminatorX&#34;. You
1253       can now use for example the <ulink url="alsa-patch-bay link here">alsa-patch-pay</ulink>
1254       to connect an output port of your choice (either a hardware MIDI input
1255       device or a software generating midi events) to the terminatorX input
1256       port.</para>
1257
1258       <para>Once the connection is set up terminatorX receives MIDI events
1259       through the input port. To configure what MIDI events will have which
1260       effect on a terminatorX turntable you can bind MIDI events to parameters
1261       of your choice by clicking the <emphasis>MIDI Mapping</emphasis> button
1262       of the turntable&#39;s audio panel. As a result the
1263       <emphasis>Configure MIDI Bindings</emphasis> dialog will pop up which
1264       features a field labelled <emphasis>Selected MIDI Event</emphasis> that
1265       will frequently update to display the contents of the last MIDI event
1266       received by terminatorX. So in order to map a MIDI controller to a
1267       specific turntable parameter select the parameter of your choice from
1268       the parameter list, cause your MIDI event sending device to emit the
1269       event you want to map the parameter on and click the
1270       <emphasis>Bind</emphasis> button.</para>
1271
1272       <para>Immediately after binding the event you should see that the
1273       <emphasis>Event</emphasis> column entry of the selected parameter is
1274       updated to match the selected event. From now on all events matching the
1275       selected event will cause the turntable parameter to be updated. The GUI
1276       for that parameter will be refreshed accordingly. Note that it is
1277       possible to map the same event to multiple parameters.</para>
1278
1279       <para>The MIDI mappings are stored within terminatorX set files so you
1280       wont have to reconfigure your bindings every time you start up
1281       terminatorX. If you are unhappy with a chosen binding you can select the
1282       parameter and click the <emphasis>Remove Binding</emphasis> button to
1283       get rid of the parameter&#39;s MIDI mapping.</para>
1284
1285       <para>If you want to use your joystick to control terminatorX - I wrote
1286       a tiny tool to create MIDI events from joystick motion called
1287       <emphasis>aseqjoy</emphasis>. It&#39;s available from the <ulink
1288       url="http://terminatorX.cx/aseqjoy">terminatorX website</ulink>, too.</para>
1289     </sect2>
1290   </sect1>
1291
1292   <sect1 id="CONFIGURATION">
1293     <title>Configuration</title>
1294
1295     <para>The main terminatorX configuration parameters can be set up via the
1296     <emphasis>Preferences</emphasis> dialog, which can be activated from the
1297     terminatorX menu. The new <emphasis>Preferences</emphasis> dialog features
1298     multiple tabs for several aspects of configuration.</para>
1299
1300     <para>A word on the settings in general: your settings are stored in an
1301     XML file ( <filename moreinfo="none">~/.terminatorXrc).</filename> So if
1302     you think you completely messed up your settings you will have to exit
1303     terminatorX - delete this file - and then re-run terminatorX with the
1304     default settings. Note: is this file is now an XML file you can edit with
1305     an editor of your choice.</para>
1306
1307     <sect2>
1308       <title><emphasis>Audio</emphasis> Tab</title>
1309
1310       <para>This tab allows to select which audio backend to use. Currently
1311       there are two of these: one for the OSS (Open Sound System) backend and
1312       one for ALSA (Advanced Linux Sound Architecture) backend. Hopefully
1313       future releases will feature a JACK backend too.</para>
1314     </sect2>
1315
1316     <sect2>
1317       <title><emphasis>Audio: OSS</emphasis> Tab</title>
1318
1319       <para>Select the audio device you are going to use from the available
1320       options (or simply enter one yourself). terminatorX renders audio
1321       block-wise. In order to achieve close-to-realtime performance it is
1322       necessary to keep this blocks as small as possible. The main parameters
1323       that determine how close-to-realtime terminatorX will perform are
1324       <emphasis>No. of Buffers</emphasis> and <emphasis>Buffersize</emphasis>.
1325       The <emphasis>No. of Buffers</emphasis> parameter determines how many
1326       buffers the audio driver should use in most cases <emphasis>2</emphasis>
1327       should be the best setting and in rare cases <emphasis>3</emphasis>
1328       might give better results.</para>
1329
1330       <para>The value for the <emphasis>Buffersize</emphasis> setting will be
1331       evaluated as 2^buffersize by OSS. So if you set the value to
1332       <emphasis>8</emphasis> the actual buffer size will be 2^8=256 Bytes. The
1333       smaller the buffers&#39; size the better terminatorX will perform. The
1334       default setting of <emphasis>9</emphasis> should be acceptable in most
1335       conditions, but if you here &#34;clicks&#34;, or &#34;drops&#34; in
1336       audio output that are not related to your sample-material you will have
1337       to increase the buffer size. On the other hand if you believe
1338       terminatorX does not react fast enough you have to decrease this
1339       parameter.</para>
1340
1341       <para>Additionally you can select the sampling rate you want terminatorX
1342       to operate on - note that recording to disk will use the same sample
1343       rate.</para>
1344     </sect2>
1345
1346     <sect2>
1347       <title><emphasis>Audio: ALSA</emphasis> Tab</title>
1348
1349       <para>Using ALSA for audio output allows specifing the buffer sizes in
1350       microseconds. ALSA uses a ring-buffer to process audio. The
1351       <emphasis>Buffer Time</emphasis> option lets you set the size for the
1352       complete ring buffer, while the <emphasis>Period Time</emphasis>
1353       determines how many audio samples will be transferred to the audio
1354       device per cycle. I&#39;m not really sure on what kind of settings to
1355       recommend, however I had best results when setting the
1356       <emphasis>Period Time</emphasis> to 3rd or half of the
1357       <emphasis>Buffer Time</emphasis>. </para>
1358
1359       <para>It&#39;s advisable to set the <emphasis>Buffer Time</emphasis> to
1360       at least the double of the <emphasis>Period Time</emphasis>, but for a
1361       more detailed description check out the ALSA documentation.</para>
1362     </sect2>
1363
1364     <sect2>
1365       <title><emphasis>Input</emphasis> Tab</title>
1366
1367       <para>Between rendering and outputting these blocks terminatorX checks
1368       for mouse motion. The problem with mice is: they don&#39;t report when
1369       they have stopped. This is why terminatorX assumes your mouse has
1370       stopped if there is no motion reported for certain amount of
1371       render/output-cycles. This value is configurable via the
1372       <emphasis>Stop-sense-cycles</emphasis> option. If you decrease your
1373       buffersize of course you shorten the cycle time as well, therefore if
1374       you here strange stop/run behaviour of the audio output while scratching
1375       after you decreased the buffer size you might have to increase the
1376       stop-sense value too.</para>
1377
1378       <para>XInput Device: <emphasis>WARNING:</emphasis> Use this option
1379       *only* if you want to use an input device other than your default-mouse
1380       for scratching. Selecting your default pointer will cause terminatorX to
1381       crash. See the &#34;Using a turntable&#34; section on the terminatorX
1382       homepage for details.</para>
1383     </sect2>
1384
1385     <sect2>
1386       <title><emphasis>User Interface</emphasis> Tab</title>
1387
1388       <para>With <emphasis>Update Idle</emphasis> / <emphasis>Update Delay</emphasis>
1389       you can configure GUI responsiveness: Higher <emphasis>Update Idle</emphasis>
1390       will cause the wave display (position display) and flash-widgets to
1391       update less often. Higher <emphasis>Update Delay</emphasis> values will
1392       cause the parameter widgets to update less often.</para>
1393     </sect2>
1394
1395     <sect2>
1396       <title><emphasis>Misc</emphasis> Tab</title>
1397
1398       <para>You can now enter the soundfile editor of your choice in the
1399       &#34;Sound file editor&#34; field. This editor will be started when
1400       clicking the <emphasis>Edit</emphasis>-button in the main panel of the
1401       vtt-gui. If you enter for example &#34;myeditor&#34; terminatorX will
1402       run &#34;myeditor sample_in_vtt.wav&#34;.</para>
1403     </sect2>
1404   </sect1>
1405
1406   <sect1 id="CONTACT">
1407     <title>Contact / Download</title>
1408
1409     <para>Find out more about terminatorX at it&#39;s <ulink
1410     url="http://www.terminatorX.cx">homepage</ulink>.</para>
1411
1412     <para>Send me comments, bug-reports, patches or scratches (see scratches
1413     section on the terminatorX homepage) at: <email>alex@lisas.de</email></para>
1414   </sect1>
1415 </article>