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