$Id: README,v 1.1.1.1 1999/06/04 13:05:41 chb Exp $

                                CDLoop


by Claus Brunzema <chb@ossi.fho-emden.de>


- WHAT IS IT ?

CDLoop is an audio-cd-player for Linux/X11 like e.g. WorkMan. It has
extended capabilities for looping certain parts of a cd (for
hifi-standalone-cdplayers this is often called 'AB-Repeat'). In CDLoop
you can move the boundaries of the looped area after defining a
loop. This is intended for musicians (like myself I admit), who want
to transcribe music and who want to loop the small part of a track
they are working on. If the looped part of a track doesn't start or
end on measure boundaries, you can tell CDLoop to wait some time
before jumping back to the start of the loop. This makes it possible
to continue counting the beat over the loop.

CDLoop is published under the terms of the GNU GENERAL PUBLIC LICENSE
Version 2 (see file COPYING). You may do almost anything you like with
the sourcecode, but please PLEASE _P_L_E_A_S_E_ **DO NOT** release your
results with the name CDLoop. 

Please mail me, if you use CDLoop.


- WARRANTY ???

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.
---> If this thing zaps your cds or your drive, don't blame me,
you have been warned. But CDLoop doesn't use any dirty tricks or
undocumented stuff, so it should be fairly safe :-).


- WHERE TO GET IT ?

The newest Version of CDLoop is available from the author's homepage:
http://ossi.fho-emden.de/homepages/chb/index.html

CDLoop is also available at suntech (but it may not be the latest version):
ftp://sunsite.unc.edu in directory /pub/Linux/apps/sound/cdrom


- WHAT DO YOU NEED TO RUN IT ?

-- Linux (tested with kernel version 2.0.30, gcc 2.7.2.1)
   System V IPC (Inter Process Communication) must be compiled in
-- X11R6 (tested with XFree86 Version 3.3). CDLoop runs in a window 
   min sized 493x365.
-- tcl/tk (at least version 7.6/4.2)
-- a CD-ROM-drive (tested with a standard ATAPI-drive, but people told me it
   works with SCSI, too)
-- something to make the signal from the CD-ROM-drive audible
-- access rights to the CD-ROM (see PROBLEMS)


- HOW TO BUILD IT ?

In order to rebuild CDLoop you need 
- gcc (if you have linux, you have gcc...)
- tcl/tk (see section WEB RESOURCES)
- perl 5 (see section WEB RESOURCES)

Simply type:

configure
make

and you should get the executable CDLoop :-).


- HOW TO USE IT ?

In most cases it should be enough to start the CDLoop-binary simply by
invoking it from the command-line. CDLoop understands the following
options:

-help	           shows the help message of tcl/tk
--help		   shows CDLoop's help message
--version	   gives version info
--device <device>  tells CDLoop to use <device> as cd-drive.
                   Default is /dev/cdrom

CDLoop will complain at startup if there is a mounted data-cd in the drive.

The buttons:
- Quit                   Quits CDLoop (you guessed it).
- About                  Shows my name and some copyright remarks.
- Eject                  Ejects the CD.
- Close                  Closes the tray.
- Play                   Starts playing track one. If CDLoop is 
                         looping a part of the disc, Play restarts the 
                         loop.
- Pause                  Pauses.
- Stop                   Stops.
- <<<, <<, >>, >>>       These are the 'Search'-buttons. With these 
                         you can jump a smaller/bigger step
                         backward/forward in the track.
- Previous               Starts playing the previous track.
- Restart                Restarts the current track or loop if in a loop.
- Next                   Starts playing the next track.

- Locator A:
-- Set                   Sets the first locator.
-- <50, <10 ... 10>, 50> These buttons move the first locator 
                         backward/forward.
- Locator B:
-- Set                   Sets the second locator.
-- Clear                 Clears the second locator.
-- <50, <10 ... 10>, 50> These buttons move the second locator
                         backward/forward.
- Gap:
-- +50, +10 ... -10, -50 These buttons change the length of the gap between
                         the loops.
- Clear Locators         Clears both locators (and the gap (a gap without
                         locators makes no sense)).
- Clear Gap              Clears the gap and leaves the locators untouched.


The keyboard shortcuts:
- 1,2,...,9,0    start playing track 1, 2 and so on (0 starts playing
                 track 10). If the track doesn't exist, do nothing.
- <space>        same as button Pause
- a              same as button Set Locator A
- b              same as button Set Locator B
- c              same as button Clear Locators
- n              same as button Next
- q              same as button Quit
- p              same as button Play
- r              same as button Restart
- s              same as button Stop
- v              same as button Previous (sorry about the v for Previous, but
                   p and r are already used up and e for Previous is even
		   worse than v for Previous)


Any position-data (play-position and position of the locators) is
displayed in the format track-minute:second:frame (one second has 75
frames).


- PROBLEMS

If CDloop plays a cd (you see the position change) and you can't hear
anything, check if your volume setting is correct (I use xmix to set
volumes on my soundcard, see section WEB RESOURCES).

The most common problem is insufficent access rights to the
CD-ROM-drive. If CDLoop can't open the cdrom-device even when there
isn't a cd mounted, do a

chmod 666 /dev/cdrom

as root. Replace /dev/cdrom with the path to the cdrom-device you use.

If CDLoop doesn't run at all, check if you have 'System V Inter
Process Communication' compiled into your Linux-kernel (CDLoop uses
shared memory).


- MISC

-- While writing CDLoop I have learned a lot from the sources of
WorkBone 2.3 (by Thomas McWilliams, tgm@netcom.com). I think there are
about ten lines from WorkBone left in my code. WorkBone is available
under the GPL at:
ftp://sunsite.unc.edu in directory /pub/Linux/apps/sound/players
-- The sourcecode of CDLoop has two parts: the cdplayer-engine
(written in C) and the GUI (written in Tcl/Tk). The GUI is made with
Visual Tcl V1.10 (vtcl), so if you want to change the outlook of
CDLoop, I stongly recommend getting vtcl (it's cool anyway), see
section WEB RESOURCES.
-- The Tcl/Tk-part of CDLoop is integrated into the C-part by
converting the Tcl/Tk-script to a C-string. The C-part runs the
Tcl/Tk-string with Tcl_VarEval(), both parts are in one binary. The
scrip-to-C conversion is done by the perl-script filetostring (called
automatically in the makefile).
-- vtcl reads and executes the Tcl/Tk-scripts loaded for
editing. CDloop uses an extended Tcl/Tk-shell with commands unknown to
vtcl. In order to avoid confusing vtcl, the stuff in the init- and
main-procedures is moved to initCDLoop and mainCDLoop. These two
procedures must be called in main, but for vtcl the lines calling
these procedures are preceded with the special comment sequence
#VTCL_PROTECT:. If the Tcl/Tk-script is loaded into vtcl, the
initCDLoop and mainCDLoop-procedures (containing commands unknown to
vtcl) aren't executed. But if you type 'make', the comment characters
get removed before the script is converted to a C-string.


- BUGS

I'm not sure if CDLoop can handle CDs with both audio and datatracks,
if a datatrack lies between two audiotracks (but I have never seen
such a CD).  If the datatracks are the last tracks on the CD,
everything should work fine.


- NOT TO DO

-- I will never put nice bitmaps on the buttons (e.g. a green triangle on
   the Play-button) and I will never use 'fancy' fonts in CDLoop. I think
   those GUI-extremities are a waste of time and space. They don't improve
   CDLoop at all.
-- I will never port CDLoop to any Mickey$oft OS.


- MY ADDRESS

Suggestions, comments and donations to:

chb@ossi.fho-emden.de

My homepage on the web is at:

http://ossi.fho-emden.de/homepages/chb/index.html


- WEB RESOURCES

-- you can get xmix here:       ftp://sunsite.unc.edu
                                in directory /pub/Linux/apps/sound/mixers
-- official home for Tcl/Tk:    http://www.scriptics.com/
-- for perl 5 see:              http://www.perl.com/perl/index.html
-- you can get vtcl at      
         ->  Home Site:         http://www.neuron.com/stewart/vtcl/
         ->  Australia:         http://holmes.ccs.deakin.edu.au/vtcl/
         ->  United Kingdom:    http://www.jessikat.demon.co.uk/vtcl/
         ->  Germany:           http://www.ifconnection.de/~rjs/vtcl/
         ->  US East:           http://www.ultra.net/~eugene/mirror/vtcl/


- FILES

COPYING          the GNU GENERAL PUBLIC LICENSE Version 2
README           this file
cdhw.c           low-level module dealing with ioctl()s
cdhw.h           header for cdhw.c
cdloop-x.y.lsm	 lsm entry for CDLoop
cdloop.c         the extended Tcl-shell. cdloop.tcl gets compiled in here.
cdloop.tcl       tcl-script defining the XWindows-appearance of CDLoop.
                 This script is made with vtcl, so don't look at it with
                 any other tool (exept for reading the GPL disclaimer :-).
cdplayer.c       the real CD-player.
cdplayer.h       header for cdplayer.c
err.c            for printing errors.
err.h            header for err.c
filetostring.in  script skeleton for converting any file into a C-string. The
                 makefile adds the call to perl in the first line to create
                 the perl-script filetostring
Makefile.in      the makefile template, this is used by configure to create 
                 the real makefile
configure.in     the source for autoconf, you only need this to rebuild the
                 configure-script (not necessary to build CDLoop)
configure        the configure-script, checks for paths and creates the
                 Makefile
.cvsignore	 contains filenames CVS should ignore


- CHANGES

from version 1.1 to version 1.2:
  - I use CVS now
  - CDLoop pays attention to the -geometry option now
  - options --help and --version added
  
from version 1.0.2 to version 1.1:
  - the height of the CDLoop window can be changed.
  - the path of the cd-device can be given on the command-line

from version 1.0.1 to version 1.0.2:
  - Button Restart restarts the loop, not the whole track
  - CDLoop now uses a configure script to get paths right 
      (thanks to Matt Rice <Matt@ProjectA.com> !)

from version 1.0 to version 1.0.1:
  - added comments in the sourcecode, general cleanup etc.
