(no commit message)
[terminatorX.git] / terminatorX / README
1 terminatorX V2.3 README
2 -----------------------
3
4 Copyright (C) 1999 Alexander König
5 eMail: alkoit00@fht-esslingen.de
6 Homepage: http://www.termX.cjb.net
7
8 This is open source software see the COPYING file that came with this
9 distribution for details.
10
11 Contens:
12 --------
13
14         1.......What it is
15         2.......Quickstart
16         3.......Features
17         4.......Requirements
18         5.......Installation
19         6.......Operation
20         7.......Further notes
21         8.......Contact/Homepage
22
23 1. What it is
24 -------------
25
26 TerminatorX is a realtime audio synthesizer. It enables you to scratch
27 on wavfiles like you might have heard HipHop-DJs scratch on vinyl records.
28 This is BETA Software please help me fix bugs. See section Contact/Homepage.
29 Please read this README and take a look at the homepage
30 http://www.termX.cjb.net BEFORE you complain.
31
32 2. Quickstart:
33 --------------
34
35         o tar xzf terminatorX-VXX.tar.gz
36         o cd terminatorX-VXX
37         o edit Makefile to your needs if required
38           (If you want to run terminatorX on a big endian machine (LinuxPPC,
39           Ultrapenguin SUN etc, enable -DBIG_ENDIAN_MACHINE (CFLAGS) and
40           disable optimizations (OPT=), on i386 machines you can safely use
41           OPT=-O2, set Compiler (default=egcs) and X-includes and libs)
42         o make
43         o become root
44         o make install
45         o become yourself
46         o start terminatorX with any 16Bit, 44.1 kHz, mono Wavfile:
47           e.g.: terminatorX anyfile.wav
48         o move your mouse pointer into terminatorX-Window
49         o press <RETURN> in the terminatorX-Window
50         o press and hold <SPACE>
51         o use your mouse to scratch
52         o release <SPACE> and if you enjoyed it press again.....
53         o press <RETURN> again to stop playback
54         o use <q> to quit
55         
56 3. Features:
57 ------------
58
59         o CD-Quality operation
60         o Audio aliasing
61         o Optional playback of an additional loop wavfile to
62           enable rhythm based scratching
63         o Recording of your scratching in a memory buffer, customizable by user
64         o Save that buffer (as a wavfile) with or without the loop mixed to it,
65           no matter whether you recorded it with our without a loop playback
66         o Visual feedback to "see" current position in scratch-wavfile
67         o Kernel-level audio latency configurable via parameters
68         o Run terminatorX on the hardware platform of your choice,
69           this software is known to run on the following platforms        
70                 - X86 (i386) (Linux)
71                 - PowerPC (Linux)
72                 - SUN Sparcs (Linux)
73           It should run on other Linux hardware as well, if you manage to
74           run it on any other platform (or you have prolems) please contact
75           me.
76         
77 4. Requirements:
78 ----------------
79
80         o A Linux system with gcc/egcs and X-Windows installed. Since 
81           terminatorX is no longer multithreaded it shouldn't matter whether
82           you run it on glibc2 or libc5 system. I guess if your system
83           has more than let's say 100 BogoMIPS it should be capable
84           of running terminatorX (see --buffsize option for slow machines)
85         o A soundcard supported by OSS (Open Sound System, Linux Audio driver)
86           or any compatible audio driver.
87         o A good clean mouse and pad, a good X-Pointer setup. see the mouse
88           section on the homepage.
89
90 Notes:  On performance the only thing I can say is this: it runs fine on my
91         P(I)233MMX with 98MB of RAM. On slower machines you might have to
92         enlarge the kernel-level audio buffer (default is 512 Bytes) with
93         the -b (--buffsize) switch on invoking the program. Nobody ever
94         told me it didn't run (due to cpu-power) so if you think your machine's
95         to slow please tell me so I can specify machines to slow...
96         
97 5. Installation:
98 ----------------
99
100 Installing terminatorX is pretty easy:
101 - Extract the source-archive:
102   > tar xzf terminatorX-VXX.tar.gz
103
104 - Change to the newly created directory
105   > cd terminatorX-VXX 
106
107 - Edit the Makefile:
108   The Makefile uses egcs as the default-compiler, if you don´t have egcs
109   installed you might want to set CC to gcc. On i386 (X86) machines you may
110   want to set some optimizations OPT=-O2 seems to work on any i386-System.
111   If you want to run terminatorX on a big endian machines (LinuxPPC, SUN, etc.)
112   set -DBIG_ENDIAN_MACHINE in the CFLAGS. Some of you might also have to
113   correct the path to X-includes and X-libs, and the INSTALLDIR. 
114
115 - Build the binary:  
116   The normal
117   > make
118   should do it.
119
120 - Install the binary:
121   Become root. This depends on your machine and user status. You don't
122   actually have to install the binary. You can run it from any directory.
123   If you have superuser access type:
124   > make install
125   and terminatorX will be installed into the INSTALLDIR you specified or
126   the default (/usr/local/bin).
127   
128
129 6. Operation:
130 -------------
131
132 For now terminatorX does not have a man-page but the most important information
133 is contained within the binary:
134 - run 
135   > terminatorX --help
136   to see all commandline options
137 - run
138   > terminatorX --keys
139   to see all key-commandos avialable in the terminatorX window.
140
141 Using terminatorX is not as straightforward as you might expect it from an
142 X-Window program. This is due to the fact that we abuse the mouse for scratching
143 instead of using it to operate the software. 
144
145 Whenever you want to run terminatorX you have to give it one wavfile as 
146 an parameter (the file you want to scratch on):
147 > terminatorX example.wav
148
149 Most important command-line options:
150 ------------------------------------
151 All options except for -h, -k, -g and -v require a parameter (X in the
152 following descriptions). The following are just the most important options
153 try -h to see ALL options.
154
155 --help (or -h), no Parameter
156         Displays all options
157         
158 --keys  (or -k), no Parameter
159         Displays all available keys in terminatorX's window.
160
161 --mouse X (or -m) Parameter: float, Default: 0.5
162         Sets mouse sensitivity. Use negative values to invert scratch motion.
163         
164 --speed X (or -s) Parameter: float, Default: 1.0
165         Sets the motor speed of the virtual turntable.
166         
167 --loop X (or -l) Parameter: string, Default: none
168         Specifies a wavfile that can be played while you scratch on the main
169         wavfile. E.g. a beat if you want to scratch to a rythm. Mixing is
170         now automatically enabled if a loopfile was specified at startup,
171         use the <m>-key to toggle mix on/off.
172         
173 --prefix X (or -p) Prameter: string, Default: tX_scratch
174         Specifies the name of your saved scratches with the default these
175         files are called tX_scratch01.wav, tX_scratch02.wav ....
176         
177 --buffsize X (or -b) Parameter: integer, Default: 9
178         This configures the kernel-level audiobuffer's size. With
179         the default you get 2^9=512 Bytes. On slower systems you might
180         have to increase this value (10 -> 1024 Bytes, 11 -> 2048 Bytes ...)
181         The smaller this value the lower the latency of terminatorX.
182         
183 --recbuff X (or -r) Parameter: integer, Default: 500
184         With this option you can set the size of the recording buffer in KBytes.
185         Recording a scratch stops when this buffer is full. A 500 KB Buffer
186         equals 5.6 seconds of audio just like a same sized Wavfile of 16 Bit 
187         44.1 kHz mono.
188
189 The keys in terminatorX (or how to use it)
190 ------------------------------------------
191
192 After you started terminatorX it displays its own window with a figure of
193 the scratch-wavfile and a "statusbar". If you press <RETURN> now the virtual
194 turntable starts spinning and you see a red position display underneath the
195 wave-data. If you press <SPACE> now and keep it pressed you put your
196 "virtual" hand on the turntable, which means if you don't move your mouse
197 playback seems to stop. If you DO move your mouse now (with <SPACE> still
198 pressed) this movement will be transferred to the vritual turntable -> you
199 scratch. When you release <SPACE> the motor of the virtual turntable starts
200 spinning again and the playback continues at the usual rate (or the rate you
201 set with the --speed parameter). Press <RETURN> again to stop playback.
202
203 The following keys are only available when playback has stopped:
204         
205 <n>     Enter SCRATCH mode: of the three mode-displays in the lower right
206         edge of the window the empty circle becomes activated.
207         This mode enables you to scratch when playback is activated as long
208         as you want. Nothing will be recorded.
209         Start/Stop scratching with <RETURN>
210         
211 <r>     Enter RECORD mode: full circled becomes activated.
212         This mode enables the recording of your scratching when playback has 
213         started. Playback will stop automatically when the recording buffer
214         is full.
215         Start/Stop recording with <RETURN>
216
217 <p>     Enter PLAYBACK mode: arrow becomes activated.
218         In this mode you can NOT scratch. This mode enables you to playback
219         your last recorded scratch.
220         Start/Stop playback with <RETURN>
221         
222 <m>     Toggle mixing on/off (This works only if you loaded an additional
223         loop wavfile via the --loop option)
224         This option is fully functional with all three modes described above.
225         So you can record a scratch with the mix enabled and play it back 
226         without.        
227
228 <LEFT>  Decreases the scratch-volume and increases the loop-volume.
229
230 <RIGHT> Decreases the loop-volume and increases the scratch-volume.
231
232 <s>     Saves the last scratch recorded RAW (not mixed with loop wavfile).
233         Filenames are generated automatically and can be influenced via
234         the --prefix option (see above).
235         
236 <x>     Saves the last scratch recorded MIXED (mixed with loop wavfile).
237         Filenames are the same as with the <s> key. Mixing happens at
238         the currently set volume-levels.
239         
240 ATTENTION:      Files are saved to the current directory. If there are files
241                 of the same name already, these files will be overwritten!
242                 So be sure to move your scratches to an other directory or
243                 set a different prefix each time you save scratches.    
244
245 <q>     Quits the program.
246
247 Now have fun and scratch! If you have further question see homepage or send
248 me an eMail.
249
250 7. Further notes:
251 -----------------
252
253 You can find more on terminatorX operation and especially the mouse
254 configuration on the terminatorX homepage: http://www.termX.cjb.net
255
256 8. Contact/Homepage:
257 --------------------
258
259 terminatorX's homepage: http://www.termX.cjb.net
260
261 If you wan't to send me comments, bug-reports, patches or scratches (see
262 the users' scratches section on the terminatorX homepage) send a me
263 an eMail to alkoit00@fht-esslingen.de