-Features over the older CD-DA plugin
+This file documents the ``Extended'' VLC CD-DA Plugin
+
+Copyright (C) 2003, 2004 Rocky Bernstein (rocky@panix.com)
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``Free Software'' and ``Free Software Needs
+Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.
+
+(a) The Free Software Foundation's Back-Cover Text is: ``You have
+freedom to copy and modify this GNU Manual, like GNU software. Copies
+published by the Free Software Foundation raise funds for GNU
+development.''
+
+- - - - - -
+
+Features over the older VLC CD-DA plugin
Internally I think this is much much cleaner. It uses the
libcdio for disk reading and libcddb to get CDDB information.
support)
Features:
-- Can customize the what to show in the play-list title
+- Can customize the what to show in the play-list title and author.
+- Duration of each track is shown
- Media information is shown using CDDB
- Dynamic debugging
- Will scan for a CD-ROM drive with a CD-DA loaded in it.
-----------------------------------------------------------------
-Quick start
+General Info
-----------------------------------------------------------------
-If you're new to using the plugin some, here are some common things
-that will probably trip you up.
+
+Much of what I write in this section can be found elsewhere. See for
+example http://www.pctechguide.com/08cd-rom.htm, or the libcdio
+documentation.
+
+The Sony and Philips Corporations invented and Compact Disc (CD) in
+the early 1980s. The specifications for the layout is often referred
+to by the color of the cover on the specification.
+
+The first type of CD specification that was produced was the Compact
+Disc Digital Audio (CD-DA) or just plain ``audio CD'' and is commonly
+called the ``Red Book''. Music CD's are recorded in this format which
+basically allows for around 74 minutes of audio per disc and for that
+information to be split up into *tracks*. Tracks are broken up into
+"sectors" and each sector contains 2,352 bytes. To play one 44.1 kHz
+CD-DA sampled audio second, 75 sectors are used.
+
+A CD can hold at most 99 such tracks. Between the tracks CD
+specifications require a ``2 second'' in gap (called a @term{lead-in
+gap}. This is unused space with no ``data'' similar to the space
+between tracks on an old phonograph. The word ``second'' here really
+refers to a measure of space and not really necessarily an amount of
+time. However in the special case here where you have an audio CD, the
+amount of time to play a gap of this size will take 2 seconds. Note
+this is independent of how fast your CD drive can read a sector.
+
+The beginning (or inner edge) of the CD is supposed to have a ``2
+second'' lead-in gap and there is supposed to be another ``2 second''
+*lead-out* gap at the end (or outer edge) of the CD.
+
+CD-DA ``Red Book'' Specification
+
+One can create and then write or "burn" a CD in the CD-DA format
+and in this process sometimes one writes the bytes that will appear as
+a file on a hard disk. This is called a "CD disk image". This
+plugin may be able to play this file just the same as if it were
+burned onto a CD.
+
+As there are a number of CD-burning programs, there are a number of
+CD-image formats. This plugin uses libcdio which currently understands
+the BIN/CUE disk-image format used by a popular DOS/Window mastering
+tool and a limited subset of the proprietary and unpublished form at
+used by the Nero burning software. Over time however perhaps more
+disk-image formats will be recognized.
+
+Audio CD Identification Information (CDDB)
+
+The Philips Red-Book specification allows for a Compact Disc to have a
+Media Catalog Number or MCN written on it, and probably this
+was how they CD's would be identified. Alas, very few audio discs
+actually have a Medium Catalog Number on the box, and the way the code
+is written on CD is *not* uniform across all discs!
+
+However the listening community wanted a way to identify an audio CD,
+so a database of CD information was gathered by basically making a
+``signature'' or hash from the number of tracks on a disk and a
+checksum of the bytes of the tracks. This is referred to as CDDB
+information. Using the hash the database gives information about the
+titles of the tracks, the CD album name, year it was published and so
+on. This plugin has the ability to show this information courtesy of
+libcddb written by Kris Verbeeck.
+
-----------------------------------------------------------------
MRLS:
description of the ones specific to CDDAX are listed below.
- -
-cddax-title-format
+cddax-cddb-title-format
-This gives a format used in the playlist title string.
+This gives a format used in the playlist title string when CDDB is consulted.
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 **
+ %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 **
+ %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 **
+ %t : The name
+ %Y : The year 19xx or 20xx
%% : a %
-** Only available if CDDB is enabled
-
-The default if CDDB is enabled is
+The default is
Track %T. %t - %p
-Or
- %T %M otherwise
- -
-cddax-cddb_email
+cddax-title-format
+
+This gives a format used in the playlist title string when CDDB is
+*NOT* consulted. 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
+
+ %M : The current MRL
+ %m : The CD-DA Media Catalog Number (MCN)
+ %n : The number of tracks on the CD
+ %T : The track number
+ %s : Number of seconds in this track
+ %% : a %
+
+The default is
+ %T %M
+
+- -
+cddax-cddb-email
# email given on cddb requests
# string, default: me@home
- -
-cddax-cddb_enabled
+cddax-cddb-enabled
# Do we use CDDB to retrieve CD information?
# bool, default: 1
This gives higher-level troubleshooting. More detailed and
lower-level information is given in the next section DEBUGGING.
+Problem: something doesn't work. Start at step -1.
+
+Problem: The program gets a SEGFAULT or gives core dump. Start at step
+0.
+
Problem: I don't get anything playing. I can't even get a playlist of
the CD.
Determination: start at step 1.
about the CD in the playlist.
Determination: start at step 5.
-1. Do you even have the plugin loaded?
+-1. (Something doesn't work.)
+
+ A lot of what is put here really is applicable to reporting
+ problems and troubleshooting in vlc and the concepts really
+ apply to any sort of bug reporting.
+
+ When reporting a problem it's helpful to have facts:
+
+ a) the version of vlc) you are using
+
+ b) the OS you are running on
+
+ c) the version of libcdio and/or libcddb you are using
+ versions of libcdio and libcddb can be obtained by running
+ pkg-config --modversion libcdio
+ pkg-config --modversion libcddb
+
+ d) what you input or requested (e.g. the full command line entered -
+ if it is possible to reproduce the problem by giving a
+ commandline that is desirable since it is probably the simplest
+ way to convey exactly what was requested)
+
+ People often give (some part) of an error message neglecting
+ to also include what was requested or entered that led to the
+ output.
+
+ e) The setting for this plugin. That is the values of the
+ variables that start cddax- listed above. On Unix this can
+ generally be found in ~/.vlc/vlcrc
+
+ f) Exactly the messages that were what given. You can turn
+ increase the verbosity level by setting "verbosity=2" in the
+ vlc preferences files. On Unix the preferences file is
+ generally in ~/vlc/.vlcrc but there are GUI ways to set this
+ too. Give everything that is in the message log.
+
+0. (The program gets a SEGFAULT or gives core dump.)
+
+ Get and send a stack trace.
+
+ In addition to -1. Make sure the program has been compiled with
+ debugging symbols put into the code. This is usually done by having
+ the "-g" flag set when compiling the program.
+
+ You can get a strack trace the GNU debugger using the "where"
+ command. For example on this might work:
+
+ gdb vlc *name-of-corefile*
+ where
+
+
+1. (I don't get anything playing. I can't even get a playlist of
+ the CD.)
+
+ 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,
+ you see a expandable entry under "access" labeled "cddax"? If so,
skip on to step 2.
- a) If no "cddax" expandable list, thent the CDDAX plugin isn't
+ a) If no "cddax" expandable list, then 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
+ b) if libcddax_plugin.so is in the filesystem, 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
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
+ For example on Linux, among the many line of output when I run
+ "strace -e trace=file vlc" I see this along with a lot of other
output:
...
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
+2. (There plugin was loaded and preferences found.) In the "cddax" tab
+ of preference. An important selection is "cddax-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
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
+ 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
+ to read a disk image of a CD and thus eliminate 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
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
+You think of debug switches as a bit mask, that you specify as an
integers the various "bit" values (given in decimal) are listed below.
name value description
CALL 16 all calls
LSN 32 LSN changes
SEEK 64 Seeks to set location
- CDIO 128 Debugging from CDIO
- CDDB 256 CDDB debugging
+ CDIO 128 Debugging from CDIO library routines
+ CDDB 256 debugging from CDDB library routines
**CD debugging...
The tool cd-read from libcdio can be used to show the sectors of
the CD or CD image or extract sectors.
+$Id$
projects / vlc / blobdiff