Some basic CDDA plugin documentation.

doc/intf-cdda.txt

+Features over the older CD-DA plugin
+
+Internally I think this is much much cleaner. It uses the 
+libcdio for disk reading and libcddb to get CDDB information.
+
+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 what to show in the play-list title 
+-  Media information is shown using CDDB
+-  Dynamic debugging
+-  Will scan for a CD-ROM drive with a CD-DA loaded in it.
+
+-----------------------------------------------------------------
+Quick start
+-----------------------------------------------------------------
+If you're new to using the plugin some, here are some common things
+that will probably trip you up. 
+
+-----------------------------------------------------------------
+MRLS:
+-----------------------------------------------------------------
+
+the vlc CD-DA plugin, identifies itself in the vlc GUI as CDDAX. It
+also registers itelf to handle a class of MRL's that start with
+cddax://.
+
+The CDDAX MRL takes the following form:
+
+  cddax://[path to file or CD-DA device][@[Tt]number]]
+
+A simple cddax:// runs the default item: track 1 using the default CD
+device (perhaps /dev/cdrom). The default default device is
+user-configurable.
+
+It is however also possible to specify both Compact Disc device/filename
+and item explicitly in the MRL.
+
+For example cddax://dev/cdrom2 specifies using device /dev/cdrom2 which
+might useful if as I have /dev/cdrom is a burner and the /dev/cdrom2
+is a read-only device. And cddax://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 @ or an @ and T in either case. A MRL
+which ends in an @ 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
+
+    cddax://                   - track 1 of device: /dev/cdrom
+    cddax://@                  - same as above
+    cddax:///dev/cdrom         - probably same as above
+    cddax:///dev/cdrom2        - track 1 of /dev/cdrom2
+    cddax:///dev/cdrom2@       - same as above
+    cddax://dev/cdrom2@53      - track 53 from /dev/cdrom2
+    cddax://dev/cdrom2@T53     - Same as above
+    cddax://dev/cdrom2@t53     - Same as above
+    cddax://@2                 - track 2 from default device
+    cddax://3                  - track 3 from default device
+    cddax:///tmp/ntsc.cue      - track 1 from /tmp/ntsc.bin, (a bin/cue
+                                 disk image)
+    cddax:///tmp/ntsc.cue@     - same as above
+    cddax://tmp/ntsc.cue@      - track 1 of tmp/ntsc.bin. NOT the
+                                 the same as above unless the cwd is /.
+    cddax://ntsc.nrg           - track 1 of ntsc.nrg (a nero disk image)
+    cddax://tmp/ntsc.nrg@5     - track 5 of /tmp/ntsc.nrg
+
+  Bad MRL's
+    cddax://@x                  - x is not a number
+    cddax/tmp                   - no colon
+    cddax:/                     - must start cddax://
+
+-----------------------------------------------------------------
+Configuration settings:
+-----------------------------------------------------------------
+
+Configuration settings in vlc are generally put in ~/.vlc/vlcrc. A
+description of the ones specific to CDDAX are listed below.
+
+- -
+cddax-title-format
+
+This gives a format used in the playlist title string.
+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 album artist **
+   %A : The album information **
+   %C : Category **
+   %I : CDDB disk ID **
+   %G : Genre **
+   %M : The current MRL
+   %m : The CD-DA Media Catalog Number (MCN)
+   %n : The number of tracks on the CD
+   %p : The artist/performer/composer in the track **
+   %T : The track number **
+   %s : Number of seconds in this track
+   %t : The name **
+   %Y : The year 19xx or 20xx **
+   %% : a %
+
+** Only available if CDDB is enabled
+
+The default if CDDB is enabled is 
+  Track %T. %t - %p 
+Or 
+  %T %M otherwise
+
+- -
+cddax-cddb_email
+
+# email given on cddb requests
+# string, default: me@home
+
+- -
+cddax-cddb_enabled
+
+# Do we use CDDB to retrieve CD information?
+# bool, default: 1
+
+- -
+cddax-cddb-http
+
+# Contact CDDB via the HTTP protocol?
+# bool, default: 0
+
+- -
+cddax-cddb-port
+
+# numeric, default: 8880
+
+- -
+cddax-cddb-server
+
+# The server CDDB contacts to get CD info
+# string, default: freedb.freedb.org
+
+- -
+cddax-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.
+
+- - 
+cddax-device
+
+What to use if no drive specified. If null, we'll scan for CD
+drives with a CD-DA loaded in it.
+
+# string, default: 
+
+-----------------------------------------------------------------
+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. I can't even get a playlist of
+the CD.
+Determination: start at step 1.
+
+Problem: Okay, I something plays menu now. But I don't see information
+about the CD in the playlist.
+Determination: start at step 5.
+
+1. Do you even have the plugin loaded? 
+
+   When you run the vlc GUI, under Settings/Preferences you should see
+   a "plugins" expandable list and under that another "access" list do
+   you see a expandalbe entry under "access" labeled "cddax"? If so,
+   skip on to step 2.
+
+   a) If no "cddax" expandable list, thent the CDDAX plugin isn't
+   loaded. Does a shared object exist?  The plugin shared object is
+   called "libcddax_plugin.so" It should be in the directory that has
+   ...vlc/access. If this isn't around you need to build and install
+   the CDDAX plugin.
+
+   b) if libcddax_plugin.so is in the fileystem, there might be a
+   loader error; perhaps libcdio is not installed or
+   are the wrong version. Use ldd on the file to see that it has all
+   of the libraries dependencies satisfied. Also you might be able
+   check if 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 vlc" I see this amongst lots of other
+   output:
+
+   ...
+   stat64("/usr/local/lib/vlc/access/libcddax_plugin.so", {st_mode=S_IFREG|0755, st_size=238921, ...}) = 0
+   open("/usr/local/lib/vlc/access/libcddax_plugin.so", O_RDONLY) = 5
+
+   The parameters inside the calls may be different depending on where
+   vlc is installed and what release is installed. If the the file is
+   found and "opened", 
+  
+   There may also be a message may under "setup/logs".
+
+2. (There plugin was loaded and preferences found).  In the "cddax" tab
+   of preference. An important selection is "vcdx-device."  If this is
+   set to the empty string, CDDAX will try to scan your drives for a
+   suitable device if the driver has the capability to scan for
+   drives. However you can set the device to something of your
+   choosing. On GNU/Linux, this may be "/dev/cdrom" and on Solaris it
+   may be "/vol/dev/aliases/cdrom0".  If you set this field, 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).  Bring up the playlist. If you specified only a drive and
+   no track, you should see in the playlist a list of tracks 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. <<Fill in info about CDDB hacking>>
+
+-----------------------------------------------------------------
+Debugging
+-----------------------------------------------------------------
+
+**General vlc debugging...
+
+Before delving to things specific to this plugin, some preparation may
+be in order. You'll probably want to configure vlc with "--enable-debug".
+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 vlc 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. Another way to
+speed up gdb loading is to attach the debugger after vlc has started up
+via a command like:
+
+  gdb -p *pid-of-vlc-process*
+
+**cddax 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 vlc's plugin log and/or "standard error"
+(assuming you've run vlc 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  MRL debugging
+   EXT         8  Calls from external routines
+   CALL       16  all calls
+   LSN        32  LSN changes
+   SEEK       64  Seeks to set location
+   CDIO      128  Debugging from CDIO
+   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.
+
+The tool cd-read from libcdio can be used to show the sectors of 
+the CD or CD image or extract sectors. 
+