Features over default CD plugin

Internally I think this is much much cleaner. It uses the 
libcdio for disk reading and libcddb to get CDDB information.

But the unsympathetic cold-harded user asks "Don't give me your
problems, what's in it for me?" Simple. These libraries are maintained
separately and can are used in other applications so they are
generally of better quality. If there are problems, they are tested
separately and can be regression tested. Ever seen a regression test
suite for xine? 

In theory, the libraries will be better documented too, but alas right
now that's not true. On the other hand, they are as well documented as
the routines they replace which is to say not at all.

MRL handling: 
-  Can specify device as well as track.
-  Because we use the libcdio library, the "device" can be a disk image
   to be burned (e.g. a cdrdao bin/cue pair and some primitive Nero
   support)

Features:
-  Can customize the title display and meta-info comment field.
-  Customize whether or not to use HTTP proxy for CDDB.
-  Dynamic debugging
-  Ability to get a "directory" list of the tracks on the CD
-  Can view CD as one large unit (composed of tracks) or
   as individual tracks. (Individual tracks are how the current CD 
   plugin works).

libcddb:
  CDDB information can be obtained via HTTP proxy. 
  Can specify a time delay for a network timeout.
  Can specify whether to cache CDDB information or not

Almost all of the non-CDDB feature described above are really also
true with my Video CD plugin.

Disadvantages over existing CD plugin: 
  - No FreeBSD support. But if someone wants to add that or any other
    OS (IRIX, AIX, HP/UX, Mac OS X anyone?) I'd be happy to add that
    in and as a bonus, you'll add a better port to your OS for
    vcdimager (http://vcdimager.org) and the better Video CD plugin.
  - Can't specify the CDDB cache location. Right now you get the
    libcddb default which is ~/.cddbslave. In a way, I think this is
    a good thing, since you'll share the cddb cache with other
    applications that use libcddb. Fixing this is not all that hard
    to do.

 
 
-----------------------------------------------------------------
Quick start
-----------------------------------------------------------------
If you're new to using the plugin some, here are some common things
that will probably trip you up. 

First, this plugin doesn't overwrite the old existing CD-DA plugin
called "CD" Rather it comes *in addition* to it. Perhaps someday this
will change. However when this is installed, there is a slight
conflict in that MRL's that start
"cdda" are used by this plugin". 

If you don't understand what I'm talking with this MRL stuff see the
section below on MRL.  Even if you do understand what a MRL for xine
is you probably want to look at the MRL section. By and large CDX
handles an upward-compatible selection of MRLs. However there are a
lot more kinds of things you can specify in an MRL than you could with
the old plugin.

-----------------------------------------------------------------
MRLS:
-----------------------------------------------------------------

the xine CD-DA plugin, identifies itself in the xine GUI as CDX. It
also registers itelf to handle a class of MRL's that start with
vcdx:/.

The CDX MRL takes the following form:

  cdda:/[path to file or vcd device][:number]]

A simple cdda:/ runs the default item: track 1 using the default VCD
device (perhaps /dev/cdrom). The default default device is
user-configurable.

It is however also possible to specify both Compac Disc device/filename
and item explicitly in the MRL.

For example cdda:/dev/cdrom2 specifies using device /dev/cdrom2 hich
might useful if as I have /dev/cdrom is a burner and the /dev/cdrom2
is a read-only device. And cdda://test_cdda.cue specifies the
"cuesheet" file for a CD-DA image on disk created say with cdrdao.
(test_cdda.bin is the corresponding bin file, but using that won't
work.)

After the optional device name or file name, you can name the track number
unit which preceded by a colon. An MRL which ends in a colon is like
not adding it at all.

Some examples of MRLS are given below. In the examples, we assume the
following configuration setting:

cdda.default_device:/dev/cdrom

  cdda://                   - track 1 of device: /dev/cdrom
  cdda://@                  - same as above
  cdda:///dev/cdrom         - probably same as above
  cdda:///dev/cdrom2        - track 1 of /dev/cdrom2
  cdda:///dev/cdrom2@       - same as above
  cdda://dev/cdrom2@5       - track 5 from /dev/cdrom2
  cdda://@2                 - track 2 from default device
  cdda://3                  - track 3 from default device
  cdda:///dev/cdrom2@4      - track 4 from /dev/cdrom2
  cdda:///tmp/ntsc.cue      - track 1 from /tmp/ntsc.bin, (a bin/cue
                              disk image)
  cdda:///tmp/ntsc.cue@     - same as above
  cdda:/ntsc.nrg            - track 1 of ntsc.nrg (a nero disk image)
  cdda://tmp/ntsc.nrg@5     - track 5 of /tmp/ntsc.nrg

Bad MRL's
  cdda://@x                  - x is not a number
  cdda/tmp                   - no colon
  cdda:/                     - must start cdda://

-----------------------------------------------------------------
Configuration settings:
-----------------------------------------------------------------

Configuration settings in xine are generally put in ~/.xine/config. A
description of the ones specific to CDX are listed below.

- -
cdda.cddb_cddb_comment_format.

This gives a format used in the stream meta comment string when using
CDDB. Similar to the Unix date command, there are format specifiers
that start with a percent sign for which various information is filled
in dynamically.  The control specifiers are given as below

%a : The artist
%A : The album information 
%C : Category
%I : CDDB disk ID
%G : Genre
%M : The current MRL
%T : The track number
%t : The name
%Y : The year 19xx or 20xx
%% : a %

The default is: MRL %M, Disc Id %I

- -
cdda.cddb_cddb_title_format

This gives a format used in the GUI Title. See
cdda.cddb_cddb_comment_format above for the format specifiers.

The default is %T: %t Artist: %a, Album %A, %C (%Y)

- -
cdda.comment_format

This gives a format used in the stream meta comment string when *not* using
CDDB. Similar to the Unix date command, there are format specifiers
are a reduced those possible when using CDDB.

%M : The current MRL
%T : The track number
%% : a %

- -
cdda.cddb_email

# email given on cddb requests
# string, default: me@home

- -
cdda.cddb_enabled

# Do we use CDDB to retrieve CD information?
# bool, default: 1

- -
cdda.cddb_http

# Contact CDDB via the HTTP protocol?
# bool, default: 0

- -
cdda.cddb_port

# numeric, default: 8880

- -
cdda.cddb_server

# The server CDDB contacts to get CD info
# string, default: freedb.freedb.org

- -
cdda.comment_format

This gives a format used in the stream meta comment string when *not* using
CDDB. Similar to the Unix date command, there are format specifiers
are a reduced those possible when using CDDB.

%M : The current MRL
%T : The track number
%% : a %

The default is : %T MRL: %M Disc Id %I

- -
cdda.title_format

This gives a format used in the GUIE title when *not* using
CDDB. Similar to the Unix date command, there are format specifiers
are a reduced those possible when using CDDB and the same as for the
cdda.comment_format given above.

The default is : %T MRL: %M Disc Id %I

- -
cdda.debug

An integer (interpreted as a bit mask) which shows additional
debugging information see the section below on debugging for more
information about the bits that can be set.

- - 
cdda.default_device

# device used for cdda drive
# string, default: /dev/cdrom

- -
cdda.disk_mode

# play unit
# { track  disk }, default: 0

- -
cdda.title_format

# format for display banner (when CDDB is not available)
# string, default: Track %T %M


-----------------------------------------------------------------
Key bindings
-----------------------------------------------------------------

This CDDA understands numeric input and this can be used to select
tracks if disk_mode is 1 (disk).

Older versions of xine befofore 1-beta10 have the number bound to other
functions. I recommend binding the numbers, to well, numbers.

Key bindings are usually stored in ~/.xine/keymap. Make sure the 
"Number" keys are bound to numbers like this:

# Enter the number 0.
Number0 {
	key = 0
	modifier = none
}

# Enter the number 1.
Number1 {
	key = 1
	modifier = none
}

# Enter the number 2.
Number2 {
	key = 2
	modifier = none
}

# Enter the number 3.
Number3 {
	key = 3
	modifier = none
}

# Enter the number 4.
Number4 {
	key = 4
	modifier = none
}

# Enter the number 5.
Number5 {
	key = 5
	modifier = none
}

# Enter the number 6.
Number6 {
	key = 6
	modifier = none
}

# Enter the number 7.
Number7 {
	key = 7
	modifier = none
}

# Enter the number 8.
Number8 {
	key = 8
	modifier = none
}

# Enter the number 9.
Number9 {
	key = 9
	modifier = none
}

# Add 10 to the next entered number.
Number10add {
	key = minus
	modifier = none
}

## To have the above rebound correctly you'll have to 
## Nuke the existing stupidly thought out number 
## bindings. Here's what I have...

# Set position to beginning of current stream.
SetPosition0% {
	key = 0
	modifier = mod3
}

# Set position to 10% of current stream.
SetPosition10% {
	key = 1
	modifier = mod3
}

# Set position to 20% of current stream.
SetPosition20% {
	key = 2
	modifier = mod3
}

# Set position to 30% of current stream.
SetPosition30% {
	key = 3
	modifier = mod3
}

# Set position to 40% of current stream.
SetPosition40% {
	key = 4
	modifier = mod3
}

# Set position to 50% of current stream.
SetPosition50% {
	key = 5
	modifier = mod3
}

# Set position to 60% of current stream.
SetPosition60% {
	key = 6
	modifier = mod3
}

# Set position to 70% of current stream.
SetPosition70% {
	key = 7
	modifier = mod3
}

# Set position to 80% of current stream.
SetPosition80% {
	key = 8
	modifier = mod3
}

# Set position to 90% of current stream.
SetPosition90% {
	key = 9
	modifier = mod3
}

If this is done, you'll be able to change to that track number by
typing the number you want and hitting the numeric pad "Enter"
key. (The keyboard Enter key is by default bound to something else - I
suppose one could change that too.)

To go to the next or previous item, the keypad PgUp (keypad 9) and
PgDn (keypad 3) keys can be used. If you have made the above numeric
input changes you can prefix these by a number and it will have the
same effect as hitting the function that many times. For example,
entering "2 PgDn" (that's the keyboard 2 key followed by the keypad
PgDn key) will have go forward 2 items.

-----------------------------------------------------------------
Troubleshooting Guide
-----------------------------------------------------------------

This gives higher-level troubleshooting. More detailed and
lower-level information is given in the next section DEBUGGING. 

Problem: I don't get anything playing. 
Determination: start at step 1.

Problem: Okay, I something plays menu now. But I can't figure out how to
select track x.
Determination: start at step 5.

1. When you run the xine GUI, do you see a button somewhere below
   the H:M:S time indicator that is labeled "CDX"? If so, skip on
   to step 2.

   a) If no "CDX" button, the CDX plugin isn't loaded. Does a shared
   object exist?  The plugin shared object is called
   "xineplug_inp_cdx.so" (and has an assocated file called
   xineplug_inp_cdx.la). It should be in the directory that has
   ...xine/plugins/1.0.0 where "1.0.0" is the release number of xine.
   If this isn't around you need to build and install the plugin

   b) if xineplug_inp_vcd.so is in the fileystem that is appropriate
   for the current release of xine, you might be able check of there
   was an attempt to load it by tracking system calls. On Linux and
   other OS's) "strace" can be used to see if the file gets
   accessed. On Solaris use "truss".

   For example on Linux, amonst the many line of output when I run
   "strace -e trace=file xine" I see this amongst lots of other
   output:

   ...
   stat64("/usr/local/lib/xine/plugins/1.0.0/xineplug_inp_cdx.so", 
  {st_mode=S_IFREG|0755, st_size=761430, ...}) = 0
   ...

   The parameters inside the calls may be different depending on where
   xine is installed and what release is installed. If the the file is
   found and "opened", then the most likely thing is that there is an
   API version mismatch. This can happen if you are using a CVS
   version and the API number changes.  It's also possible that you've
   installed a different CDX plugin for a different release of
   xine-lib. If possible use a release number of xine-lib that
   matches xine-vcdx exactly.
  
   (There may also be a message may under "setup/logs", but I've found that
   there are so many plugins that it is anyone's guess where it will
   be in the volumous log, if this message is even around by the time
   all you have a chance to look at it.)

   API mismatches in xine are pretty common. In fact they are sort of
   engineered in. All plugins break whenever there is an API upgrade;
   the decision of what the API versions a plugin can handle is not up
   to the plugin. So this means you need to have a copy of a plugin
   for every API version of xine you might use and none of this code
   can be shared between API versions. 

2. (There is a CDX button displayed) When you hit "setup" you should
   see a "cdda" tab in one of the tabs at the top of the setup window.
   When you select "cdda" you should see the default settings. The
   most important one is: "default_device" On GNU/Linux, this may be
   "/dev/cdrom" and on Solaris it may be "/vol/dev/aliases/cdrom0".
   Make sure these are correct for your particular setup. For example,
   I generally play out of the DVD device and this is called /dev/dvd
   rather than /dev/cdrom.

3. (CD-DA Setup devices seems correct and there is a CD in the
   drive).  Press the MRL button to bring up a MRL window. There
   should again be a CDX button, perhaps on the side near a "file"
   button. If you press this button, you should see your CD disk light
   go on if you have one. And the CD should be read. You should get a
   list of what's on the CD.
   
   a. If not something's wrong like step 2. Another tack may be to try
   to read a disk image of a CD and thus elimate any problems with
   hardware. If this works, then this is a hardware problem. 

4. (You have a list of entries describing the CD-DA or disk-file of
   a CD-DA image.)

   There should be at least one "track" listed for the CD-DA and track
   1 will end with the digit 1.  If there are NO tracks listed then
   there may be a problem with the that particular medium. So as in
   step 3 you can try a known good sample and perhaps burn a CD from
   that. 

5. (Have a menu, but can't figure out how to select a number.)
   Are the number keys are not bound to numbers? See the section
   "Key bindings"
 
-----------------------------------------------------------------
Debugging
-----------------------------------------------------------------

**General xine debugging...

Before delving to things specific to this plugin, some preparation may
be in order. If you are going to use a debugger to track down problems
as I do, you'll probably want to compile xine-lib, xine-ui and this
plugin with debug information. Instead of "make'ing" with "make", use
"make debug" and instead of installing using "make install" use "make
install-debug". 

I use gdb to debug. Debugging xine with the entire suite of plugins
under gdb is slow because it has to read in symbol tables from all the
plugins. There are two ways to make loading faster when debugging. The
simplest is just to go to the plugin directory and remove unused
plugins. Another approach is create a new directory and make
(symbolic) links into the complete plugin directory. Then set
XINE_PATH to refer to your new directory.

**cdx debugging...

It's a fact of life that this plugin may be in an incomplete state
and/or will have bugs. So to facilitate tracking down problems we let
you see what's going on dynamically. Various debugging settings will
cause output to appear on xine's plugin log and/or "standard error"
(assuming you've run xine in a way that you can capture this).

You think of debug switches as a bit mask, that you specifiy as an
integers the various "bit" values (given in decimal) are listed below.

   name    value  description
---------- -----  -----------
   META        1  Meta information
   EVENT       2  Trace keyboard events
   MRL         4  Things involved getting lists of what's in the CD
   EXT         8  Trace external calls to the plugin routines
   CALL       16  Trace all calls
   LSN        32  Trace Logical block address changes
   INFO       64  Some informative messages. Like verbose
   CDIO      128  Debugging from libcdio
   CDDB      256  CDDB debugging 

**CD debugging...

The tool cd-info from libcdio can be used to show the contents and
analyze the contents of a CD.

