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