Fix readme
[terminatorX.git] / terminatorX / README
index b69ca4b2ce00f7a77c2324373a6db86670c85303..a7ad9566e9bb75786f24465d222290e185237faa 100644 (file)
-terminatorX V2.3 README
------------------------
+terminatorX V3.83 README
+------------------------
 
-Copyright (C) 1999 Alexander König
-eMail: alkoit00@fht-esslingen.de
-Homepage: http://www.termX.cjb.net
+Copyright (C) 1999-2011 Alexander König
+eMail: alex@lisas.de
+Homepage: http://terminatorX.org
 
-This is open source software see the COPYING file that came with this
+This is free software see the COPYING file that came with this
 distribution for details.
 
-Contens:
---------
+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!
 
-       1.......What it is
-       2.......Quickstart
-       3.......Features
-       4.......Requirements
-       5.......Installation
-       6.......Operation
-       7.......Further notes
-       8.......Contact/Homepage
+Read that fine Manual:
+----------------------
 
-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 don´t 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 
+    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