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