+++ /dev/null
-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.
-
-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 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.
-
------------------------------------------------------------------
-General Info
------------------------------------------------------------------
-
-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:
------------------------------------------------------------------
-
-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-cddb-title-format
-
-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
- %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 %
-
-The default is
- Track %T. %t - %p
-
-- -
-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
-
-# 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: 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.
-
-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. (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 expandable entry under "access" labeled "cddax"? If so,
- skip on to step 2.
-
- 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 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
- 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, among the many line of output when I run
- "strace -e trace=file vlc" I see this along with a lot 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 "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
- 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 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
- 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 specify 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 library routines
- CDDB 256 debugging from CDDB library routines
-
-**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.
-
-$Id$
projects / vlc / commitdiff