f3c92fc96566242ff5dba32d0d826b43b2281edb
[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 software may have <ulink
90       url="http://terminatorX.cx/bugs.html">bugs</ulink> please help fixing
91       them. See <xref linkend="CONTACT" />. Please read this manual and visit
92       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 continuation="restarts" inheritnum="ignore">
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</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</para>
202         </listitem>
203
204         <listitem>
205           <para>Record to disk</para>
206         </listitem>
207
208         <listitem>
209           <para>Save and Load turntable sets (.tX - files)</para>
210         </listitem>
211
212         <listitem>
213           <para>Support for LADSPA plugins.</para>
214         </listitem>
215
216         <listitem>
217           <para>Support for the <emphasis>JACK Audio Connection Kit</emphasis></para>
218         </listitem>
219
220         <listitem>
221           <para>and more</para>
222         </listitem>
223       </itemizedlist>
224     </sect2>
225
226     <sect2 id="REQUIREMENTS">
227       <title>Requirements</title>
228
229       <para>To run terminatorX a system should meet the following
230       requirements:</para>
231
232       <itemizedlist>
233         <listitem>
234           <para>Software</para>
235
236           <itemizedlist>
237             <listitem>
238               <para>required</para>
239
240               <itemizedlist>
241                 <listitem>
242                   <para>Linux, FreeBSD or the like</para>
243                 </listitem>
244
245                 <listitem>
246                   <para>glibc2 (pthreads).</para>
247                 </listitem>
248
249                 <listitem>
250                   <para>XFree86 (with DGA DirectMouse support). Note that
251                   XFree86 Release 4.0 has a bug resulting in broken
252                   DirectMouse support. This has been fixed by the XFree86-Team
253                   with Release 4.0.1 available from your distribution or the
254                   <ulink url="http://www.xfree86.org">XFree86 homepage</ulink>.</para>
255                 </listitem>
256
257                 <listitem>
258                   <para>The Gimp Toolkit: gtk+ (&#62;= 2.0). If your
259                   distribution doesn&#39;t provide a current version of gtk+
260                   get it from the <ulink url="http://www.gtk.org">gtk+
261                   homepage</ulink>.</para>
262                 </listitem>
263
264                 <listitem>
265                   <para>LADSPA - the Linux Audio Developer&#39;s Simple Plugin
266                   API. Get it from the <ulink url="http://www.ladpsa.org">LADSPA
267                   homepage</ulink></para>
268                 </listitem>
269
270                 <listitem>
271                   <para>a compiler (gcc)</para>
272                 </listitem>
273               </itemizedlist>
274             </listitem>
275
276             <listitem>
277               <para>optional (but highly recommended)</para>
278
279               <itemizedlist>
280                 <listitem>
281                   <para><ulink url="http://plugin.org.uk/releases/lrdf/">liblrdf</ulink>
282                   for easier handling of LADSPA plugins</para>
283                 </listitem>
284
285                 <listitem>
286                   <para><ulink url="http://www.mars.org/home/rob/proj/mpeg/">mad</ulink>
287                   for loading mp3 files.</para>
288                 </listitem>
289
290                 <listitem>
291                   <para><ulink url="http://www.xiph.org/ogg/vorbis/">libvorbis</ulink>
292                   for loading ogg files.</para>
293                 </listitem>
294
295                 <listitem>
296                   <para><ulink url="http://jackit.sourceforge.net">libjack</ulink>
297                   for JACK support.</para>
298                 </listitem>
299
300                 <listitem>
301                   <para><ulink url="http://xmlsoft.org/">libxml2</ulink> to
302                   read terminatorX set and rc files</para>
303                 </listitem>
304
305                 <listitem>
306                   <para><ulink url="http://www.gzip.org/zlib/">zlib</ulink> to
307                   create compressed XML set files to save diskspaces</para>
308                 </listitem>
309
310                 <listitem>
311                   <para><ulink url="http://www.68k.org/~michael/audiofile/">libaudiofile</ulink>
312                   for loading misc other audio files.</para>
313                 </listitem>
314
315                 <listitem>
316                   <para><ulink
317                   url="http://www-ti.informatik.uni-tuebingen.de/~hippm/mpg123.html">mpg123</ulink>
318                   for mp3 pre-listening (and fallback loading if mad is not
319                   installed).</para>
320                 </listitem>
321
322                 <listitem>
323                   <para><ulink url="http://www.xiph.org/ogg/vorbis/">ogg123</ulink>
324                   for ogg pre-listening (and fallback loading if libvorbis is
325                   not installed).</para>
326                 </listitem>
327
328                 <listitem>
329                   <para><ulink
330                   url="http://home.sprynet.com/~cbagwell/sox.html">sox</ulink>
331                   for misc files pre-listening (and fallback loading of misc
332                   files).</para>
333                 </listitem>
334               </itemizedlist>
335             </listitem>
336           </itemizedlist>
337         </listitem>
338
339         <listitem>
340           <para>Hardware</para>
341
342           <itemizedlist>
343             <listitem>
344               <para>An <ulink url="http://www.alsa-project.org">ALSA</ulink>
345               or OSS compatible soundcard capable of stereo output.</para>
346             </listitem>
347
348             <listitem>
349               <para>A good clean mouse and pad, a good X-Pointer setup.</para>
350             </listitem>
351           </itemizedlist>
352         </listitem>
353       </itemizedlist>
354
355       <para>A note on performance: terminatorX is known to run satisfyingly on
356       pentium-class systems (or above of course). Increasing the number of
357       turntables or plugins will of course require more performant systems.</para>
358     </sect2>
359
360     <sect2 id="INSTALLATION">
361       <title>Installation</title>
362
363       <para>For GNU-standards&#39; sake this information is now located in the
364       <filename moreinfo="none">INSTALL</filename> file that came with this
365       distribution of terminatorX.</para>
366     </sect2>
367   </sect1>
368
369   <sect1 id="OPERATION">
370     <title>Operation</title>
371
372     <para>TerminatorX&#39; user interface is split up into the main controls
373     (master, sequencer, engine controls and menu buttons) and the individual
374     turntable&#39;s controls. Each turntable has it&#39;s own interface split
375     up into a control and a audio panel (see <xref linkend="TURNTABLECONTROLS" />).</para>
376
377     <sect2 id="MENU">
378       <title>Menu</title>
379
380       <para>To clean-up the user interface a bit further some functions have
381       been moved into a more standard menu bar for the main window (with
382       release 3.80). The following sub-menus are available:</para>
383
384       <sect3 id="FILEMENU">
385         <title><emphasis>File</emphasis> Menu</title>
386
387         <para>The <emphasis>File</emphasis> menu features these functions:</para>
388
389         <itemizedlist>
390           <listitem>
391             <para><emphasis>New</emphasis></para>
392
393             <para>Erases all existing turntables and sequencer events and
394             creates a new and untouched turntable.</para>
395           </listitem>
396
397           <listitem>
398             <para><emphasis>Open</emphasis></para>
399
400             <para>Allows restoring of a previously saved terminatorX set file.</para>
401           </listitem>
402
403           <listitem>
404             <para><emphasis>Save</emphasis></para>
405
406             <para>Saves the current turntables and events in a terminatorX set
407             file.</para>
408           </listitem>
409
410           <listitem>
411             <para><emphasis>Save As</emphasis></para>
412
413             <para>Like <emphasis>Save</emphasis> but prompts for a new file
414             name.</para>
415           </listitem>
416
417           <listitem>
418             <para><emphasis>Quit</emphasis></para>
419           </listitem>
420         </itemizedlist>
421       </sect3>
422
423       <sect3 id="TURNTABLESMENU">
424         <title><emphasis>Turntables</emphasis> Menu</title>
425
426         <para>The <emphasis>Turntables</emphasis> menu features these
427         functions:</para>
428
429         <itemizedlist>
430           <listitem>
431             <para><emphasis>Add Turntable</emphasis></para>
432
433             <para>Adds a new turntable to the current set of turntables.</para>
434           </listitem>
435
436           <listitem>
437             <para><emphasis>Record Audio to Disk</emphasis></para>
438
439             <para>On activation of this option, terminatorX will prompt for a
440             file name for the RIFF/Wave file to create. Once activated
441             terminatorX will start recording audio to disk the next time the
442             audio engine is started - either by pressing the Power or the Play
443             button. Recording will stop when the audio engine is stopped
444             again. The created RIFF/Wave file will be a 16Bit/Stereo wave-file
445             with the sampling rate selected for the current audio backend.</para>
446           </listitem>
447         </itemizedlist>
448       </sect3>
449
450       <sect3 id="SEQUENCERMENU">
451         <title><emphasis>Sequencer</emphasis> Menu</title>
452
453         <para>The <emphasis>Sequencer</emphasis> (see the <xref
454         linkend="SEQUENCER" /> section for general information on the
455         sequencer) menu features these functions:</para>
456
457         <itemizedlist>
458           <listitem>
459             <para><emphasis>Delete All</emphasis> submenus</para>
460
461             <para>These submenus allow you to delete sequencer events of a
462             specific parameter or all events for a complete turntable. After
463             selecting the the parameter/turntable of your choice a dialog will
464             pop-up that allows you to delete all events from either:</para>
465
466             <itemizedlist>
467               <listitem>
468                 <para>the beginning of the song upto the current song position</para>
469               </listitem>
470
471               <listitem>
472                 <para>the current song position upto the end of the song</para>
473               </listitem>
474
475               <listitem>
476                 <para>the beginning to the end of the song (all events)</para>
477               </listitem>
478             </itemizedlist>
479           </listitem>
480
481           <listitem>
482             <para><emphasis>Delete All Events</emphasis></para>
483
484             <para>Works the same as the <emphasis>Delete All</emphasis>
485             submenus but selects <emphasis>all</emphasis> events for
486             <emphasis>all</emphasis> turntables.</para>
487           </listitem>
488
489           <listitem>
490             <para><emphasis>Confirm Recorded Events</emphasis></para>
491
492             <para>Usually terminatorX will add all recorded events of a take
493             to the song event list as soon as you hit the
494             <emphasis>Stop</emphasis> button for the sequencer. If you enable
495             <emphasis>Confirm Recorded Events</emphasis> terminatorX will ask
496             you whether the recorded events should really be fed into the song
497             list. This makes it much easier to record a certain part over and
498             over again until you get it right.</para>
499           </listitem>
500         </itemizedlist>
501       </sect3>
502
503       <sect3 id="OPTIONSMENU">
504         <title><emphasis>Options</emphasis> Menu</title>
505
506         <para>The <emphasis>Options</emphasis> menu features these functions:</para>
507
508         <itemizedlist>
509           <listitem>
510             <para><emphasis>Fullscreen</emphasis></para>
511
512             <para>Maximizes the terminatorX main windows to use the complete
513             screen. Note that this requires a NETWM compliant window manager
514             to work. By toggling this option again terminatorX&#39; window can
515             be resized back to the previous state again. The setting will be
516             stored in the <filename>~/.terminatorXrc</filename> file.</para>
517           </listitem>
518
519           <listitem>
520             <para><emphasis>Preferences</emphasis></para>
521
522             <para>Will pop up the Preferences dialog. For more details on
523             configuration itself see <xref linkend="CONFIGURATION" />.</para>
524           </listitem>
525         </itemizedlist>
526       </sect3>
527
528       <sect3 id="HELPMENU">
529         <title><emphasis>Help</emphasis> Menu</title>
530
531         <para>The <emphasis>Help</emphasis> menu features these functions:</para>
532
533         <itemizedlist>
534           <listitem>
535             <para><emphasis>Contents</emphasis></para>
536
537             <para>Starts a <emphasis>gnome-help</emphasis> (aka
538             <emphasis>yelp</emphasis>) process to display the very manual you
539             are reading right now.</para>
540           </listitem>
541
542           <listitem>
543             <para><emphasis>About</emphasis></para>
544
545             <para>Selecting this menu item will cause a small dialog to pop up
546             that contains some information on the compile time settings for
547             the terminatorX binary as well as the license.</para>
548           </listitem>
549
550           <listitem>
551             <para><emphasis>Visit terminatorX.cx</emphasis></para>
552
553             <para>Will try to spawn a browser process to load the URL
554             &#34;http://terminatorX.cx&#34; - for easy update checking or just
555             unecessary bloat.</para>
556           </listitem>
557         </itemizedlist>
558       </sect3>
559     </sect2>
560
561     <sect2 id="MAINCONTROLS">
562       <title>Main Controls</title>
563
564       <para>The controls of the master GUI are located in the top and the
565       right bar of the terminatorX main window.</para>
566
567       <itemizedlist>
568         <listitem>
569           <para><emphasis>Audio Engine Power / Mouse Grab</emphasis></para>
570
571           <para>With the Audio Engine Button you can en- and disable the audio
572           playback engine without activating the sequencer. Unlike earlier
573           versions you will not automatically enter mouse-grab mode so you can
574           modify volume/pitch/echo settings etc. while you actually hear what
575           you do.</para>
576
577           <para>Some functions are not available when the audio engine is on,
578           their controls will be marked insensitive when you enable the
579           engine. To actually enter grab mode you&#39;ll have to click on the
580           &#34;Mouse Grab&#34; button. See <xref linkend="GRABMODE" /> to find
581           out how to control the software then.</para>
582         </listitem>
583
584         <listitem>
585           <para><emphasis>Sequencer Play / Record / Stop</emphasis></para>
586
587           <para>Please read the <xref linkend="SEQUENCER" /> section to find
588           out more about the sequencer.</para>
589         </listitem>
590
591         <listitem>
592           <para><emphasis>Master Volume / Pitch</emphasis></para>
593
594           <para>The volume and pitch settings of the individual turntables are
595           relative to these master settings. This information will be stored
596           within the .tX set files.</para>
597         </listitem>
598       </itemizedlist>
599     </sect2>
600
601     <sect2 id="TURNTABLECONTROLS">
602       <title>Turntable Controls</title>
603
604       <para>The turntable GUI contains multiple controls and the real time
605       displays for each turntable. To save some space on your desktop and to
606       give terminatorX the traditional audio-application look, terminatorX
607       features &#34;knob&#34;-widgets. These widgets work pretty
608       straight-forward: click somewhere within the widget and keep the left
609       mouse-button pressed. Now move the mouse up and down or left and right
610       to increase/decrease the control&#39;s value. All those widget are
611       coupled with a text entry field since 3.70, which allows you to enter
612       values directly.</para>
613
614       <para>A turntable is visualized by two panels: the control and the audio
615       panel. These are no longer combined for better layout management.</para>
616
617       <para>Sometimes you might find a certain audio or control panel
618       unnecessary - simply eating up space. Since release 3.73 it is possible
619       to minimize audio and control panels to the <emphasis>panel bar</emphasis>
620       with the tiny button with a blue bar icon in the upper right edge of
621       each panel. This bar works just like GNOME&#39;s window list or
622       KDE&#39;s kicker: When a panel is minimized a button in the bar will
623       appear, representing the minimized window. On clicking this button the
624       button will be removed and the minimized panel is displayed again. When
625       no panels are minimized the panel bar automatically disappears to save
626       display space.</para>
627
628       <sect3>
629         <title>Turntable Audio Panel</title>
630
631         <para>The complete audio-file loaded into a turntable is displayed in
632         the green-on-black audio-widget. When playing terminatorX will
633         indicate the current position within the sample with a red cursor (a
634         blue/green cursor indicates the turntable is muted).</para>
635
636         <para>Additionally there are some controls above the audio-display:</para>
637
638         <itemizedlist>
639           <listitem>
640             <para><emphasis>Turntable Label</emphasis></para>
641
642             <para>This label indicates the turntables name. The name can be
643             set via the control panel</para>
644           </listitem>
645
646           <listitem>
647             <para><emphasis>File Button</emphasis></para>
648
649             <para>This button holds the name of the audio-file currently
650             loaded. When there&#39;s no sample loaded the button will read
651             &#34;NONE&#34; to indicate the current status. Click on this
652             button to get a menu from which you can load/reload a sound file
653             or run an external soundfile editor. Alternatively you can
654             drag&#39;n&#39;drop files over the audio-display to load them.</para>
655
656             <itemizedlist>
657               <title>The File Button Menu</title>
658
659               <listitem>
660                 <para><emphasis>Load File</emphasis></para>
661
662                 <para>Choose this menu entry to select a soundfile from the
663                 file-selection dialog that will pop-up.</para>
664               </listitem>
665
666               <listitem>
667                 <para><emphasis>Reload File</emphasis></para>
668
669                 <para>Choose this menu entry to re-read the audio-file.</para>
670               </listitem>
671
672               <listitem>
673                 <para><emphasis>Edit File</emphasis></para>
674
675                 <para>This menu entry will run the external audiofile-editor
676                 (that can be specified via the options-dialog) with the
677                 current audio-file as a parameter. Choose reload after editing
678                 and saving the file.</para>
679               </listitem>
680             </itemizedlist>
681           </listitem>
682
683           <listitem>
684             <para><emphasis>Mouse Mapping</emphasis></para>
685
686             <para>terminatorX allows mapping misc parameters to the mouse axis
687             of your choice. These mappings will be activated in grab mode, so
688             if you move your mouse in X or Y direction in grab mode the
689             parameters you selected from this menu will be affected (for this
690             turntable). Since Version 3.70 this mappings are no longer
691             hardcoded to built-in controls but available for all parameters
692             that qualify as &#34;mappable&#34;. Note that this includes
693             plugins&#39; controls as well.</para>
694           </listitem>
695
696           <listitem>
697             <para><emphasis>MIDI Mapping</emphasis></para>
698
699             <para>This button is available only if terminatorX was built with
700             ALSA MIDI support and the sequencer input port was created
701             successfully on startup. For more information on terminatorX&#39;
702             MIDI interface see <xref linkend="MIDI" /> section.</para>
703           </listitem>
704         </itemizedlist>
705       </sect3>
706
707       <sect3>
708         <title>Turntable Controls</title>
709
710         <para>These controls are now grouped within functional panels. The
711         number of panels depends on the number of plugins loaded. terminatorX
712         allows hiding the controls not required via the yellow triangle
713         button. To un-hide just click the button again. The first panels are
714         the standard controls for a turntable, then follows the dynamic
715         FX-section and below that follow the pitch and volume controls.</para>
716
717         <sect4>
718           <title>Main Panel</title>
719
720           <itemizedlist>
721             <listitem>
722               <para><emphasis>Name Field</emphasis></para>
723
724               <para>The main panel features a text entry field that allows
725               setting a name for the related turntable. The Labels for the
726               controls and the audio-display will update accordingly.</para>
727             </listitem>
728
729             <listitem>
730               <para><emphasis>Delete Button</emphasis></para>
731
732               <para>Pressing this button remove the turntable from the current
733               setup. Note that all sequencer events recorded for this
734               turntable will be erased, too.</para>
735             </listitem>
736
737             <listitem>
738               <para><emphasis>Pitch Adj. Button</emphasis></para>
739
740               <para>Using two (or more) loops and terminatorX&#39;
741               synchronization facility usually requires adjusting the pitch of
742               the loops so that the turntables play in sync. For precisely cut
743               loops this usually means making them run equally fast or one
744               running twice as fast as the other etc. Manually finding the
745               necessary pitch values usually consumes a significant amount of
746               time so the feature <emphasis>Pitch Adjust</emphasis> helps
747               speeding up this process.</para>
748
749               <para>Clicking this button will cause the <emphasis>Compute
750               Pitch</emphasis> dialog to pop up. With this dialog it is
751               possible to specify how many loops of this turntable should be
752               played as fast as a certain amount of loops of the master
753               turntable. After pressing the <emphasis>Ok</emphasis> button
754               terminatorX will adjust the turntable&#39;s ptich accordingly in
755               order to match the given playback speed requirements.</para>
756
757               <para>Note that this feature is proabably useless when loading
758               complete songs into terminatorX - it&#39;s intended for use with
759               precisely cut loops.</para>
760             </listitem>
761           </itemizedlist>
762         </sect4>
763
764         <sect4>
765           <title>Trigger Panel</title>
766
767           <para>The trigger panel holds all controls related to triggering the
768           turntable. For more details on synchronization see <xref
769           linkend="SYNCHRONIZATION" />.</para>
770
771           <itemizedlist>
772             <listitem>
773               <para><emphasis>Trigger! Button</emphasis></para>
774
775               <para>Pressing this button triggers the turntable now. With the
776               audio engine enabled this will cause the turntable to start
777               playing back audio from the beginning of the sample.</para>
778             </listitem>
779
780             <listitem>
781               <para><emphasis>Stop Button</emphasis></para>
782
783               <para>Guess what, this stops this turntable&#39;s
784               audio-playback.</para>
785             </listitem>
786
787             <listitem>
788               <para><emphasis>Master Button</emphasis></para>
789
790               <para>Enabling this button makes this turntable the
791               <emphasis>sync-master</emphasis>. Note that only
792               <emphasis>one</emphasis> turntable at a time can be the
793               sync-master.</para>
794             </listitem>
795
796             <listitem>
797               <para><emphasis>Client Button</emphasis></para>
798
799               <para>This button marks the turntable as <emphasis>sync-client</emphasis>,
800               so it will be triggered with the master automatically.</para>
801             </listitem>
802
803             <listitem>
804               <para><emphasis>Sync-Cycles Selection</emphasis></para>
805
806               <para>The sync cycles determine how often a sync-client should
807               be triggered. With a setting of zero the sync-client will be
808               (re-)triggered with <emphasis>every</emphasis> trigger of the
809               sync-master. A setting of 1 will (re-)trigger the client every
810               <emphasis>second</emphasis> master-trigger and so on.</para>
811             </listitem>
812           </itemizedlist>
813
814           <para>Below the effect queue a turntable shows some more controls:
815           <itemizedlist><listitem><para><emphasis>Pitch Control</emphasis></para><para>The
816           pitch control allows setting the default playback speed for that
817           turntable (the &#34;motor&#34; speed). Negative values will result
818           in the sample being played backwards.</para></listitem><listitem><para><emphasis>PAN
819           Control</emphasis></para><para>This parameter allows setting the
820           position of the turntable&#39;s main signal within the stereo
821           panorama.</para></listitem><listitem><para><emphasis>VU Meter</emphasis></para><para>The
822           displayed signal shows the turntable&#39;s current signal not
823           including the echo-signal which is mixed separately.</para></listitem></itemizedlist></para>
824         </sect4>
825       </sect3>
826
827       <sect3 id="PARAMETERMENU">
828         <title>Parameter Menu</title>
829
830         <para>TerminatorX can record events for nearly all parameters of a
831         turntable. All of these so-called &#34;sequencable&#34; parameters
832         have an extra pop-up menu since Version 3.81. Simply right-click on
833         the knob, button, slider of the parameter you want to setup, and a
834         menu with the following options will appear:<itemizedlist><listitem><para><emphasis>MIDI
835         Learn</emphasis></para><para>This options provides an easy method to
836         select the MIDI control to modify the parameter you select. If you
837         choose this menu entry, a tiny dialog box will pop up that reads
838         <emphasis>&#34;Waiting for MIDI Event...&#34;</emphasis>. The first
839         MIDI event terminatorX receives will now be mapped to control this
840         parameter.</para></listitem><listitem><para><emphasis>Remove MIDI
841         Binding</emphasis></para><para>If a MIDI event has been bound to a
842         parameter it can be removed by selecting this menu entry.</para></listitem><listitem><para><emphasis>Set
843         Upper MIDI Bound</emphasis></para><para>Sometimes it is preferable to
844         modify a certain parameter only within a specific value range - this
845         can be achieved with this option - by setting an upper and a lower
846         bound for the MIDI control of this parameter. When you select this
847         menu entry, the current setting of this parameter will be used as the
848         upper bound for the parameter&#39;s MIDI mapping.</para></listitem><listitem><para><emphasis>Reset
849         Upper MIDI Bound</emphasis></para><para>If an upper MIDI bound was set
850         for this parameter it can be removed by selecting this menu entry.</para></listitem><listitem><para><emphasis>Set
851         Lower MIDI Bound</emphasis></para><para>Works just like setting the
852         uper MIDI bound: when you select this menu entry, the current setting
853         of this parameter will be used as the lower bound for the
854         parameter&#39;s MIDI mapping.</para></listitem><listitem><para><emphasis>Reset
855         Lower MIDI Bound</emphasis></para><para>If a lower MIDI bound was set
856         for this parameter it can be removed by selecting this menu entry.</para></listitem><listitem><para><emphasis>Delete
857         Sequencer Events</emphasis></para><para>Just like the <xref
858         linkend="SEQUENCERMENU" /> this entry allows you to delete events
859         recorded for this specific parameter.</para></listitem></itemizedlist></para>
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 fileref="figures/signalflow.png" format="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" />.</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 see <xref
1264       linkend="SEQUENCERMENU" /> and <xref linkend="PARAMETERMENU" />.</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. If the &#34;<emphasis>Restore MIDI Connections</emphasis>&#34;
1359       option is activated terminatorX will try to re-connect to the MIDI ports
1360       it was connected to with the last run. However this approach is purely
1361       address-based and might fail miserably with software ports, in this case
1362       just disable the configuration options re-wire manually.</para>
1363
1364       <para>There are two ways to map MIDI events to a parameter:<itemizedlist><listitem><para>Via
1365       the <emphasis>Configure MIDI Bindings</emphasis> dialog as described
1366       below</para></listitem><listitem><para>Via the the a parameter&#39;s
1367       menu (see <xref linkend="PARAMETERMENU" />) </para></listitem></itemizedlist></para>
1368
1369       <para>Once the connection is set up terminatorX receives MIDI events
1370       through the input port. To configure what MIDI events will have which
1371       effect on a terminatorX turntable you can bind MIDI events to parameters
1372       of your choice by clicking the <emphasis>MIDI</emphasis> button of the
1373       turntable&#39;s audio panel. As a result the <emphasis>Configure MIDI
1374       Bindings</emphasis> dialog will pop up which features a field labelled
1375       <emphasis>Selected MIDI Event</emphasis> that will frequently update to
1376       display the contents of the last MIDI event received by terminatorX. So
1377       in order to map a MIDI controller to a specific turntable parameter
1378       select the parameter of your choice from the parameter list, cause your
1379       MIDI event sending device to emit the event you want to map the
1380       parameter on and click the <emphasis>Bind</emphasis> button.</para>
1381
1382       <para>Immediately after binding the event you should see that the
1383       <emphasis>Event</emphasis> column entry of the selected parameter is
1384       updated to match the selected event. From now on all events matching the
1385       selected event will cause the turntable parameter to be updated. The GUI
1386       for that parameter will be refreshed accordingly. Note that it is
1387       possible to map the same event to multiple parameters.</para>
1388
1389       <para>The MIDI mappings are stored within terminatorX set files so you
1390       wont have to reconfigure your bindings every time you start up
1391       terminatorX. If you are unhappy with a chosen binding you can select the
1392       parameter and click the <emphasis>Remove Binding</emphasis> button to
1393       get rid of the parameter&#39;s MIDI mapping.</para>
1394
1395       <para>If you want to use your joystick to control terminatorX - I wrote
1396       a tiny tool to create MIDI events from joystick motion called
1397       <emphasis>aseqjoy</emphasis>. It&#39;s available from the <ulink
1398       url="http://terminatorX.cx/aseqjoy.html">terminatorX website</ulink>,
1399       too.</para>
1400     </sect2>
1401
1402     <sect2 id="JACKSUPPORT">
1403       <title>JACK Support</title>
1404
1405       <para>TerminatorX Version 3.81 brings support for the
1406       <emphasis>JACK Audio Connection Kit</emphasis>. Instead of writing audio
1407       data directly to some audio device terminatorX can send data to the JACK
1408       Daemon for further processing.</para>
1409
1410       <para>To use the JACK backend you have to ensure that the JACK Daemon is
1411       up and running before you start terminatorX. The JACK backend is only
1412       available if terminatorX was capable of connecting to the JACK Daemon on
1413       startup. By default the two output ports of terminatorX will be
1414       connected to physical ports if available. You can then re-wire the ports
1415       whatever way you want. They will not be deactivated - when
1416       terminatorX&#39; audio engine is turned off , the audio backend emits
1417       continuous silence.</para>
1418     </sect2>
1419   </sect1>
1420
1421   <sect1 id="CONFIGURATION">
1422     <title>Configuration</title>
1423
1424     <para>The main terminatorX configuration parameters can be set up via the
1425     <emphasis>Preferences</emphasis> dialog, which can be activated from the
1426     terminatorX menu. The new <emphasis>Preferences</emphasis> dialog features
1427     multiple tabs for several aspects of configuration.</para>
1428
1429     <para>A word on the settings in general: your settings are stored in an
1430     XML file ( <filename moreinfo="none">~/.terminatorXrc).</filename> So if
1431     you think you completely messed up your settings you will have to exit
1432     terminatorX - delete this file - and then re-run terminatorX with the
1433     default settings. Note: is this file is now an XML file you can edit with
1434     an editor of your choice.</para>
1435
1436     <sect2 id="AUDIOTAB">
1437       <title><emphasis>Audio</emphasis> Tab</title>
1438
1439       <para>This tab allows to select which audio backend terminatorX should
1440       use. Currently there are three options: the OSS (Open Sound System)
1441       backend, the ALSA (Advanced Linux Sound Architecture) backend and the
1442       JACK (JACK Audio Connection Kit) backend. Some of these options might
1443       not be available, if your terminatorX binary wasn&#39;t compiled to
1444       support a certain backend.</para>
1445
1446       <para>The OSS and ALSA backends have dedicated configuration tabs, JACK
1447       requires no further configuration - for more details on JACK support see
1448       <xref linkend="JACKSUPPORT" />.</para>
1449     </sect2>
1450
1451     <sect2 id="OSSTAB">
1452       <title><emphasis>Audio: OSS</emphasis> Tab</title>
1453
1454       <para>Select the audio device you are going to use from the available
1455       options (or simply enter one yourself). terminatorX renders audio
1456       block-wise. In order to achieve close-to-realtime performance it is
1457       necessary to keep this blocks as small as possible. The main parameters
1458       that determine how close-to-realtime terminatorX will perform are
1459       <emphasis>No. of Buffers</emphasis> and <emphasis>Buffersize</emphasis>.
1460       The <emphasis>No. of Buffers</emphasis> parameter determines how many
1461       buffers the audio driver should use in most cases <emphasis>2</emphasis>
1462       should be the best setting and in rare cases <emphasis>3</emphasis>
1463       might give better results.</para>
1464
1465       <para>The value for the <emphasis>Buffersize</emphasis> setting will be
1466       evaluated as 2^buffersize by OSS. So if you set the value to
1467       <emphasis>8</emphasis> the actual buffer size will be 2^8=256 Bytes. The
1468       smaller the buffers&#39; size the better terminatorX will perform. The
1469       default setting of <emphasis>9</emphasis> should be acceptable in most
1470       conditions, but if you here &#34;clicks&#34;, or &#34;drops&#34; in
1471       audio output that are not related to your sample-material you will have
1472       to increase the buffer size. On the other hand if you believe
1473       terminatorX does not react fast enough you have to decrease this
1474       parameter.</para>
1475
1476       <para>Additionally you can select the sampling rate you want terminatorX
1477       to operate on - note that recording to disk will use the same sample
1478       rate.</para>
1479     </sect2>
1480
1481     <sect2 id="ALSATAB">
1482       <title><emphasis>Audio: ALSA</emphasis> Tab</title>
1483
1484       <para>Using ALSA for audio output allows specifing the buffer sizes in
1485       microseconds. ALSA uses a ring-buffer to process audio. The
1486       <emphasis>Buffer Time</emphasis> option lets you set the size for the
1487       complete ring buffer, while the <emphasis>Period Time</emphasis>
1488       determines how many audio samples will be transferred to the audio
1489       device per cycle. I&#39;m not really sure on what kind of settings to
1490       recommend, however I had best results when setting the
1491       <emphasis>Period Time</emphasis> to 3rd or half of the
1492       <emphasis>Buffer Time</emphasis>.</para>
1493
1494       <para>It&#39;s advisable to set the <emphasis>Buffer Time</emphasis> to
1495       at least the double of the <emphasis>Period Time</emphasis>, but for a
1496       more detailed description check out the ALSA documentation.</para>
1497     </sect2>
1498
1499     <sect2 id="INPUTTAB">
1500       <title><emphasis>Input</emphasis> Tab</title>
1501
1502       <para>Between rendering and outputting these blocks terminatorX checks
1503       for mouse motion. The problem with mice is: they don&#39;t report when
1504       they have stopped. This is why terminatorX assumes your mouse has
1505       stopped if there is no motion reported for certain amount of
1506       render/output-cycles. This value is configurable via the
1507       <emphasis>Stop-sense-cycles</emphasis> option. If you decrease your
1508       buffersize of course you shorten the cycle time as well, therefore if
1509       you here strange stop/run behaviour of the audio output while scratching
1510       after you decreased the buffer size you might have to increase the
1511       stop-sense value too.</para>
1512
1513       <para>XInput Device: <emphasis>WARNING:</emphasis> Use this option
1514       *only* if you want to use an input device other than your default-mouse
1515       for scratching. Selecting your default pointer will cause terminatorX to
1516       crash. See the &#34;Using a turntable&#34; section on the terminatorX
1517       homepage for details.</para>
1518     </sect2>
1519
1520     <sect2 id="USERINTERFACETAB">
1521       <title><emphasis>User Interface</emphasis> Tab</title>
1522
1523       <para>With <emphasis>Update Idle</emphasis> / <emphasis>Update Delay</emphasis>
1524       you can configure GUI responsiveness: Higher <emphasis>Update Idle</emphasis>
1525       will cause the wave display (position display) and flash-widgets to
1526       update less often. Higher <emphasis>Update Delay</emphasis> values will
1527       cause the parameter widgets to update less often.</para>
1528     </sect2>
1529
1530     <sect2>
1531       <title><emphasis>Audio Colors</emphasis> and <emphasis>VU Colors</emphasis>
1532       Tab</title>
1533
1534       <para>Since Version 3.81 it is possible to configure the colors
1535       terminatorX&#39; audio widgets. Simply click on the color you want to
1536       modify and select the tone you prefer.</para>
1537     </sect2>
1538
1539     <sect2 id="MISCTAB">
1540       <title><emphasis>Misc</emphasis> Tab</title>
1541
1542       <para>You can now enter the soundfile editor of your choice in the
1543       &#34;Sound file editor&#34; field. This editor will be started when
1544       clicking the <emphasis>Edit</emphasis>-button in the main panel of the
1545       vtt-gui. If you enter for example &#34;myeditor&#34; terminatorX will
1546       run &#34;myeditor sample_in_vtt.wav&#34;.</para>
1547
1548       <para>The <emphasis>LADSPA RDF Path</emphasis> defines where liblrdf
1549       will look for the RDF files for LADPSA Plugins.</para>
1550
1551       <para>If <emphasis>Compress set files</emphasis> is activated
1552       terminatorX will use zlib to compress set files. This is very usefull
1553       for sets that have many events recorded.</para>
1554
1555       <para>See <xref linkend="MIDI" /> for more details on
1556       <emphasis>Restore MIDI Connections</emphasis>. If you disable the
1557       <emphasis>Ask for &#34;Quit&#34; Confirmation</emphasis> option
1558       terminatorX will no longer ask if you really want to quit.</para>
1559     </sect2>
1560   </sect1>
1561
1562   <sect1 id="CONTACT">
1563     <title>Contact / Download</title>
1564
1565     <para>Find out more about terminatorX at it&#39;s <ulink
1566     url="http://www.terminatorX.cx">homepage</ulink>.</para>
1567
1568     <para>Send me comments, bug-reports, patches or scratches (see scratches
1569     section on the terminatorX homepage) at: <email>alex@lisas.de</email></para>
1570   </sect1>
1571 </article>