Uploaded Version 3.2 into ther repository... Alex
[terminatorX.git] / terminatorX / README
1 terminatorX V3.2 README
2 -----------------------
3
4 Copyright (C) 1999 Alexander König
5 eMail: alkoit00@fht-esslingen.de
6 Homepage: http://termX.cjb.net
7
8 This is free software see the COPYING file that came with this
9 distribution for details.
10
11 WARNING: TerminatorX comes with ABSOLUTELY NO WARRANTY. Version 3.0 introduces
12          some features that are not too heavily tested and a crashing
13          terminatorX may now result in locked X-Pointer.
14
15 Contens:
16 --------
17
18         1.......What it is
19         2.......Quickstart
20         3.......Features
21         4.......Requirements
22         5.......Installation
23         6.......Operation
24         7.......Options/Configuration
25         7.......Further notes
26         8.......Contact/Homepage
27
28 1. What it is
29 -------------
30
31 TerminatorX is a realtime audio synthesizer. It enables you to scratch
32 on wavfiles like you might have heard HipHop-DJs scratch on vinyl records.
33 This is BETA Software please help me fix bugs. See section Contact/Homepage.
34 Please read this README and take a look at the homepage
35 http://www.termX.cjb.net BEFORE you complain.
36
37 2. Quickstart:
38 ----------------
39
40         o Install terminatorX (see INSTALL)
41         o Run terminatorX
42         o Load a scratch file (and a loop if you want)
43         o Click Start
44         o Press <SPACE> or left mouse button to scratch
45         o Release <SPAVE> or left mouse button to let the scratch-file run at
46           the turntable's default speed
47         o Press ESC or middle (third) mouse button to stop
48         
49 3. Features:
50 ------------
51
52         Pre-3.0 Features (still there):
53         -------------------------------
54         
55         o CD-Quality operation
56         o Audio aliasing
57         o Optional playback of an additional loop wavfile to
58           enable rhythm based scratching
59         o Recording of your scratching in a memory buffer, customizable by user
60         o Save that buffer (as a wavfile) with or without the loop mixed to it,
61           no matter whether you recorded it with our without a loop playback
62         o Visual feedback to "see" current position in scratch-wavfile
63         o Kernel-level audio latency configurable
64         o Run terminatorX on the hardware platform of your choice,
65           this software is known to run on the following platforms        
66                 - X86 (i386) (Linux)
67                 - PowerPC (Linux)
68                 - SUN Sparcs (Linux)
69           It should run on other Linux hardware as well, if you manage to
70           run it on any other platform (or you have prolems) please contact
71           me.     
72         
73         New Features (3.0++):
74         ---------------------
75         
76         o Easy to use GUI (gtk+)
77         o No more commandline switches - settings are now configurable via
78           the options dialog and saved on exit.
79         o Better mouse handling (now requires DGA)
80         o Support for other (XInput) devices
81         o (If enabled) Support for .mp3, .wav, .au, .iff, .smp, .cdr ....
82         o Improved visual feedback for better scratching.
83         o Mouse-button support ;)
84         o Mouse Y-axis support (see Options)
85         o Time-display
86         o Heavily enhanced audio-rendering engine. It is now 100% click free.
87           (Btw: if you hear clicks these may result either:
88            - from a buffer underrun -> enlarge audio buffersize (Options)
89            - from "dirty" samples (either loop or scratch)
90            - from importing audiofiles with a samplerate != 44.1 kHz)
91         o You can now mute the scratch (try <M>, <STRG>, right mouse button
92           or (different!) <ALT>)
93         
94         
95 4. Requirements:
96 ----------------
97
98         o A Linux system with gcc/egcs and X-Windows installed.         
99           
100           You now need pthreads (alias LinuxThreads an implementation of POSIX
101           threads) and a threadsafe libc: glibc2(++) as terminatorX is 
102           multithreaded again (Hi, Andy ;))
103           
104           For the GUI you now need: gtk+ >= 1.2.0
105           
106           If you want to use other devices than your main X-Pointer
107           you proabably need: XFree86 >= 3.3.3.1
108           
109           For enhanced audiofile support you need sox (and mpg123 for mp3s)
110           
111         o A soundcard that's supported either by OSS our ALSA.
112         o A good clean mouse and pad, a good X-Pointer setup. see the mouse
113           section on the homepage.
114
115 Notes:  On performance the only thing I can say is this: it runs fine on my
116         P(I)233MMX with 98MB of RAM. On slower machines you might have to
117         enlarge the kernel-level audio buffer (see Options). Nobody ever
118         told me it didn't run (due to cpu-power) so if you think your machine's
119         to slow please tell me so I can specify machines to slow...
120         
121 NEW:    Since Version 3.2 tX contains a lowpass filter which seems to eat quite
122         some CPU power. So a bigger machine wont hurt, I guess a 200MMX is sort
123         of the lower limit. Maybe I'll find ways to accelerate that stuff for
124         future versions...      
125         
126 5. Installation:
127 ----------------
128
129 For GNU-standards' sake this information is now located in the INSTALL file
130 that came with your distribution of terminatorX.
131   
132 6. Operation:
133 -------------
134
135 This chapter was heavily cut as terminatorX now has a very easy to handle
136 GUI. This GUI btw features tooltips, so if you want to know what a button/slider
137 is about leave your mouse above that widget for a second or two and a short
138 explanation will pop up.
139
140 Still if you're new to terminatorX (and not familiar with 3.0+) you should
141 read the following.
142
143 About Scratching:
144
145 At first you have to select the operation Mode:
146
147 - Free Scratch: 
148   This Mode enables scratching. The scratching is not recorded and therefore
149   the playback will only stop if you hit either the middle mouse button
150   or <ESC> ("Escape").
151   
152 - Record Scratch:
153   This Mode enables scratching. The scratching will be recorded into the 
154   record buffer. Playback either stops when the record buffer is full or you
155   pressed one of buttons described above.
156   
157 - Playback Scratch:
158   This mode disables scratching. For now your mouse will be locked anyway.
159   In this mode terminatorX will playback the record buffer. Playback will
160   either stop when all of the recorded data was played back or you pressed
161   on of the buttons described above.
162
163 If you have a scratch-file (== a file to scratch on) loaded and maybe a loop
164 as well you can hit the "Start" button to start Playback.
165
166 Both samples (scratch and loop) will playback at normal speed. To actually
167 scratch you will have to keep either <SPACE> or left mouse button. Now the
168 scratch sample is played back at the same speed you move your mouse -> you
169 scratch ;). If you want to temporarily mute the scratch-sample press either,
170 <M>, right mouse button or <CTRL>. You can also use <ALT> but the "meaning"
171 of this key is inverted: 
172         - ALT pressed  -> scratch NOT muted.
173         - ALT released -> scratch muted.
174 This is of course not true when playback starts. The scratch will be unmuted
175 then. Why there are multiple ways of muting? So you can use whatever you
176 prefer.
177
178 If you want to "move" through the sample a little faster you can keep <F> 
179 (alias fast) pressed to accelerate by factor 10.
180
181 To stop playback you either press middle mouse button, <ESC> or (for 
182 compability with old versions) <RETURN>.
183
184 Recorded scratches can be saved with one of the four "save"-buttons on the
185 right side of terminatorX's main window. "Fast" means you wont have to enter
186 a filename, terminatorX will generate the name from the prefix you set (if
187 not default is "tX_scratch") in the Options dialog. "(mix)" means the saved
188 file will contain your scratch mixed with the loop file at the currently
189 selected ratio. 
190
191 NEW: Since version 3.2 terminatorX comes with an additonal resonating lowpass
192 filter. If enabled this effect will be applied to the scratch-signal. The
193 resonance parameter can be set with the slider underneath the "LP Filter" 
194 on/off button. The other parameter (cutoff frequency) can be modified in
195 realtime while scratching. Depending on what mouse-axis you chose for scratching
196 the other axis will be used for modifying the cutoff frequency of the lowpass
197 filter. Now if you think this sounds somewhat complicated, simply run
198 terminatorX, enable "LP Filter" and set the resonance-factor close to the max
199 (~ pretty far to the right) and move your mouse up and down (or from left )
200 while scratching and hear what happens...
201
202 Althoug tX is trying to adjust the input volume according to the resonance 
203 factor, you might get clipping with high resonance values and samples that
204 contain loud high-frequent parts. The only way to get around this for now is to
205 reduce resonance.
206
207 7. Options/Configuration
208 ------------------------
209
210 All configuration business now happens in the Options-dialog. The features
211 that are not completely self-explaining do have tooltips. So in this document
212 I will discuss the buffer settings and the sense-cycles-option only. 
213
214 A word on the settings in general: your settings are stored in the file
215 ~/.terminatorXrc.bin so if you think you completely messed up your settings
216 you will have to exit terminatorX - delete this file - and then re-run 
217 terminatorX with the default settings.
218
219 TerminatorX renders audio blockwise. If you want to have near-realtime operation
220 you need to have really small blocks. The values of these blocks can be 
221 influenced via the "buffer size" option. The setting you select actually results
222 in a 2^x blocksize (size-setting == 8 -> true buffer size in bytes is 2^8=256).
223
224 The problem is the smaller the value you select is the faster your machine has
225 to be. So if you here "clicks", or "drops" in audio output that are not related
226 to your sample-material you will have to increase the buffer size. On the 
227 other hand if you believe terminatorX does not react fast enought you have to
228 decrease this parameter. The default value is 9. IMHO I'd say 8 is close to
229 perfect but this value causes clicks on my machine already (I still use 8
230 though ;) ).
231
232 Between rendering and outputing these blocks terminatorX checks for mouse 
233 motion. The problem with mice is: they don´t report when they have stopped.
234 This is why terminatorX assumes your mouse has stopped if there is no motion
235 reported for certain amount of render/output-cycles. This value is configurable
236 via the Stop-sense-cycles. If you decrease your buffsize of course you shorten
237 the cycle time as well, therefore if you here strange stop/run behaviour of 
238 the audio ouput while scratching after you decreased the buffersize you might 
239 have to increase the stop-sense value too.
240
241 8. Further notes:
242 -----------------
243
244 You can find more on terminatorX operation and especially the mouse
245 configuration on the terminatorX homepage: http://termX.cjb.net
246
247 9. Contact/Homepage:
248 --------------------
249
250 terminatorX's homepage: http://termX.cjb.net
251
252 If you wan't to send me comments, bug-reports, patches or scratches (see
253 the users' scratches section on the terminatorX homepage) send a me
254 an eMail to alkoit00@fht-esslingen.de