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