Fix readme
[terminatorX.git] / terminatorX / README
index 5489f2c244fcdb1b904f0a44d178fe1e7a6bb11a..a7ad9566e9bb75786f24465d222290e185237faa 100644 (file)
@@ -1,17 +1,9 @@
-terminatorX V3.60 README
+terminatorX V3.83 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 König
-eMail: alkoit00@fht-esslingen.de
-Homepage: http://www.terminatorX.cx
+Copyright (C) 1999-2011 Alexander König
+eMail: alex@lisas.de
+Homepage: http://terminatorX.org
 
 This is free software see the COPYING file that came with this
 distribution for details.
@@ -20,383 +12,13 @@ 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 don´t 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
+Read that fine Manual:
+----------------------
 
-send comments, bug-reports, patches or scratches (see scratches section on the
-terminatorX homepage) to: alkoit00@fht-esslingen.de
+    o ./INSTALL             - Information on installing terminatorX
+    o ./README.GNOME        - Some hints on GNOME-integration
+    o ./README.PERFORMANCE  - Some hints on tuning terminatorX
+    o ./doc/terminatorX-manual/C/terminatorX-manual.xml
+                            - The user manual browsable with "yelp"
+                              (yelp is the gnome2 help browser).
+    o ./COPYING             - The license