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