terminatorX V3.60 README
------------------------

New:
     6.4   : Drag And Drop
     6.5   : The Sequencer
     
Updated:
     6.2.1 : The Main Panel
     7     : Options

Copyright (C) 1999, 2000 Alexander Knig
eMail: alkoit00@fht-esslingen.de
Homepage: http://www.terminatorX.cx

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

WARNING: TerminatorX comes with ABSOLUTELY NO WARRANTY. This software is known
to lockup X11 or cause other problems under rare conditions. Don't use
it on production servers. You have been warned!

Contens:
--------

	1.......What it is
	2.......Quickstart
	3.......Features
	4.......Requirements
	5.......Installation
	6.......Operation
	6.1.....The Master GUI
	6.2.....The Turntable GUI
	6.2.1...The Main Panel
	6.2.2...The Trigger Panel
	6.2.2.1.Syncing Turntables
	6.2.3...The X- and Y-Control Panels
	6.2.4...The Lowpass Panel
	6.2.5...The Echo Panel
	6.3.....Grab Mode Operation
	6.4.....Drag And Drop
	6.5.....The Sequencer
	7.......Options/Configuration
	7.......Further notes
	8.......Contact/Homepage

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

terminatorX is a realtime audio synthesizer that allows you to "scratch"
on digitally sampled audio data (*.wav, *.au, *.mp3, etc.) the way hiphop-DJs
scratch on vinyl records. It features multiple turntables, realtime effects and
an easy-to-use gtk+ GUI.
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.terminatorX.cx.

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

	o Install terminatorX (see INSTALL)
	o Run terminatorX
	o Load an audiofile into the available turntable (you can add
	  more turntables if you want) (Hint: Click on the button that
	  holds "NONE" in the "Main"-panel)
	o Click on the "Audio Engine"-button to start playback.
	o Click on the "Mouse-Grab"-button to enter grab mode. The turntable
	  with the red border has the input focus.
	o Press <SPACE> or left mouse button to scratch
	o Release <SPACE> or left mouse button to let the scratch-file run at
	  the turntable's default speed
	o Press <ESC> to quit grab mode.
	
3. Features:
------------

	NOTE: I decided to remove the old ridiculous feature list and replace
	it by a shorter version.
	
	- Scratching ;) 
	- Multiple turntables
	- Builtin Sequencer
	- Pitch / Volume settings for each turntable
	- Effects (Lowpass/Echo) configurable for each turntable
	- Syncing tables to one master turntable
	- Broad audiofile-type support through the use of sox and mpg123
	- Recording (straight to disk now)
	- Save turntable sets (.tX - files)
	- and more 
	
4. Requirements:
----------------

	- Software:
	  ---------
	  required:
			o Linux (>= 2.0)
			o glibc2 (pthreads)
			o XFree86 (with DGA DirectMouse support)
			o gtk+ (>= 1.2.0)
			o a compiler (gcc)
	  optional:
	  		o XFree86 >= 3.3.3.1 to support other XInput devices
			o sox for enhanced audio file support
			o mpg123 for mp3 support
	  
	- Hardware:
	  ---------
			o A OSS compatible soundcard.
			o A good clean mouse and pad, a good X-Pointer setup. 

NOTE on performance: tX is known to run pretty smooth on "current" PCs
	(200MHz++). If you experience problems take a look at the config
	options section in INSTALL.
	
5. Installation:
----------------

For GNU-standards' sake this information is now located in the INSTALL file
that came with this distribution of terminatorX.
  
6. Operation:
-------------

Since V3.5 terminatorX has separated GUIs for main operation and the turntable
settings and therefore I'll (try to ;) explain these in different sections.

6.1 The Master GUI
------------------

The controls of the master gui are located in the top and the right bar of the
terminatorX main window.

- Audio Engine Power / Mouse Grab
With the Audio Engine Button you can en- and disable the audio playback
engine without activating the sequencer. Unlike earlier versions you will
not automatically enter mouse-grab mode so you can modify volume/pitch/echo
settings etc. while you actually hear what you do. 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 the "Grab Mode Operation" section to find out how
to control the software then.

- Record (Audio Engine)
To enable recording you have to enable the "Record"-toggle button BEFORE you 
start the audio engine. You will be prompted for a filename after enabling the
button. Audio will then be recorded to that file in RIFF/WAV format from the
moment you turn the audio engine on until you turn it off again. Please be aware
of the fact that recording audio requires A LOT of harddisk space!

- Sequencer Play / Record / Stop
Please Read 6.5 to find out more about the sequencer.

- Master Volume / Pitch
The volume and pitch settings of the individual turntables are relative to these
master settings. This information will be stored within the .tX set files.

- Add Turntable
Oh well, it says it all: adds a (new) turntable to the current set.

- Save Set
With this button you can save your current set and all related settings to a 
.tX set file. Note that the audiofiles themselves will not be stored within
these files but only references to them. Therefore on loading the set the 
audiofiles have to be at the same location in the filesystem as they were when
putting that set together.

- Load Set
Loads a previously saved set (see above). The current set will be destroyed!

- Hide Gui
If you have a lot of turntables you may find all the panels disturbing in
grab mode. Therefore you can hide these by clicking on "Hide Gui".

- Options
Displays the options dialog. See section 7 (Options/Configuration)

- About/Legal
Displays a dialog with some info about the prog and the binary itself plus
the good old GPL.

- Quit
No comment.

6.2 The Turntable GUI
---------------------

The turntable GUI contains multiple controls and the realtime displays for each
turntable.

6.2.1 The Main Panel
--------------------

With the text entry widget you can setup a name for the turntable. "Delete" 
removes the turntable from the current set. The button beneath these two holds
the name of the currently loaded audiofile. On creation it will hold "NONE". To
load an audiofile click that button. Volume and Pitch... oh well ;)

"Edit" will run the soundfile editor you configured in the Options-dialog with
the soundfile loaded into the turntable as parameter. After editing the file you
can make terminatorX reload the file by clicking the "Reload" button.

6.2.2 The Trigger Panel
-----------------------

"Trigger!" actually triggers that turntable right now -> it will start playing 
immediately if the audio engine is turned on. Stop will stop playback (of this
turntable) of course. Autotrigger will cause the turntable to be triggered
whenever you turn on the audio engine. Loop en- or disables the looping of that
turntable.

6.2.2.1 Syncing Turntables
--------------------------

Let's start off with an example: Say you have two drumloops and one bassline
loaded in three turntables. Of course you want these samples to be triggered
at the same time but you don't want to invest time to cut them to the exact 
length. Therefore you decide which of the drumloops to make the sync master. 
You'll have to do this before you enable the audio engine (for now). Only one
turntable can be the sync master. Now you can make the other two sync clients
which will cause them to be (re-)triggered whenever the master is
(re-)triggered. The number you can select to the right of the "Sync Client"
button sets the trigger delay for the button: if it's set to zero the turntable
will be triggered with every master trigger, if it's set to 1 it'll be triggered
every 2nd master trigger and so on.

A nice side effect of this feature is: you can now scratch the second (sync
client) drum loop and no matter whether you're scratching is good or not the
beat will be triggered correctly again ;)


6.2.3 The X- and Y-Control Panels
---------------------------------

With these panels you can select which mouse axis (X = left to right, Y= up
and down) controls which realtime parameter. Possible choices are
o Scratching
o Volume
o Cutoff frequency for the lowpass filter
o Feedback value for the echo
o Nothing

6.2.4 The Lowpass Panel
-----------------------

This panel contians the controls for the resonating lowpass filter. The
"Resonance" and "Frequency" parameters control the actual filter and "Input
Gain" enables you to preamp the signal in case the filter eats too much
volume.

6.2.5 The Echo Panel
--------------------

Here you can en- and disable the echo-effect and set "Duration" and "Feedback"
parameters. The duration parameter scales to the actual sample length: so if you
set it to 0.5 you will hear the echo when the red playback cursor is half way 
through the sample. This is true for samples that are shorter than
terminatorX' maximum echo buffer size only.

6.3 Grab Mode Operation
-----------------------

After pressing "Mouse Grab" terminatorX enters "grab mode". This mode actually
locks the mouse (as this input is now used to control the realtime parameters)
and therefore you'll have to know some mouse/keyboard shortcuts to control
the software without the GUI:

Press <ESC> to quit grab mode.

Select the turntable with input focus:
The first turntable to hold the input focus will be the first turntable. You
can now use <TAB> or right mouse button to switch to the next turntable. 
Alternativley you can use <F1> to <F12> to select turtntable 1 to 12.

Now the turntable that has the focus is the one you will manipulate with your
mouse and keyboard inputs: Note that you can actually map different functions
to the mouse x/y axis - so what actually happens when you move your mouse
depends on what you select on the x/y control panels for each turntable.

Keyboard:
<TAB>		select next turntable
<F1> to <F12>	select turntable 1 to 12
<RETURN> 	triggers the turntable
<BACSPACE> 	stops the turntable
<S>		toggles "Sync Client"
<SPACE>		while pressed turntable speed is mapped to mouse speed
		(scratching!)
<ALT>		mute on/off
<CTRL>		mute on/off (inverted)
<F>		(> "fast") warp mode (while scratching)
<W>		same as above but the audio will be muted while warping

Mouse:
left button	same as <SPACE> -> scratching (triggers the turntable when
		stopped)
right button	select next turntable
middle button	mute on/off

Scratching works as before: press <SPACE> or left mouse button to actually
scratch -> now your mouse controls the turntables speed -> release <SPACE>
to let that turntable spin at default speed again.

6.4 Drag And Drop
-----------------

Since V3.55 terminatorX provides multiple DND-Drop-Targets for use with GNOME/
gmc (gmc is the GNU Midnight Commander). You can now load an audiofile into
an existing turntable by dragging an audiofile from a gmc-window and drop it 
over a. the "file"-button (on the "main"-panel) or b. (the easier target ;)
over the wavdisplay (the green on black widget that displays the audiodata).
To add a file set (== to load the file into a *new* turntable) simply drop the
audiofile over the "New Turntable" Button. To load a complete terminatorX-set
simply drop the setfile (*.tX) over the "Load Set" button. DND does not work
with KDE.

6.5 The Sequencer
-----------------

Release 3.60 introduces the sequencer. It can record and play back events for
the following parameters:

Master volume & pitch, scratching, (turntable) volume & pitch, triggers,
loop (on/off), sync client settings, muting and all lowpass and echo paramters.

To record events simply press the Record button of the sequencer, then press
the Play button. All actions (for sequencable parameters - see above) you now
take will be recorded into the song list. Press the Stop and Play again to
see/hear how terminatorX plays back the events recorded before. You can now
record events again for e.g. another turntable or record other parameters for
the same turntable - whatever you want to do. Recording events for parameters
for wich events have been recorded before will result in dubbing: if you touch
a parameter while recording, events previously recorded will be erased from the
moment you touch the paramater until you stop recording.

When recording long sequences/songs you can use the sequencer-scale to start
recording/playback from any song-position you want. To record a single
paramteter value at a certain position simply move the sequencer-scale to that
position, press Record, set the parameter and press Stop again.

There is no other the way to edit the sequencer events currently, but future
releases may feature an event-list editor.

7. Options/Configuration
------------------------

All configuration business now happens in the Options-dialog. The features
that are not completely self-explaining do have tooltips. So in this README
I will discuss the buffer settings and the sense-cycles-option only. 

A word on the settings in general: your settings are stored in the file
~/.terminatorX3rc.bin 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.

TerminatorX renders audio blockwise. If you want to have near-realtime operation
you need to have really small blocks. The values of these blocks can be 
influenced via the "buffer size" option. The setting you select actually results
in a 2^x blocksize (size-setting == 8 -> true buffer size in bytes is 2^8=256).

The problem is the smaller the value you select is the faster your machine has
to be. So if you here "clicks", or "drops" in audio output that are not related
to your sample-material you will have to increase the buffer size. On the 
other hand if you believe terminatorX does not react fast enought you have to
decrease this parameter. The default value is 8, but as my machine handles 7
nicely (with --enhance-scheduler and root privileges) I use 7.

Between rendering and outputing these blocks terminatorX checks for mouse 
motion. The problem with mice is: they dont report when they have stopped.
This is why terminatorX assumes your mouse has stopped if there is no motion
reported for certain amount of render/output-cycles. This value is configurable
via the Stop-sense-cycles. If you decrease your buffsize of course you shorten
the cycle time as well, therefore if you here strange stop/run behaviour of 
the audio ouput while scratching after you decreased the buffersize you might 
have to increase the stop-sense value too.

Xinput Device: WARNING: Use this option *only* if you want to use an input 
device other than your default-mouse for scratching. Selecting your default
pointer will cause terminatorX to crash. See the "Using a turntable" section
on the terminatorX homepage for details.

With "Update Idle" / "Update Delay" you can configure GUI resposivness: Higher
"Update Idle" will cause the wav-display (position display) and flash-widgets
to update less often. Higher "Update Delay" values will cause the parameter
widgets to update less often.

You can now enter the soundfile editor of your choice in the "Soundfile editor"
field. This editor will be started when clicking the "Edit"-button in the 
main panel of the vtt-gui. If you enter for example "myeditor" terminatorX will
run "myeditor sample_in_vtt.wav".

8. Further notes:
-----------------

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

9. Contact/Homepage:
--------------------

terminatorX's homepage:	http://www.terminatorX.cx

send comments, bug-reports, patches or scratches (see scratches section on the
terminatorX homepage) to: alkoit00@fht-esslingen.de
