--- /dev/null
+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.
+
projects / vlc / commitdiff