On the way to OMF - Alex
[terminatorX.git] / doc / terminatorX-manual / C / terminatorX-manual.xml
1 <?xml version="1.0"?>
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   <!ENTITY GFDL SYSTEM "fdl-appendix.xml">
6   <!ENTITY appversion "0.3.5">
7   <!ENTITY manrevision "0.1.1">
8   <!ENTITY date "March 18, 2002">
9   <!-- Information about the entities
10        The legal.xml file contains legal information, there is no need to edit the file.
11        Use the appversion entity to specify the version of the application.
12        Use the manrevision entity to specify the revision number of this manual.
13        Use the date entity to specify the release date of this manual.
14        Use the app entity to specify the name of the application. -->
15 ]>
16 <article id="index" lang="en">
17   <articleinfo>
18     <title>terminatorX - Manual</title>
19     <author><firstname>Alexander</firstname>
20       <surname>K&ouml;nig</surname></author>
21     <copyright><year>1999 - 2002</year>
22       <holder ROLE="mailto:alex@rhlx01.fht-esslingen.de">Alexander K&ouml;nig</holder></copyright>
23     <releaseinfo>Version 3.73</releaseinfo></articleinfo>
24   <preface id="preface">
25     <title>Preface</title>
26     <para>This is free software see the
27       <filename moreinfo="NONE">COPYING</filename>
28       file that came with this distribution for details.</para>
29     <para><emphasis>Warning:</emphasis> TerminatorX comes with
30       <emphasis>ABSOLUTELY NO WARRANTY</emphasis>. This software is
31       known o lockup X11 or cause other problems under rare conditions. Don't
32       use it on production servers. You have been
33       warned!</para></preface>
34
35   <section id="INTRODUCTION"><title>Introduction</title>
36     <section id="WHATITIS"><title>What it is</title>
37       <para><application moreinfo="NONE">terminatorX</application> is a
38         realtime audio synthesizer that allows you to "scratch" on
39         digitally sampled audio data (*.wav, *.au, *.mp3, *.ogg etc.)
40         the way hiphop-DJs scratch on vinyl records. It features
41         multiple turntables, realtime effects (built-in as well as
42         LADSPA plugin effects), a sequencer and an easy-to-use gtk+
43         GUI.</para>
44
45       <para>This is <emphasis>beta</emphasis> Software please help me
46         fix bugs. See <xref linkend="CONTACT"/>
47         (Contact/Download). Please read this manual and take a look at
48         the
49         <ulink url="http://www.terminatorX.cx">homepage</ulink>.
50       </para></section>
51
52     <section id="QUICKSTART"><title>Quickstart</title>
53       <orderedlist CONTINUATION="RESTARTS"
54                    INHERITNUM="IGNORE"><listitem><para>If you don't have
55             <application moreinfo="NONE">LADSPA</application> (Linux
56             Audio Developer's Simple Plugin API) installed, go and get
57             it from the 
58             <ulink url="http://www.ladspa.org">LADSPA-homepage</ulink>
59             and install the SDK. terminatorX requires 
60             <filename moreinfo="NONE">ladspa.h</filename>.</para></listitem>
61         <listitem><para>Install terminatorX (see 
62             <filename moreinfo="NONE">INSTALL</filename>)</para></listitem>
63         <listitem><para>Run terminatorX</para></listitem>
64         <listitem><para>Load an audiofile into the available turntable
65             (you can add more turntables if you want) (Hint: Click on
66             the button that holds "NONE" to load an audiofile, or drop
67             one over the audiofile display from your filemanager if your
68             filemanager is efm, gmc, Nautilus or compatible (kfm does
69             <emphasis>not</emphasis> work))</para></listitem>
70         <listitem>
71           <para>Load a LADSPA plugin of your choice by clicking the
72             turntable's <emphasis>FX</emphasis> button and enable it.
73           </para>
74         </listitem>
75
76         <listitem><para>Click on the "Audio Engine"-button to start
77             playback.</para></listitem>
78
79         <listitem><para>Click on the "Mouse-Grab"-button to enter grab
80             mode. The turntable with the red border has the input
81             focus.</para></listitem>
82
83         <listitem><para>Press <keycap moreinfo="NONE">SPACE</keycap> or
84             left mouse button to scratch.</para></listitem>
85
86         <listitem><para>Release <keycap moreinfo="NONE">SPACE</keycap>  or left mouse button to let the scratch-file run at the turntable's default speed.</para></listitem>
87         <listitem><para>Press <keycap moreinfo="NONE">ESCAPE</keycap> to
88             quit grab mode.</para></listitem></orderedlist></section>
89
90     <section id="FEATURES"><title>Features</title>
91       <itemizedlist><listitem><para>Scratching ;)</para></listitem>
92         <listitem><para>Multiple turntables</para></listitem>
93         <listitem><para>Built-in Sequencer</para></listitem>
94         <listitem><para>Pitch / Volume settings for each turntable</para></listitem>
95         <listitem><para>Effects (Lowpass/Echo) configurable for each turntable</para></listitem>
96         <listitem><para>Syncing tables to one master turntable</para></listitem>
97         <listitem><para>Broad audiofile-type support through the use of sox and mpg123</para></listitem>
98         <listitem><para>Recording (straight to disk now)</para></listitem>
99         <listitem><para>Save turntable sets (.tX - files)</para></listitem>
100         <listitem><para>Support for the LADSPA-plugin-standard.</para></listitem>
101         <listitem><para>and more</para></listitem></itemizedlist></section>
102     <section id="REQUIREMENTS"><title>Requirements</title>
103       <itemizedlist><listitem><para>Software</para>
104           <itemizedlist><listitem><para>required</para>
105               <itemizedlist><listitem><para>The Linux Operating System (Version &gt;=
106                     2.0) or FreeBSD</para></listitem>
107                 <listitem><para>glibc2 (pthreads).</para></listitem>
108                 <listitem><para>XFree86 (with DGA DirectMouse
109                     support). Note that XFree86 Release 4.0 has a bug
110                     resulting in broken DirectMouse support. This has
111                     been fixed by the XFree86-Team with Release 4.0.1
112                     available from your distribution or the 
113                     <ulink url="http://www.xfree86.org">XFree86
114                       homepage</ulink>.
115                   </para></listitem>
116                 <listitem><para>The Gimp Toolkit: gtk+ (>= 1.2.5) - Version 2 of gtk+ is
117                     supported, too. If your distribution doesn't provide
118                     a current version of gtk+ get it from the 
119                     <ulink url="http://www.gtk.org">gtk+
120                       homepage</ulink>.
121                   </para></listitem>
122                 <listitem><para>LADSPA - the Linux Audio Developer's
123                     Simple Plugin API. Get it from the
124                     <ulink url="http://www.ladpsa.org">LADSPA homepage</ulink>
125                   </para></listitem>
126                 <listitem><para>a compiler
127                     (gcc)</para></listitem></itemizedlist></listitem>
128             <listitem><para>optional</para>
129               <itemizedlist><listitem><para>
130                     <ulink url="http://home.sprynet.com/~cbagwell/sox.html">sox</ulink>
131                     for enhanced audio file support</para></listitem>
132                 <listitem><para>
133                     <ulink url="http://www-ti.informatik.uni-tuebingen.de/~hippm/mpg123.html">mpg123</ulink>
134                     for mp3 support</para></listitem>
135                 <listitem><para>
136                     <ulink url="http://www.xiph.org/ogg/vorbis/">ogg123</ulink>
137                     for Ogg Vorbis support</para></listitem>
138
139               </itemizedlist></listitem></itemizedlist></listitem>
140         <listitem><para>Hardware</para>
141           <itemizedlist><listitem><para>An OSS compatible soundcard
142                 capable of stereo output. This includes
143                 <emphasis>all</emphasis> 
144                 <ulink url="http://www.alsa-project.org">ALSA-driven</ulink> 
145                 soundcards as this enhanced audio device interface includes support for
146                 the OSS API.</para></listitem>
147
148             <listitem><para>A good clean mouse and pad, a good X-Pointer
149                 setup.</para></listitem></itemizedlist></listitem></itemizedlist>
150
151       <para>A note on performance: terminatorX is known to run
152         satisfyingly on pentium-class systems (or above of
153         course). Increasing the number of turntables or plugins will of
154         course require more performant systems.</para></section>
155
156     <section id="INSTALLATION"><title>Installation</title>
157       <para>For GNU-standards' sake this information is now located in
158         the <filename moreinfo="NONE">INSTALL</filename> file that came
159         with this distribution of
160         terminatorX.</para></section></section>
161
162   <section id="OPERATION"><title>Operation</title>
163     <para>With Release Version 3.70 the terminatorX has undergone some
164       redesign again. It's split up in the main controls (master,
165       sequencer, engine controls and menu buttons) and the individual
166       turntable's controls. Each turntable has it's own GUI split up
167       into control and audio panel.</para>
168
169     <section id="MAINCONTROLS"><title>Main Controls</title>
170       <para>The controls of the master gui are located in the top and
171         the right bar of the terminatorX main window.</para>
172       <itemizedlist><listitem><para><emphasis>Audio Engine Power / Mouse
173               Grab</emphasis></para>
174
175           <para>With the Audio Engine Button you can en- and disable the
176             audio playback engine without activating the
177             sequencer. Unlike earlier versions you will not
178             automatically enter mouse-grab mode so you can modify
179             volume/pitch/echo settings etc. while you actually hear what
180             you do. </para>
181
182           <para>Some functions are not available when the audio engine is on, their controls will be marked insensitive when you enable the engine. To actually enter grab mode you'll have to click on the "Mouse Grab" button. See <xref linkend="GRABMODE"/> (Grab Mode Operation) to find out how to control the software then.</para></listitem>
183         <listitem><para><emphasis>Record (Audio
184               Engine)</emphasis></para>
185
186           <para>To enable recording you have to enable the "Record"-toggle button BEFORE you 
187             start the audio engine. You will be prompted for a filename after enabling the
188             button. Audio will then be recorded to that file in stereo
189             RIFF/WAV format from the moment you turn the audio engine on
190             until you turn it off again. Please be aware of the fact
191             that recording audio requires <emphasis>a lot</emphasis> of
192             harddisk space!</para></listitem>
193
194         <listitem><para><emphasis>Sequencer Play / Record / Stop</emphasis></para>
195           <para>Please read the Sequencer-Section to find out more about
196             the sequencer.</para></listitem>
197
198         <listitem><para><emphasis>Master Volume /
199               Pitch</emphasis></para>
200
201           <para>The volume and pitch settings of the individual
202             turntables are relative to these master settings. This
203             information will be stored within the .tX set
204             files.</para></listitem>
205
206         <listitem><para><emphasis>Add Turntable</emphasis></para>
207           <para>Oh well, it says it all: adds a (new) turntable to the
208             current set.</para></listitem>
209
210         <listitem><para><emphasis>Save Set</emphasis></para>
211           <para>With this button you can save your current set and all related settings to a 
212             .tX set file. Note that the audiofiles themselves will not be stored within
213             these files but only references to them. Therefore on loading the set the 
214             audiofiles have to be at the same location in the filesystem as they were when
215             putting that set together.</para></listitem>
216         <listitem><para><emphasis>Load Set</emphasis></para>
217           <para>Loads a previously saved set (see above). The current
218             set will be destroyed!</para></listitem>
219
220         <listitem><para><emphasis>Options</emphasis></para>
221           <para>Displays the options dialog. See
222             <xref linkend="CONFIGURATION"/>
223             (Options/Configuration).</para>
224         </listitem>
225         <listitem><para><emphasis>About/Legal</emphasis></para>
226           <para>Displays a dialog with some info about the prog and the
227             binary itself plus the good old GPL.</para></listitem>
228
229         <listitem><para><emphasis>Quit</emphasis></para>
230           <para>No comment.</para></listitem></itemizedlist></section>
231     <section id="TURNtableCONTROLS"><title>Turntable Controls</title>
232       <para>The turntable GUI contains multiple controls and the
233         realtime displays for each turntable. To save some space on your
234         desktop and to give terminatorX the traditional
235         audio-application look, terminatorX features
236         &quot;knob&quot;-widgets. These widgets work pretty
237         straight-forward: click somewhere within the widget and keep the
238         left mouse-button pressed. Now move the mouse up and down or
239         left and right to increase/decrease the control's value. All
240         those widget are coupled with a text entry field since 3.70,
241         which allows you to enter values directly.</para>
242
243       <para>A turntable is visualized by two panels: the control and the
244         audio panel. These are no longer combined for better layout
245         management.</para>
246       <para>
247         Sometimes you might find a certain audio or control panel
248         unnecessary - simply eating up space. Since release 3.73 it is
249         possible to minimize audio and control panels to the 
250         <emphasis>panel bar</emphasis> with the tiny button with a blue
251         bar icon in the upper right edge of each panel. This bar works
252         just like GNOME's
253         window list or KDE's kicker: When a panel is minimized a button in
254         the bar will appear, representing the minimized window. On
255         clicking this button the button will be removed and the
256         minimized panel is displayed again. When no panels are minimized
257         the panel bar automatically disappears to save display space.
258 </para>
259       <section><title>Turntable Audio Panel</title>
260         <para>The complete audio-file loaded into a turntable is
261           displayed in the green-on-black audio-widget. When playing
262           terminatorX will indicate the current position within the
263           sample with a red cursor (a blue/green cursor indicates the
264           turntable is muted).</para>
265
266         <para>Additionaly there are some controls above the audio-display:</para>
267         <itemizedlist><listitem><para><emphasis>Turntable Label</emphasis></para>
268             <para>This label indicates the turntables name. The name can
269               be set via the control panel</para></listitem>
270
271           <listitem><para><emphasis>File Button</emphasis></para>
272             <para>This button holds the name of the audio-file currently
273               loaded. When there's no sample loaded the button will read
274               &quot;NONE&quot; to indicate the current status. 
275               Click on this button to get a menu from which you can
276               load/reload a sound file or run an external soundfile
277               editor. Alternatively you can drag'n'drop
278               files over the audio-display to load
279               them.</para>
280             <itemizedlist>
281               <title>The File Button Menu</title>
282               <listitem><para><emphasis>Load File</emphasis></para>
283                 <para>Choose this menu entry to select a soundfile from
284                   the file-selection dialog that will pop-up.
285                 </para></listitem>
286
287               <listitem><para><emphasis>Reload File</emphasis></para>
288                 <para>Choose this menu entry to re-read the
289                   audio-file.</para></listitem>
290
291               <listitem><para><emphasis>Edit File</emphasis></para>
292                 <para>This menu entry will run the external audiofile-editor
293                   (that can be specified via the options-dialog) with
294                   the current audio-file as a parameter. Choose
295                   reload after editing and saving the
296                   file.</para></listitem>
297
298             </itemizedlist>
299           </listitem>
300           
301           <listitem>
302             <para><emphasis>Mouse Mapping</emphasis></para>
303             <para>terminatorX allows mapping misc parameters to the
304               mouse axis of your choice. These mappings will be
305               activated in grab mode, so if you move your mouse in X or
306               Y direction in grab mode the parameters you selected from
307               this menu will be affected (for this turntable). Since
308               Version 3.70 this mappings are no longer hardcoded to
309               built-in controls but available for all parameters that
310               qualify as &quot;mappable&quot;. Note that this includes
311               plugins' controls as
312               well.</para></listitem></itemizedlist></section>
313
314       <section><title>Turntable Controls</title>
315         <para>These controls are now grouped within functional
316           panels. The number of panels depends on the number of plugins
317           loaded. terminatorX allows hiding the controls not required
318           via the yellow triangle button. To un-hide just click the
319           button again. The first panels are the standard controls for a
320           turntable, then follows the dynamic FX-section and below that
321           follow the pitch and volume controls.</para>
322         
323         <section><title>Main Panel</title>
324           <itemizedlist><listitem><para><emphasis>Name Field</emphasis></para>
325               <para>The main panel features a text entry field that
326                 allows setting a name for the related turntable. The
327                 Labels for the controls and the audio-display will
328                 update accordingly.</para></listitem>
329
330             <listitem><para><emphasis>Delete Button</emphasis></para>
331               <para>Pressing this button remove the tunrtable from the
332                 current setup. Note that all sequencer events recorded
333                 for this turntable will be erased,
334                 too.</para></listitem></itemizedlist></section>
335
336         <section><title>Trigger Panel</title>
337           <para>The trigger panel holds all controls related to
338             triggering the turntable. For more details on
339             synchronization see <xref linkend="SYNCHRONIZATION"/>
340             (synchronization).</para>
341
342           <itemizedlist><listitem><para><emphasis>Trigger! Button</emphasis></para>
343               <para>Pressing this button triggers the turntable
344                 now. With the audio engine enabled this will cause the
345                 turntable to start playing back audio from the beginning
346                 of the sample.</para></listitem>
347
348             <listitem><para><emphasis>Stop Button</emphasis></para>
349               <para>Guess what, this stops this turntable's
350                 audio-playback.</para></listitem>
351
352             <listitem><para><emphasis>Master Button</emphasis></para>
353               <para>Enabling this button makes this turntable the
354                 <emphasis>sync-master</emphasis>. Note that only
355                 <emphasis>one</emphasis> turntable at a time can be the
356                 sync-master.</para></listitem>
357
358             <listitem><para><emphasis>Client Button</emphasis></para>
359               <para>This button marks the turntable as
360                 <emphasis>sync-client</emphasis>, so it will be triggerd
361                 with the master automatically.</para></listitem>
362
363             <listitem><para><emphasis>Sync-Cycles Selection</emphasis></para>
364               <para>The sync cycles determine how often a sync-client
365                 should be triggered. With a setting of zero the
366                 sync-client will be (re-)triggered with
367                 <emphasis>every</emphasis> trigger of the sync-master. A
368                 setting of 1 will (re-)trigger the client every
369                 <emphasis>second</emphasis> master-triger and so
370                 on.</para></listitem></itemizedlist>
371
372           <para>Below the effect queue a turntable shows some more controls:
373             <itemizedlist>
374               <listitem>
375                 <para><emphasis>Pitch Control</emphasis></para>
376                 <para>The pitch control allows setting the default playback
377                   speed for that turntable (the "motor" speed). Negative values
378                   will result in the sample being played backwards.</para>
379               </listitem>
380               <listitem>
381                 <para><emphasis>PAN Control</emphasis></para>
382                 <para>This parameter allows setting the position of the
383                   turntable's main signal within the stereo panorama.</para>
384               </listitem>
385               <listitem>
386                 <para><emphasis>VU Meter</emphasis></para>
387                 <para>The displayed signal shows the turntable's current
388                   signal not including the echo-signal which is mixed
389                   separately.</para>
390               </listitem>
391             </itemizedlist>
392
393           </para>
394
395         </section></section>
396       <section><title>The Effect Queue</title>
397         <para>With release 3.70 the effects are no longer hardcoded into
398           the turntable. The effects are now arranged within an
399           per-turntable effect-queue. The effect sequence is
400           configurable by the user. To move an effect to higher position
401           within the queue, press the <emphasis>blue upward arrow
402             button</emphasis>. This will cause the effect to be renderd
403           <emphasis>before</emphasis> the following effects. The
404           <emphasis>blue downward arrow button</emphasis> will move the
405           effect down by one position. It will then be rendered
406           <emphasis>after</emphasis> the preceding effects.</para>
407
408
409         <para>There are two types of effects: the traditional built-in
410           effects (Lowpass and Echo) and LADSPA plugins. The built-in
411           effects are always available and cannot be removed (but
412           disabled). There can be only one instance of a built-in
413           effect. The LADSPA plugins on the other hand may be
414           instanciated multiple times and can be removed from the effect
415           queue. Press the <emphasis>blue cross button</emphasis> to
416           achieve this.</para>
417
418         <figure float="0">
419           <title>An example for a terminatorX effect queue</title>
420           <graphic fileref="figures/signalflow" scale="27"/>
421         </figure>
422         <para>Now since release 3.71 the built-in echo effect is treated
423           differently from other effects. Where all other effects feed
424           their signal back into the effect queue the echo effect
425           doesn't touch the input signal. It's echo-signal is mixed
426           seperately from the turntable's main signal to allow a
427           different panning value for the echo-signal. This mode of
428           operation does have some side-effects: imagine a lowpass
429           filter with a position after the echo effect in the effect
430           queue. This will result in the turntable's main signal being
431           lowpassed but it will leave the echo-signal
432           un-lowpassed.</para>
433
434         <para>Some may call this behaviour a bug - whereas I would
435           consider it a feature ;). Anyway if the above description
436           didn't clear things up maybe the displayed figure does. It
437           shows a schematic effect queue with the built-in effects and
438           two LADSPA effects enabled. Now with this setup you will not
439           hear anything from the second LADSPA effect in the
440           echo-signal.</para>
441
442
443         <para>For more information on a LADSPA plugin, press it's panel's label and a small info box will pop up.</para>
444         <itemizedlist><listitem><para><emphasis>FX Button</emphasis></para>
445             <para>Press this button to load a LADSPA plugin into the
446               effect queue of the turntable. A menu holding the
447               available (terminatorX-&quot;compatible&quot;)
448               LADSPA-plugins will pop up. The plugins are grouped within
449               submenus according to the modules the plugins are
450               contained in. Simply select the plugin you want to load
451               from this menu and a panel for it will pop up at the end
452               of the effect queue.</para>
453
454             <para>Note that due to the wide parameter ranges some LADSPA
455               plugins have they sometimes might be hard to control with
456               the knob widget. In these cases you might want to use the
457               text field to enter values. For more details on Plugins
458               see <xref linkend="LADSPAPLUGINS"/>
459               (LASDPA).</para></listitem></itemizedlist></section>
460
461       <section><title>Lowpass Panel</title>
462         <para>terminatorX features a builtin resonating lowpass filter
463           that can be configured with this panel.</para>
464
465         <itemizedlist><listitem><para><emphasis>Enable Button</emphasis></para>
466             <para>Activating this button will enable the lowpass filter
467               for this turntable.</para></listitem>
468
469           <listitem><para><emphasis>Input Gain Control</emphasis></para>
470             <para>With this parameter you can amplify the signal that
471               goes into the lowpass filter if
472               required.</para></listitem>
473
474           <listitem><para><emphasis>Frequency Control</emphasis></para>
475             <para>Use this parameter to set the cutoff frequency for the
476               lowpass filter. Minimum: 0=0Hz, Maximum:
477               1=22KHz.</para></listitem>
478
479           <listitem><para><emphasis>Resonance</emphasis></para>
480             <para>Use this parameter to set the
481               resonance-value. Minimum: 0=no resonance, Maximum: 1=max
482               resonance.</para></listitem></itemizedlist></section>
483
484       <section><title>Echo Panel</title>
485         <para>Additionaly terminatorX features a built-in echo
486           effect. It can be configured with this panel.</para>
487
488         <itemizedlist><listitem><para><emphasis>Enable
489                 Button</emphasis></para>
490
491             <para>Activating this button will enable the echo effect for
492               this turntable.</para></listitem>
493
494           <listitem><para><emphasis>Duration Control</emphasis></para>
495             <para>Use this parameter to set the length of the echo. The
496               duration parameter scales to the actual sample length: so
497               if you set it to 0.5 you will hear the echo when the red
498               playback cursor is half way  through the sample. This is
499               true for samples that are shorter than terminatorX'
500               maximum echo buffer size only.</para></listitem>
501
502           <listitem><para><emphasis>Feedback Control</emphasis></para>
503             <para>Set the echo's feedback amount with this
504               parameter.</para></listitem>
505
506           <listitem><para><emphasis>Volume Control</emphasis></para>
507             <para>This parameter can additionally amplify the echo
508               signal. Unlike the feedback parameter above this parameter
509               has no influence on the signal fed back into the
510               echo-buffer, it effects merely the playback volume of the
511               echo signal.</para></listitem>
512
513           <listitem><para><emphasis>Pan Control</emphasis></para>
514             <para>The echo effect differs from other effects as it's
515               output signal will be mixed seperately. The main goal here
516               is to allow positioning the echo signal at a position in
517               the stereo panorama that differs from the main panning
518               positon of the turntable to achieve a somewhat spacial
519               effect. The easy example is: turntable's panning left,
520               echo's panning right. As both pan parameters are
521               sequencable you can create nice motion effects from this
522               starting point.</para></listitem>
523
524
525         </itemizedlist></section></section>
526     <section id="SYNCHRONIZATION"><title>Synchronization</title>
527       <para>Let's start off with an example: Say you have two drumloops
528         and one bassline loaded in three turntables. Of course you want
529         these samples to be triggered at the same time but you don't
530         want to invest time to cut them to the exact length. Therefore
531         you decide which of the drumloops to make the sync
532         master. You'll have to do this before you enable the audio
533         engine (for now). Only one turntable can be the sync master. Now
534         you can make the other two sync clients which will cause them to
535         be (re-)triggered whenever the master is (re-)triggered. The
536         number you can select to the right of the <emphasis>client
537           button</emphasis> sets the trigger delay for the button: if
538         it's set to zero the turntable will be triggered with every
539         master trigger, if it's set to 1 it'll be triggered every 2nd
540         master trigger and so on.</para>
541
542       <para>A nice side effect of this feature is: you can now scratch
543         the second (sync client) drum loop and no matter whether you're
544         scratching is good or not the beat will be triggered correctly
545         again ;)</para></section>
546
547     <section id="GRABMODE"><title>Grab Mode Operation</title>
548       <para>After pressing the <emphasis>Mouse Grab button</emphasis>
549         terminatorX enters "grab mode". This mode actually locks the
550         mouse (as this input is now used to control the realtime
551         parameters) and therefore you'll have to know some
552         mouse/keyboard shortcuts to control the software without the
553         GUI.</para>
554
555       <para>Press <keycap moreinfo="NONE">ESCAPE</keycap> to quit grab mode.</para>
556       <para>Select the turntable with input focus: The first turntable
557         to hold the input focus will be the first turntable. You can now
558         use <keycap moreinfo="NONE">TAB</keycap> or right mouse button
559         to switch to the next turntable. Alternativley you can use
560         <keycap moreinfo="NONE">F1</keycap> to 
561         <keycap moreinfo="NONE">F12</keycap> to select turtntable 1 to 12.</para>
562
563       <para>Now the turntable that has the focus is the one you will
564         manipulate with your mouse and keyboard inputs: Note that you
565         can actually map different functions to the mouse x/y axis - so
566         what actually happens when you move your mouse depends on what
567         you select on the x/y control panels for each turntable.</para>
568
569       <table><title>Keyboard Controls in Grab Mode</title>
570         <tgroup COLS="2"><thead><row><entry>Key</entry>
571               <entry>Function</entry></row></thead>
572           <tbody><row><entry><keycap moreinfo="NONE">TAB</keycap></entry>
573               <entry>select next turntable</entry></row>
574             <row><entry><keycap moreinfo="NONE">F1</keycap> to
575                 <keycap moreinfo="NONE">F12</keycap></entry>
576               <entry>select turntable 1 to 12</entry></row>
577             <row><entry><keycap moreinfo="NONE">RETURN</keycap></entry>
578               <entry>triggers the turntable</entry></row>
579             <row><entry><keycap moreinfo="NONE">BACKSPACE</keycap></entry>
580               <entry>stops the turntable</entry></row>
581             <row><entry><keycap moreinfo="NONE">S</keycap></entry>
582               <entry>toggles "Sync Client"</entry></row>
583             <row><entry><keycap moreinfo="NONE">SPACE</keycap></entry>
584               <entry>while pressed turntable speed is mapped to mouse
585                 speed (scratching!)</entry></row>
586
587             <row><entry><keycap moreinfo="NONE">ALT</keycap></entry>
588               <entry>mute on/off</entry></row>
589             <row><entry><keycap moreinfo="NONE">CTRL</keycap></entry>
590               <entry>mute on/off (inverted)</entry></row>
591             <row><entry><keycap moreinfo="NONE">F</keycap></entry>
592               <entry>("fast") warp mode (while scratching)</entry></row>
593             <row><entry><keycap moreinfo="NONE">W</keycap></entry>
594               <entry>same as above but the audio will be muted while
595                 warping</entry></row></tbody></tgroup></table>
596
597       <table><title>Mouse Button Controls in Grab Mode</title>
598         <tgroup COLS="2"><thead><row><entry>Mouse Button</entry>
599               <entry>Function</entry></row></thead>
600           <tbody><row><entry><emphasis>Left button</emphasis></entry>
601               <entry>same as <keycap moreinfo="NONE">SPACE</keycap>:
602                 scratching (triggers the turntable when
603                 stopped)</entry></row>
604
605             <row><entry><emphasis>Right button</emphasis></entry>
606               <entry>select next turntable</entry></row>
607             <row><entry><emphasis>Middle button</emphasis></entry>
608               <entry>mute on/off</entry></row></tbody></tgroup></table>
609       <para>Scratching works as before: press <keycap
610                                                       moreinfo="NONE">SPACE</keycap> or left mouse button to actually scratch: now your mouse controls the turntables speed. Release it to let that turntable spin at default speed again.</para></section>
611
612     <section id="DRAGNDROP"><title>Drag And Drop</title>
613       <para>Since V3.55 terminatorX provides multiple DND-Drop-Targets
614         for use with GNOME / gmc (gmc is the GNU Midnight Commander),
615         Nautilus or the Elightenment File Manager (efm). You can load an
616         audiofile into an existing turntable by dragging it from a gmc
617         (or efm or whatever)-window and drop it  over a. the
618         <emphasis>file button</emphasis> (audio-display) or b. (the
619         easier target ;) over the audio-display (the green on black
620         widget that displays the audiodata).</para>
621
622       <para>To add a file to the set (== to load the file into a *new*
623         turntable) simply drop the audiofile over the "New Turntable"
624         Button. To load a complete terminatorX-set simply drop the
625         setfile (*.tX) over the "Load Set" button.</para></section>
626
627     <section id="SEQUENCER"><title>The Sequencer</title>
628       <para>Release 3.60 introduced the sequencer. It can record and
629         play back events for the following parameters:</para>
630
631       <itemizedlist><listitem><para>master volume &amp; pitch</para></listitem>
632         <listitem><para>scratching</para></listitem>
633         <listitem><para>(turntable) volume &amp; pitch</para></listitem>
634         <listitem><para>triggers</para></listitem>
635         <listitem><para>loop (on/off)</para></listitem>
636         <listitem><para>sync client settings</para></listitem>
637         <listitem><para>muting</para></listitem>
638         <listitem><para><emphasis>all</emphasis> parameters for the
639             effects. This includes built-in effects (lowpass and echo)
640             as well as LADSPA plugins.</para></listitem></itemizedlist>
641
642       <para>To record events simply press the
643         <emphasis>Record</emphasis> button of the sequencer, then press
644         the <emphasis>Play</emphasis> button. All actions (for
645         sequencable parameters - see above) you now take will be
646         recorded into the song list. Press <emphasis>Stop</emphasis> and
647         <emphasis>Play</emphasis> again to see/hear how terminatorX
648         plays back the events recorded before. You can now record events
649         again for e.g. another turntable or record other parameters for
650         the same turntable - whatever you want to do. Recording events
651         for parameters for wich events have been recorded before will
652         result in dubbing: if you touch a parameter while recording,
653         events previously recorded will be erased from the moment you
654         touch the paramater until you stop recording.</para>
655
656       <para>When recording long sequences/songs you can use the
657         sequencer-scale to start recording/playback from any
658         song-position you want. To record a single paramteter value at a
659         certain position simply move the sequencer-scale to that
660         position, press <emphasis>Record,</emphasis> set the parameter
661         and press <emphasis>Stop</emphasis> again.</para>
662
663       <para>There is no other the way to edit the sequencer events
664         currently, but future releases may feature an event-list
665         editor.</para></section>
666
667     <section id="LADSPAPLUGINS"><title>Plugins (LADSPA)</title>
668       <para>Since release 3.70 terminatorX supports
669         LADSPA-plugins. LADSPA is the &quot;Linux Audio Developer's
670         Simple Plugin API&quot; which was designed by developers on the
671         Linux-Audio-Developer-Mailinglist and is maintained by Richard
672         W.E. Furse. For more information on LADSPA, other LADSPA-hosts
673         and LADSPA-plugins checkout the 
674         <ulink url="http://www.ladspa.org">LADSPA homepage</ulink>.</para>
675
676       <para>Not every plugin is supported by terminatorX though. As the
677         plugins are inserted into the per-turntable effect-queue, they
678         have to be mono plugins (as is that queue) for now. This is why
679         terminatorX will load plugins with <emphasis>one</emphasis>
680         audio-in port and <emphasis>one</emphasis> audio-out port
681         only.</para>
682
683       <para>The decision on wether a plugin is terminatorX-suitable is
684         made on terminatorX startup, so only plugins that fit into the
685         effect queue will be offered in the plugin-menu that pops up
686         when the <emphasis>FX</emphasis> button is clicked. On startup
687         terminatorX will print some information on the LADSPA-plugins
688         analysis process to the standard output. Watch the terminal you
689         run terminatorX from for that info if you have problems loading
690         a plugin.</para>
691
692       <para>As specified in the LADSPA-standard LADSPA-plugins can be
693         located in multiple directories across the filesystem. To enable
694         LADSPA-hosts to find those plugins you have to set the
695         environment variable <ENVAR>LADSPA_PATH</ENVAR>
696         accordingly. Let's say you store your plugins in 
697         <filename moreinfo="NONE">/usr/lib/ladspa</filename>
698         and <filename moreinfo="NONE">/home/yourlogin/plugins</filename>
699         then you would have to set:</para>
700
701
702       <para><ENVAR>LADSPA_PATH</ENVAR>=
703         <filename moreinfo="NONE">/usr/lib/ladspa:/home/yourlogin/plugins</filename></para>
704       <para>As a fallback terminatorX will look in the standard
705         directories <filename moreinfo="NONE">/usr/lib/ladspa</filename>
706         and <filename moreinfo="NONE">/usr/local/lib/ladspa</filename>
707         if the environment variable  is not set. Note that this is just
708         a convenience-function, in order for other LADSPA-hosts to work
709         properly, be sure to set your <ENVAR>LADSPA_PATH</ENVAR>
710         correctly. It is a good idea to do that from somewhere in your
711         system configuration (either in your rc-scripts or 
712         <filename moreinfo="NONE">/etc/profile</filename> 
713         or whereever you perefer).</para></section></section>
714
715   <section id="CONFIGURATION"><title>Configuration</title>
716     <para>All configuration business now happens in the
717       Options-dialog. The features that are not completely
718       self-explaining do have tooltips.</para>
719
720     <para>A word on the settings in general: your settings are stored in
721       the file <filename
722                          moreinfo="NONE">~/.terminatorX3rc.bin</filename> so if you think you completely messed up your settings you will have to exit terminatorX - delete this file - and then re-run terminatorX with the default settings.</para>
723
724     <section id="AUDIOSETUP"><title>Audio Setup</title>
725       <para>TerminatorX renders audio blockwise. If you want to have
726         near-realtime operation you need to have really small
727         blocks. The values of these blocks can be influenced via the
728         <emphasis>buffer size</emphasis> option. The setting you select
729         actually results in a 2^x blocksize (size-setting == 8 -> true
730         buffer size in bytes is 2^8=256).</para>
731
732       <para>The problem is the smaller the value you select is the
733         faster your machine has to be. So if you here "clicks", or
734         "drops" in audio output that are not related to your
735         sample-material you will have to increase the buffer size. On
736         the other hand if you believe terminatorX does not react fast
737         enough you have to decrease this parameter. The default value is
738         8, but as my machine handles 7 nicely (running with root
739         privileges for realtime scheduling) I use 7.</para></section>
740
741     <section id="MOUSEINPUTSETUP"><title>Mouse/Input Setup</title>
742       <para>Between rendering and outputing these blocks terminatorX
743         checks for mouse motion. The problem with mice is: they don't
744         report when they have stopped. This is why terminatorX assumes
745         your mouse has stopped if there is no motion reported for
746         certain amount of render/output-cycles. This value is
747         configurable via the <emphasis>Stop-sense-cycles</emphasis>
748         option. If you decrease your buffsize of course you shorten the
749         cycle time as well, therefore if you here strange stop/run
750         behaviour of the audio ouput while scratching after you
751         decreased the buffersize you might have to increase the
752         stop-sense value too.</para>
753
754       <para>Xinput Device: <emphasis>WARNING:</emphasis> Use this option
755         *only* if you want to use an input device other than your
756         default-mouse for scratching. Selecting your default pointer
757         will cause terminatorX to crash. See the "Using a turntable"
758         section on the terminatorX homepage for
759         details.</para></section>
760
761     <section id="GUISETUP"><title>GUI Setup</title>
762       <para>With <emphasis>Update Idle</emphasis> / <emphasis>Update
763           Delay</emphasis> you can configure GUI resposivness: Higher
764         <emphasis>Update Idle</emphasis> will cause the wav-display
765         (position display) and flash-widgets to update less
766         often. Higher <emphasis>Update Delay</emphasis> values will
767         cause the parameter widgets to update less
768         often.</para></section>
769
770     <section id="SOUNDFILEEDITOR"><title>Soundfile-Editor integration</title>
771       <para>You can now enter the soundfile editor of your choice in the
772         "Soundfile editor" field. This editor will be started when
773         clicking the <emphasis>Edit</emphasis>-button in the  main panel
774         of the vtt-gui. If you enter for example "myeditor" terminatorX
775         will run "myeditor
776         sample_in_vtt.wav".</para></section></section>
777
778   <section id="CONTACT"><title>Contact / Download</title>
779     <para>Find out more about terminatorX at it's <ulink url="http://www.terminatorX.cx">homepage</ulink>.</para>
780     <para>Send me comments, bug-reports, patches or scratches (see
781       scratches section on the terminatorX homepage) at:
782       <email>alkoit00@fht-esslingen.de</email></para></section>
783 </article>
784
785
786