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