terminatorX V2.3 README
-----------------------

Copyright (C) 1999 Alexander Knig
eMail: alkoit00@fht-esslingen.de
Homepage: http://www.termX.cjb.net

This is open source software see the COPYING file that came with this
distribution for details.

Contens:
--------

	1.......What it is
	2.......Quickstart
	3.......Features
	4.......Requirements
	5.......Installation
	6.......Operation
	7.......Further notes
	8.......Contact/Homepage

1. What it is
-------------

TerminatorX is a realtime audio synthesizer. It enables you to scratch
on wavfiles like you might have heard HipHop-DJs scratch on vinyl records.
This is BETA Software please help me fix bugs. See section Contact/Homepage.
Please read this README and take a look at the homepage
http://www.termX.cjb.net BEFORE you complain.

2. Quickstart:
--------------

	o tar xzf terminatorX-VXX.tar.gz
	o cd terminatorX-VXX
	o edit Makefile to your needs if required
	  (If you want to run terminatorX on a big endian machine (LinuxPPC,
	  Ultrapenguin SUN etc, enable -DBIG_ENDIAN_MACHINE (CFLAGS) and
	  disable optimizations (OPT=), on i386 machines you can safely use
	  OPT=-O2, set Compiler (default=egcs) and X-includes and libs)
	o make
	o become root
	o make install
	o become yourself
	o start terminatorX with any 16Bit, 44.1 kHz, mono Wavfile:
	  e.g.: terminatorX anyfile.wav
	o move your mouse pointer into terminatorX-Window
	o press <RETURN> in the terminatorX-Window
	o press and hold <SPACE>
	o use your mouse to scratch
	o release <SPACE> and if you enjoyed it press again.....
	o press <RETURN> again to stop playback
	o use <q> to quit
	
3. Features:
------------

	o CD-Quality operation
	o Audio aliasing
	o Optional playback of an additional loop wavfile to
	  enable rhythm based scratching
	o Recording of your scratching in a memory buffer, customizable by user
	o Save that buffer (as a wavfile) with or without the loop mixed to it,
	  no matter whether you recorded it with our without a loop playback
	o Visual feedback to "see" current position in scratch-wavfile
	o Kernel-level audio latency configurable via parameters
	o Run terminatorX on the hardware platform of your choice,
	  this software is known to run on the following platforms	  
		- X86 (i386) (Linux)
		- PowerPC (Linux)
		- SUN Sparcs (Linux)
	  It should run on other Linux hardware as well, if you manage to
	  run it on any other platform (or you have prolems) please contact
	  me.
	
4. Requirements:
----------------

	o A Linux system with gcc/egcs and X-Windows installed. Since 
	  terminatorX is no longer multithreaded it shouldn't matter whether
	  you run it on glibc2 or libc5 system. I guess if your system
	  has more than let's say 100 BogoMIPS it should be capable
	  of running terminatorX (see --buffsize option for slow machines)
	o A soundcard supported by OSS (Open Sound System, Linux Audio driver)
	  or any compatible audio driver.
	o A good clean mouse and pad, a good X-Pointer setup. see the mouse
	  section on the homepage.

Notes: 	On performance the only thing I can say is this: it runs fine on my
	P(I)233MMX with 98MB of RAM. On slower machines you might have to
	enlarge the kernel-level audio buffer (default is 512 Bytes) with
	the -b (--buffsize) switch on invoking the program. Nobody ever
	told me it didn't run (due to cpu-power) so if you think your machine's
	to slow please tell me so I can specify machines to slow...
	
5. Installation:
----------------

Installing terminatorX is pretty easy:
- Extract the source-archive:
  > tar xzf terminatorX-VXX.tar.gz

- Change to the newly created directory
  > cd terminatorX-VXX 

- Edit the Makefile:
  The Makefile uses egcs as the default-compiler, if you dont have egcs
  installed you might want to set CC to gcc. On i386 (X86) machines you may
  want to set some optimizations OPT=-O2 seems to work on any i386-System.
  If you want to run terminatorX on a big endian machines (LinuxPPC, SUN, etc.)
  set -DBIG_ENDIAN_MACHINE in the CFLAGS. Some of you might also have to
  correct the path to X-includes and X-libs, and the INSTALLDIR. 

- Build the binary:  
  The normal
  > make
  should do it.

- Install the binary:
  Become root. This depends on your machine and user status. You don't
  actually have to install the binary. You can run it from any directory.
  If you have superuser access type:
  > make install
  and terminatorX will be installed into the INSTALLDIR you specified or
  the default (/usr/local/bin).
  

6. Operation:
-------------

For now terminatorX does not have a man-page but the most important information
is contained within the binary:
- run 
  > terminatorX --help
  to see all commandline options
- run
  > terminatorX --keys
  to see all key-commandos avialable in the terminatorX window.

Using terminatorX is not as straightforward as you might expect it from an
X-Window program. This is due to the fact that we abuse the mouse for scratching
instead of using it to operate the software. 

Whenever you want to run terminatorX you have to give it one wavfile as 
an parameter (the file you want to scratch on):
> terminatorX example.wav

Most important command-line options:
------------------------------------
All options except for -h, -k, -g and -v require a parameter (X in the
following descriptions). The following are just the most important options
try -h to see ALL options.

--help (or -h), no Parameter
	Displays all options
	
--keys	(or -k), no Parameter
	Displays all available keys in terminatorX's window.

--mouse X (or -m) Parameter: float, Default: 0.5
	Sets mouse sensitivity. Use negative values to invert scratch motion.
	
--speed X (or -s) Parameter: float, Default: 1.0
	Sets the motor speed of the virtual turntable.
	
--loop X (or -l) Parameter: string, Default: none
	Specifies a wavfile that can be played while you scratch on the main
	wavfile. E.g. a beat if you want to scratch to a rythm. Mixing is
	now automatically enabled if a loopfile was specified at startup,
	use the <m>-key to toggle mix on/off.
	
--prefix X (or -p) Prameter: string, Default: tX_scratch
	Specifies the name of your saved scratches with the default these
	files are called tX_scratch01.wav, tX_scratch02.wav ....
	
--buffsize X (or -b) Parameter: integer, Default: 9
	This configures the kernel-level audiobuffer's size. With
	the default you get 2^9=512 Bytes. On slower systems you might
	have to increase this value (10 -> 1024 Bytes, 11 -> 2048 Bytes ...)
	The smaller this value the lower the latency of terminatorX.
	
--recbuff X (or -r) Parameter: integer, Default: 500
	With this option you can set the size of the recording buffer in KBytes.
	Recording a scratch stops when this buffer is full. A 500 KB Buffer
	equals 5.6 seconds of audio just like a same sized Wavfile of 16 Bit 
	44.1 kHz mono.

The keys in terminatorX (or how to use it)
------------------------------------------

After you started terminatorX it displays its own window with a figure of
the scratch-wavfile and a "statusbar". If you press <RETURN> now the virtual
turntable starts spinning and you see a red position display underneath the
wave-data. If you press <SPACE> now and keep it pressed you put your
"virtual" hand on the turntable, which means if you don't move your mouse
playback seems to stop. If you DO move your mouse now (with <SPACE> still
pressed) this movement will be transferred to the vritual turntable -> you
scratch. When you release <SPACE> the motor of the virtual turntable starts
spinning again and the playback continues at the usual rate (or the rate you
set with the --speed parameter). Press <RETURN> again to stop playback.

The following keys are only available when playback has stopped:
	
<n>	Enter SCRATCH mode: of the three mode-displays in the lower right
	edge of the window the empty circle becomes activated.
	This mode enables you to scratch when playback is activated as long
	as you want. Nothing will be recorded.
	Start/Stop scratching with <RETURN>
	
<r>	Enter RECORD mode: full circled becomes activated.
	This mode enables the recording of your scratching when playback has 
	started. Playback will stop automatically when the recording buffer
	is full.
	Start/Stop recording with <RETURN>

<p>	Enter PLAYBACK mode: arrow becomes activated.
	In this mode you can NOT scratch. This mode enables you to playback
	your last recorded scratch.
	Start/Stop playback with <RETURN>
	
<m>	Toggle mixing on/off (This works only if you loaded an additional
	loop wavfile via the --loop option)
	This option is fully functional with all three modes described above.
	So you can record a scratch with the mix enabled and play it back 
	without.	

<LEFT>	Decreases the scratch-volume and increases the loop-volume.

<RIGHT>	Decreases the loop-volume and increases the scratch-volume.

<s>	Saves the last scratch recorded RAW (not mixed with loop wavfile).
	Filenames are generated automatically and can be influenced via
	the --prefix option (see above).
	
<x>	Saves the last scratch recorded MIXED (mixed with loop wavfile).
	Filenames are the same as with the <s> key. Mixing happens at
	the currently set volume-levels.
	
ATTENTION:	Files are saved to the current directory. If there are files
		of the same name already, these files will be overwritten!
		So be sure to move your scratches to an other directory or
		set a different prefix each time you save scratches.	

<q>	Quits the program.

Now have fun and scratch! If you have further question see homepage or send
me an eMail.

7. Further notes:
-----------------

You can find more on terminatorX operation and especially the mouse
configuration on the terminatorX homepage: http://www.termX.cjb.net

8. Contact/Homepage:
--------------------

terminatorX's homepage:	http://www.termX.cjb.net

If you wan't to send me comments, bug-reports, patches or scratches (see
the users' scratches section on the terminatorX homepage) send a me
an eMail to alkoit00@fht-esslingen.de 
