Updating to current release - Alex
[terminatorX.git] / terminatorX / README
1 terminatorX V3.60 README
2 ------------------------
3
4 New:
5      6.4   : Drag And Drop
6      6.5   : The Sequencer
7      
8 Updated:
9      6.2.1 : The Main Panel
10      7     : Options
11
12 Copyright (C) 1999, 2000 Alexander König
13 eMail: alkoit00@fht-esslingen.de
14 Homepage: http://www.terminatorX.cx
15
16 This is free software see the COPYING file that came with this
17 distribution for details.
18
19 WARNING: TerminatorX comes with ABSOLUTELY NO WARRANTY. This software is known
20 to lockup X11 or cause other problems under rare conditions. Don't use
21 it on production servers. You have been warned!
22
23 Contens:
24 --------
25
26         1.......What it is
27         2.......Quickstart
28         3.......Features
29         4.......Requirements
30         5.......Installation
31         6.......Operation
32         6.1.....The Master GUI
33         6.2.....The Turntable GUI
34         6.2.1...The Main Panel
35         6.2.2...The Trigger Panel
36         6.2.2.1.Syncing Turntables
37         6.2.3...The X- and Y-Control Panels
38         6.2.4...The Lowpass Panel
39         6.2.5...The Echo Panel
40         6.3.....Grab Mode Operation
41         6.4.....Drag And Drop
42         6.5.....The Sequencer
43         7.......Options/Configuration
44         7.......Further notes
45         8.......Contact/Homepage
46
47 1. What it is
48 -------------
49
50 terminatorX is a realtime audio synthesizer that allows you to "scratch"
51 on digitally sampled audio data (*.wav, *.au, *.mp3, etc.) the way hiphop-DJs
52 scratch on vinyl records. It features multiple turntables, realtime effects and
53 an easy-to-use gtk+ GUI.
54 This is BETA Software please help me fix bugs. See section Contact/Homepage.
55 Please read this README and take a look at the homepage http://www.terminatorX.cx.
56
57 2. Quickstart:
58 ----------------
59
60         o Install terminatorX (see INSTALL)
61         o Run terminatorX
62         o Load an audiofile into the available turntable (you can add
63           more turntables if you want) (Hint: Click on the button that
64           holds "NONE" in the "Main"-panel)
65         o Click on the "Audio Engine"-button to start playback.
66         o Click on the "Mouse-Grab"-button to enter grab mode. The turntable
67           with the red border has the input focus.
68         o Press <SPACE> or left mouse button to scratch
69         o Release <SPACE> or left mouse button to let the scratch-file run at
70           the turntable's default speed
71         o Press <ESC> to quit grab mode.
72         
73 3. Features:
74 ------------
75
76         NOTE: I decided to remove the old ridiculous feature list and replace
77         it by a shorter version.
78         
79         - Scratching ;) 
80         - Multiple turntables
81         - Builtin Sequencer
82         - Pitch / Volume settings for each turntable
83         - Effects (Lowpass/Echo) configurable for each turntable
84         - Syncing tables to one master turntable
85         - Broad audiofile-type support through the use of sox and mpg123
86         - Recording (straight to disk now)
87         - Save turntable sets (.tX - files)
88         - and more 
89         
90 4. Requirements:
91 ----------------
92
93         - Software:
94           ---------
95           required:
96                         o Linux (>= 2.0)
97                         o glibc2 (pthreads)
98                         o XFree86 (with DGA DirectMouse support)
99                         o gtk+ (>= 1.2.0)
100                         o a compiler (gcc)
101           optional:
102                         o XFree86 >= 3.3.3.1 to support other XInput devices
103                         o sox for enhanced audio file support
104                         o mpg123 for mp3 support
105           
106         - Hardware:
107           ---------
108                         o A OSS compatible soundcard.
109                         o A good clean mouse and pad, a good X-Pointer setup. 
110
111 NOTE on performance: tX is known to run pretty smooth on "current" PCs
112         (200MHz++). If you experience problems take a look at the config
113         options section in INSTALL.
114         
115 5. Installation:
116 ----------------
117
118 For GNU-standards' sake this information is now located in the INSTALL file
119 that came with this distribution of terminatorX.
120   
121 6. Operation:
122 -------------
123
124 Since V3.5 terminatorX has separated GUIs for main operation and the turntable
125 settings and therefore I'll (try to ;) explain these in different sections.
126
127 6.1 The Master GUI
128 ------------------
129
130 The controls of the master gui are located in the top and the right bar of the
131 terminatorX main window.
132
133 - Audio Engine Power / Mouse Grab
134 With the Audio Engine Button you can en- and disable the audio playback
135 engine without activating the sequencer. Unlike earlier versions you will
136 not automatically enter mouse-grab mode so you can modify volume/pitch/echo
137 settings etc. while you actually hear what you do. Some functions are not
138 available when the audio engine is on, their controls will be marked insensitive
139 when you enable the engine. To actually enter grab mode you'll have to click on
140 the "Mouse Grab" button. See the "Grab Mode Operation" section to find out how
141 to control the software then.
142
143 - Record (Audio Engine)
144 To enable recording you have to enable the "Record"-toggle button BEFORE you 
145 start the audio engine. You will be prompted for a filename after enabling the
146 button. Audio will then be recorded to that file in RIFF/WAV format from the
147 moment you turn the audio engine on until you turn it off again. Please be aware
148 of the fact that recording audio requires A LOT of harddisk space!
149
150 - Sequencer Play / Record / Stop
151 Please Read 6.5 to find out more about the sequencer.
152
153 - Master Volume / Pitch
154 The volume and pitch settings of the individual turntables are relative to these
155 master settings. This information will be stored within the .tX set files.
156
157 - Add Turntable
158 Oh well, it says it all: adds a (new) turntable to the current set.
159
160 - Save Set
161 With this button you can save your current set and all related settings to a 
162 .tX set file. Note that the audiofiles themselves will not be stored within
163 these files but only references to them. Therefore on loading the set the 
164 audiofiles have to be at the same location in the filesystem as they were when
165 putting that set together.
166
167 - Load Set
168 Loads a previously saved set (see above). The current set will be destroyed!
169
170 - Hide Gui
171 If you have a lot of turntables you may find all the panels disturbing in
172 grab mode. Therefore you can hide these by clicking on "Hide Gui".
173
174 - Options
175 Displays the options dialog. See section 7 (Options/Configuration)
176
177 - About/Legal
178 Displays a dialog with some info about the prog and the binary itself plus
179 the good old GPL.
180
181 - Quit
182 No comment.
183
184 6.2 The Turntable GUI
185 ---------------------
186
187 The turntable GUI contains multiple controls and the realtime displays for each
188 turntable.
189
190 6.2.1 The Main Panel
191 --------------------
192
193 With the text entry widget you can setup a name for the turntable. "Delete" 
194 removes the turntable from the current set. The button beneath these two holds
195 the name of the currently loaded audiofile. On creation it will hold "NONE". To
196 load an audiofile click that button. Volume and Pitch... oh well ;)
197
198 "Edit" will run the soundfile editor you configured in the Options-dialog with
199 the soundfile loaded into the turntable as parameter. After editing the file you
200 can make terminatorX reload the file by clicking the "Reload" button.
201
202 6.2.2 The Trigger Panel
203 -----------------------
204
205 "Trigger!" actually triggers that turntable right now -> it will start playing 
206 immediately if the audio engine is turned on. Stop will stop playback (of this
207 turntable) of course. Autotrigger will cause the turntable to be triggered
208 whenever you turn on the audio engine. Loop en- or disables the looping of that
209 turntable.
210
211 6.2.2.1 Syncing Turntables
212 --------------------------
213
214 Let's start off with an example: Say you have two drumloops and one bassline
215 loaded in three turntables. Of course you want these samples to be triggered
216 at the same time but you don't want to invest time to cut them to the exact 
217 length. Therefore you decide which of the drumloops to make the sync master. 
218 You'll have to do this before you enable the audio engine (for now). Only one
219 turntable can be the sync master. Now you can make the other two sync clients
220 which will cause them to be (re-)triggered whenever the master is
221 (re-)triggered. The number you can select to the right of the "Sync Client"
222 button sets the trigger delay for the button: if it's set to zero the turntable
223 will be triggered with every master trigger, if it's set to 1 it'll be triggered
224 every 2nd master trigger and so on.
225
226 A nice side effect of this feature is: you can now scratch the second (sync
227 client) drum loop and no matter whether you're scratching is good or not the
228 beat will be triggered correctly again ;)
229
230
231 6.2.3 The X- and Y-Control Panels
232 ---------------------------------
233
234 With these panels you can select which mouse axis (X = left to right, Y= up
235 and down) controls which realtime parameter. Possible choices are
236 o Scratching
237 o Volume
238 o Cutoff frequency for the lowpass filter
239 o Feedback value for the echo
240 o Nothing
241
242 6.2.4 The Lowpass Panel
243 -----------------------
244
245 This panel contians the controls for the resonating lowpass filter. The
246 "Resonance" and "Frequency" parameters control the actual filter and "Input
247 Gain" enables you to preamp the signal in case the filter eats too much
248 volume.
249
250 6.2.5 The Echo Panel
251 --------------------
252
253 Here you can en- and disable the echo-effect and set "Duration" and "Feedback"
254 parameters. The duration parameter scales to the actual sample length: so if you
255 set it to 0.5 you will hear the echo when the red playback cursor is half way 
256 through the sample. This is true for samples that are shorter than
257 terminatorX' maximum echo buffer size only.
258
259 6.3 Grab Mode Operation
260 -----------------------
261
262 After pressing "Mouse Grab" terminatorX enters "grab mode". This mode actually
263 locks the mouse (as this input is now used to control the realtime parameters)
264 and therefore you'll have to know some mouse/keyboard shortcuts to control
265 the software without the GUI:
266
267 Press <ESC> to quit grab mode.
268
269 Select the turntable with input focus:
270 The first turntable to hold the input focus will be the first turntable. You
271 can now use <TAB> or right mouse button to switch to the next turntable. 
272 Alternativley you can use <F1> to <F12> to select turtntable 1 to 12.
273
274 Now the turntable that has the focus is the one you will manipulate with your
275 mouse and keyboard inputs: Note that you can actually map different functions
276 to the mouse x/y axis - so what actually happens when you move your mouse
277 depends on what you select on the x/y control panels for each turntable.
278
279 Keyboard:
280 <TAB>           select next turntable
281 <F1> to <F12>   select turntable 1 to 12
282 <RETURN>        triggers the turntable
283 <BACSPACE>      stops the turntable
284 <S>             toggles "Sync Client"
285 <SPACE>         while pressed turntable speed is mapped to mouse speed
286                 (scratching!)
287 <ALT>           mute on/off
288 <CTRL>          mute on/off (inverted)
289 <F>             (> "fast") warp mode (while scratching)
290 <W>             same as above but the audio will be muted while warping
291
292 Mouse:
293 left button     same as <SPACE> -> scratching (triggers the turntable when
294                 stopped)
295 right button    select next turntable
296 middle button   mute on/off
297
298 Scratching works as before: press <SPACE> or left mouse button to actually
299 scratch -> now your mouse controls the turntables speed -> release <SPACE>
300 to let that turntable spin at default speed again.
301
302 6.4 Drag And Drop
303 -----------------
304
305 Since V3.55 terminatorX provides multiple DND-Drop-Targets for use with GNOME/
306 gmc (gmc is the GNU Midnight Commander). You can now load an audiofile into
307 an existing turntable by dragging an audiofile from a gmc-window and drop it 
308 over a. the "file"-button (on the "main"-panel) or b. (the easier target ;)
309 over the wavdisplay (the green on black widget that displays the audiodata).
310 To add a file set (== to load the file into a *new* turntable) simply drop the
311 audiofile over the "New Turntable" Button. To load a complete terminatorX-set
312 simply drop the setfile (*.tX) over the "Load Set" button. DND does not work
313 with KDE.
314
315 6.5 The Sequencer
316 -----------------
317
318 Release 3.60 introduces the sequencer. It can record and play back events for
319 the following parameters:
320
321 Master volume & pitch, scratching, (turntable) volume & pitch, triggers,
322 loop (on/off), sync client settings, muting and all lowpass and echo paramters.
323
324 To record events simply press the Record button of the sequencer, then press
325 the Play button. All actions (for sequencable parameters - see above) you now
326 take will be recorded into the song list. Press the Stop and Play again to
327 see/hear how terminatorX plays back the events recorded before. You can now
328 record events again for e.g. another turntable or record other parameters for
329 the same turntable - whatever you want to do. Recording events for parameters
330 for wich events have been recorded before will result in dubbing: if you touch
331 a parameter while recording, events previously recorded will be erased from the
332 moment you touch the paramater until you stop recording.
333
334 When recording long sequences/songs you can use the sequencer-scale to start
335 recording/playback from any song-position you want. To record a single
336 paramteter value at a certain position simply move the sequencer-scale to that
337 position, press Record, set the parameter and press Stop again.
338
339 There is no other the way to edit the sequencer events currently, but future
340 releases may feature an event-list editor.
341
342 7. Options/Configuration
343 ------------------------
344
345 All configuration business now happens in the Options-dialog. The features
346 that are not completely self-explaining do have tooltips. So in this README
347 I will discuss the buffer settings and the sense-cycles-option only. 
348
349 A word on the settings in general: your settings are stored in the file
350 ~/.terminatorX3rc.bin so if you think you completely messed up your settings
351 you will have to exit terminatorX - delete this file - and then re-run 
352 terminatorX with the default settings.
353
354 TerminatorX renders audio blockwise. If you want to have near-realtime operation
355 you need to have really small blocks. The values of these blocks can be 
356 influenced via the "buffer size" option. The setting you select actually results
357 in a 2^x blocksize (size-setting == 8 -> true buffer size in bytes is 2^8=256).
358
359 The problem is the smaller the value you select is the faster your machine has
360 to be. So if you here "clicks", or "drops" in audio output that are not related
361 to your sample-material you will have to increase the buffer size. On the 
362 other hand if you believe terminatorX does not react fast enought you have to
363 decrease this parameter. The default value is 8, but as my machine handles 7
364 nicely (with --enhance-scheduler and root privileges) I use 7.
365
366 Between rendering and outputing these blocks terminatorX checks for mouse 
367 motion. The problem with mice is: they don´t report when they have stopped.
368 This is why terminatorX assumes your mouse has stopped if there is no motion
369 reported for certain amount of render/output-cycles. This value is configurable
370 via the Stop-sense-cycles. If you decrease your buffsize of course you shorten
371 the cycle time as well, therefore if you here strange stop/run behaviour of 
372 the audio ouput while scratching after you decreased the buffersize you might 
373 have to increase the stop-sense value too.
374
375 Xinput Device: WARNING: Use this option *only* if you want to use an input 
376 device other than your default-mouse for scratching. Selecting your default
377 pointer will cause terminatorX to crash. See the "Using a turntable" section
378 on the terminatorX homepage for details.
379
380 With "Update Idle" / "Update Delay" you can configure GUI resposivness: Higher
381 "Update Idle" will cause the wav-display (position display) and flash-widgets
382 to update less often. Higher "Update Delay" values will cause the parameter
383 widgets to update less often.
384
385 You can now enter the soundfile editor of your choice in the "Soundfile editor"
386 field. This editor will be started when clicking the "Edit"-button in the 
387 main panel of the vtt-gui. If you enter for example "myeditor" terminatorX will
388 run "myeditor sample_in_vtt.wav".
389
390 8. Further notes:
391 -----------------
392
393 You can find more on terminatorX operation and especially the mouse
394 configuration on the terminatorX homepage: http://www.terminatorX.cx
395
396 9. Contact/Homepage:
397 --------------------
398
399 terminatorX's homepage: http://www.terminatorX.cx
400
401 send comments, bug-reports, patches or scratches (see scratches section on the
402 terminatorX homepage) to: alkoit00@fht-esslingen.de