Separate title format string into cases where CDDB is enabled and where

[vlc] / doc / intf-cdda.txt

This file documents the ``Extended'' VLC CD-DA Plugin

Copyright (C) 2003 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 
-  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: 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 "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 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. 

$Id: intf-cdda.txt,v 1.3 2003/12/02 03:33:22 rocky Exp $