Java CD Audio Player 1.2  (for use with JDK 1.2)
------------------------

[Legal stuff is at the end of this file.]

For the impatient: just skip to the "Installation" instructions below.

Jcd was an experiment to see if Java could be used for something more
than simple applets.  I chose to write a CD player because it required:
interfacing to C, controlling hardware, threads, file IO, sockets,
text parsing, image manipulation, data entry, graphical user
interfaces.  A great project for trying out a new language.

Porting requires writing a small native C module.  For the 1.2 version
I have a native modules for Linux only.  Tested with JDK 1.2.2 on
Linux Caldera OpenLinux 2.3.  Contributions of other native modules
would be welcome.

This is an application, not an applet, ie it accesses files and
devices and can't be run under Netscape.  You must use something that
runs a Java application: eg Sun's JDK.  If you've managed to get the
AWT to run, you shouldn't have any trouble installing and running jcd.

Features added/removed in 1.2:
  - Migrated to jdk 1.2 JNI.
  - IRIX is no longer supported.
  - Folded in load/save program patches from Andreas Sigg <Andreas.Sigg @uni-konstanz.de>

Features added in 1.1:
  - Auto load of appropriate native module, i.e. use the same installation
    for all supported platforms.
  - All windows now respond to close requests.
    Thanks to Randy Chapman <chapman@u.washington.edu>
  - Reduced reservation of memory in the jcd starup script.
    Thanks to Randy Chapman <chapman@u.washington.edu>
  - Added Add/Delete/Play mode to the program window.
  - SGI IRIX support
    - Uses the SGI cdaudio library => output to drive headphone socket only.
    - Volume control doesn't work under IRIX (why?).
    - Index play and index display doesn't work under IRIX (how?).

Features in 1.0:
  - Play/Stop/Pause/Prev/Next/Eject/Volume control panel.
  - Track/Index direct access by entry into the numeric display.
  - Displays track, index, num-tracks, track-time/track-remaining/disc-rem'ing.
  - Program play, continuous/single play, shuffle play.
  - Xmcd CDDB artist/disc/track title lookup and display.
    - Xmcd CDDB database format and protocols courtesy of Ti Kan and 
      Steve Scherf (http://sunsite.unc.edu/~cddb/xmcd).
    - Optional remote CDDB server lookup.
    - Autosave of remote lookups to local cache.
    - GUI window for creating/editing artist/title/track local cache entries.
  - Icon button widget - e.g. play button, pause button light up when active.
  - Penguin button (ie somewhere in the application there is a built in 
    plug for Linux).

It's a memory hog - partly due to statically linked Motif libraries
under Linux.   When better Java tools are available the amount of
memory required should come down.  I haven't had the chance to try it
on anything with less than 32MB.

I can't promise to support or enhance Jcd, but feedback is welcome.

I'm quite happy for others to take jcd and carry it in new directions.
The cddb client object could be extracted and put to other uses.  The
low and interediate level CD drive interfaces could also be easily
reused.  At a lower level the FancyButton object might be usefull.

I developed Jcd using JDK 1.0.2, Linux 2.0.20, Caldera 1.0, Redhat
3.0.3, Xemacs 19.14.  It will probably port easily to any platform
that supports Sun's CDROM IOCTL calls.  Porting to others requires
implementing a new Jcd_Drive_<arch-os>.c module to interface to the
hardware.

Installation:
  - Just do
        su
        cd Jcd-1.1
        make install
    A make install as root should install jcd in /usr/local/lib/jcd:
    (Warning "make" copies jcd into /usr/local/bin without first looking 
    for any existing jcd).

    This will install java classes and Linux and IRIX native modules.

  - You can also run it out of the Jcd-1.1 directory - set the 
    jcd.lib property in your ~/.jcdrc file to point to be ./ 
    or blahblah/Jcd-1.1

  - On IRIX - the AWT default font is too large. You can set the
    AWTapp*fontList X resource if you want to change it. E.g. put
    the following in your ~/.Xdefaults file
      AWTapp*fontList: -adobe-helvetica-medium-r-normal--14-*

  - On IRIX a device name of NULL (where NULL is the word NULL) in your 
    .jcdrc will force the driver to use the default IRIX CD device.

  - You may also have to enable access to your CD device.  E.g. on
    IRIX do chmod go+r /dev/scsi/blah  as root. Where blah is the CDROM unit
    found out by doing a hinv.  

Running:
  - Run /usr/local/bin/jcd, which just does the following...

        setenv CLASSPATH ${CLASSPATH}:/usr/local/lib/jcd
	java -mx1m Jcd

    (The java command has to be on your path.)

    When you run it, jcd should auto detect your architecture and OS and
    load the appropriate native module.  The IRIX native
    module was built on IRIX 6.2, but seems to run fine on IRIX 5.3. 

  - Under a Linux kernel configured to run Java as a native language.
	chmod +x /usr/local/lib/jcd/Jcd/Jcd.class
	/usr/local/lib/jcd/Jcd/Jcd.class	

  - You can use a .jcdrc file in you home directory to control how the
    player is configured (see the sample jcdrc in this directory).
    Properties recognised in .jcdrc file (format is name value newline):
      jcd.device       - /dev/cdrom or on SGI use the word NULL 
      jcd.lib          - dir where the native shared objects and images reside
      jcd.module       - override native shared object location - full path
      jcd.device_flags - bit string 
                           1 = stop before play: needed for Linux sbpcd driver.
      jcd.hilight_program_step:	- false, stop program window setting selection.
      jcd.debug        - true - to output debugging info.
      cddb.remote      - true - to use remote internet cddb server.
      cddb.autosave    - true - to cache remote info to local disc.
      cddb.server      - sunsite.unc.edu - cddb database server
      cddb.port        - 888 - cddb port number
      cddb.directory   - /home/user/CDDB - local cache dir

  - These two optional environment settings can also be set
      setenv CDROM /dev/cdrom  # device
      setenv SBPCD 1           # if spbcd Linux driver is being used.

  - The C module debugging can be enabled by:
      setenv JCD_DEBUG 1       # Enable C driver debugging.

Building
  - Edit the Makefile uncommenting one of the supported systems.
  - CLASSPATH must include the Jcd directory, eg:
      setenv CLASSPATH .:/usr/local/java/lib/classes  
    Where the source directory is the cwd.
  - The makefile is a bit crude, but gets the job done
	make
	make install
  - The makefile is configured for my Linux setup - edit for you system
    - Linux shared object modules for Jcd_Driver.so
    - Java development kit under /usr/local/java
  - Needs a sym link of "ln -s . Jcd" to allow the classpath reference
    to the build directory to match the Jcd package (this is in the tar
    by default). 
  - If you want to build for multiple systems, remove all .o and .so 
    files from the source directory before rebuilding for a new system.
  - If you're porting to a new architecture or OS, you need to find out the
    arch and os java properties for your system (eg ix86 and Linux).
    The easiest way to find this out is to run jcd and inspect the
    error message to see what arch and os native module it tries to load. 

Source
  - User Interface
    - Jcd.java      - main 
    - Player.java   - main window
    - Display.java  - Track, index, Tot Tr, Time display
    - DiscInfo.java - Artist/Title and Track Title
    - DiscEdit.java - Artist/Title and Track Title edit/save
    - Controls.java - Standard play,stop,pause,prev,next,eject panel
    - Program.java  - Programming interface for shuffle etc - quick hack.
  - Audio CD device interface
    - Drive.java      - Java to C interface.
    - SmartDrive.java - Extends Drive.java for prev/next and program lists.
    - Monitor.java    - Observes Drive state, notifies SmartDrive, and 
			user interface objects.  Runs in a thread.
    - Jcd_Drive_ix86_Linux.c - Linux native C side of the player - simplistic.
                        Uses Sun IOCTL mechanism => easy to port to Solaris??
    - Jcd_Drive_mips_IRIX.c - IRIX native C cdaudio lib module.
  - cddb interface
    - CddbClient      - Remote Cddb client with local cache.
  - Minor components
    - JcdProps    - properties read from /home/USER/.jcdrc
    - LEDfield	  - combined textfield and label field - LED look.
    - FancyButton - buttons with images on them - AWT does do this yet - so
		    roll our own.  Based on what I learned from studying
                    the NCSA Javigator.
    ...           - Misc minor helpers.

 
Bugs/Features/Limitations

- Need to adjust the volume with an audio mixer the first time its run
  after booting Linux (with kernel modules for sbpcd.o or pcd.o).
- Current method for indicating program step changes the X text selection.
  Because of this the step indicator is disabled by default.
- espresso has problems compiling Jcd.java due to a name space problem,
  don't use espresso for Jcd.java.  Espresso works fine on the other java
  source files.
- Linux tray in/out detection is a hack (due to driver limitations).
- Number button on the edit screen is a hack to get the numbers out of
  the way for data entry. You can edit with the numbers present, but they
  will be ignored and stripped out of the input before it is saved.
- Resizing doesn't work properly - JDK problem?
- Not as pretty as it could be - no time for playing with xpaint/gimp etc.
- Many constants (eg fonts) are hard coded and should really be in the .jcdrc
- Needs to be able to send email to submit new CD disc info to the remote
  server.
- Doesn't save the current program - easy to do - but not done.
- Should be able to click/double-click to play from the Edit window.
- I recommend Zoltan Vorosbaranyi's pcd module as a replacement for
  sbpcd on machines with SB16 Kotobuki/Matsushita/Panasonic
  CR-5xx drives on the SB16 proprietary interface.
- Setting your CLASSPATH can stuff up netscape under Linux (unset before
  running netscape).
- Need to redesign parts of the prototype GUI.
- Volume doesn't work on SGI.
- ...

Digression

  If you're looking for powerful easy to use languages, Python is
  definitely worth a look (http://www.python.org).

COPYRIGHT

       Permission is hereby granted, without written agreement and
       without license or royalty fees, to use, copy, modify, and
       distribute this software and its documentation for any purpose,
       provided that the above copyright notice and the following two
       paragraphs appear in all copies of this software.

       IN NO EVENT SHALL MICHAEL HAMILTON BE LIABLE TO ANY PARTY FOR
       DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
       DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS
       DOCUMENTATION, EVEN IF MICHAEL HAMILTON HAS BEEN ADVISED OF THE
       POSSIBILITY OF SUCH DAMAGE.

       MICHAEL HAMILTON SPECIFICALLY DISCLAIMS ANY WARRANTIES,
       INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
       MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE
       SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND MICHAEL
       HAMILTON HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT,
       UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
