1 This file documents the ``Extended'' VLC CD-DA Plugin
3 Copyright (C) 2003, 2004 Rocky Bernstein (rocky@panix.com)
5 Permission is granted to copy, distribute and/or modify this document
6 under the terms of the GNU Free Documentation License, Version 1.1 or
7 any later version published by the Free Software Foundation; with the
8 Invariant Sections being ``Free Software'' and ``Free Software Needs
9 Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
10 and with the Back-Cover Texts as in (a) below.
12 (a) The Free Software Foundation's Back-Cover Text is: ``You have
13 freedom to copy and modify this GNU Manual, like GNU software. Copies
14 published by the Free Software Foundation raise funds for GNU
19 Features over the older VLC CD-DA plugin
21 Internally I think this is much much cleaner. It uses the
22 libcdio for disk reading and libcddb to get CDDB information.
25 - Can specify device as well as track.
26 - Because we use the libcdio library, the "device" can be a disk image
27 to be burned (e.g. a cdrdao bin/cue pair and some primitive Nero
31 - Can customize the what to show in the play-list title and author.
32 - Duration of each track is shown
33 - Media information is shown using CDDB
35 - Will scan for a CD-ROM drive with a CD-DA loaded in it.
37 -----------------------------------------------------------------
39 -----------------------------------------------------------------
41 Much of what I write in this section can be found elsewhere. See for
42 example http://www.pctechguide.com/08cd-rom.htm, or the libcdio
45 The Sony and Philips Corporations invented and Compact Disc (CD) in
46 the early 1980s. The specifications for the layout is often referred
47 to by the color of the cover on the specification.
49 The first type of CD specification that was produced was the Compact
50 Disc Digital Audio (CD-DA) or just plain ``audio CD'' and is commonly
51 called the ``Red Book''. Music CD's are recorded in this format which
52 basically allows for around 74 minutes of audio per disc and for that
53 information to be split up into *tracks*. Tracks are broken up into
54 "sectors" and each sector contains 2,352 bytes. To play one 44.1 kHz
55 CD-DA sampled audio second, 75 sectors are used.
57 A CD can hold at most 99 such tracks. Between the tracks CD
58 specifications require a ``2 second'' in gap (called a @term{lead-in
59 gap}. This is unused space with no ``data'' similar to the space
60 between tracks on an old phonograph. The word ``second'' here really
61 refers to a measure of space and not really necessarily an amount of
62 time. However in the special case here where you have an audio CD, the
63 amount of time to play a gap of this size will take 2 seconds. Note
64 this is independent of how fast your CD drive can read a sector.
66 The beginning (or inner edge) of the CD is supposed to have a ``2
67 second'' lead-in gap and there is supposed to be another ``2 second''
68 *lead-out* gap at the end (or outer edge) of the CD.
70 CD-DA ``Red Book'' Specification
72 One can create and then write or "burn" a CD in the CD-DA format
73 and in this process sometimes one writes the bytes that will appear as
74 a file on a hard disk. This is called a "CD disk image". This
75 plugin may be able to play this file just the same as if it were
78 As there are a number of CD-burning programs, there are a number of
79 CD-image formats. This plugin uses libcdio which currently understands
80 the BIN/CUE disk-image format used by a popular DOS/Window mastering
81 tool and a limited subset of the proprietary and unpublished form at
82 used by the Nero burning software. Over time however perhaps more
83 disk-image formats will be recognized.
85 Audio CD Identification Information (CDDB)
87 The Philips Red-Book specification allows for a Compact Disc to have a
88 Media Catalog Number or MCN written on it, and probably this
89 was how they CD's would be identified. Alas, very few audio discs
90 actually have a Medium Catalog Number on the box, and the way the code
91 is written on CD is *not* uniform across all discs!
93 However the listening community wanted a way to identify an audio CD,
94 so a database of CD information was gathered by basically making a
95 ``signature'' or hash from the number of tracks on a disk and a
96 checksum of the bytes of the tracks. This is referred to as CDDB
97 information. Using the hash the database gives information about the
98 titles of the tracks, the CD album name, year it was published and so
99 on. This plugin has the ability to show this information courtesy of
100 libcddb written by Kris Verbeeck.
103 -----------------------------------------------------------------
105 -----------------------------------------------------------------
107 the vlc CD-DA plugin, identifies itself in the vlc GUI as CDDAX. It
108 also registers itelf to handle a class of MRL's that start with
111 The CDDAX MRL takes the following form:
113 cddax://[path to file or CD-DA device][@[Tt]number]]
115 A simple cddax:// runs the default item: track 1 using the default CD
116 device (perhaps /dev/cdrom). The default default device is
119 It is however also possible to specify both Compact Disc device/filename
120 and item explicitly in the MRL.
122 For example cddax://dev/cdrom2 specifies using device /dev/cdrom2 which
123 might useful if as I have /dev/cdrom is a burner and the /dev/cdrom2
124 is a read-only device. And cddax://test_cdda.cue specifies the
125 "cuesheet" file for a CD-DA image on disk created say with cdrdao.
126 (test_cdda.bin is the corresponding bin file, but using that won't
129 After the optional device name or file name, you can name the track
130 number unit which preceded by a @ or an @ and T in either case. A MRL
131 which ends in an @ is like not adding it at all.
133 Some examples of MRLS are given below. In the examples, we assume the
134 following configuration setting:
136 cdda.default_device:/dev/cdrom
138 cddax:// - track 1 of device: /dev/cdrom
139 cddax://@ - same as above
140 cddax:///dev/cdrom - probably same as above
141 cddax:///dev/cdrom2 - track 1 of /dev/cdrom2
142 cddax:///dev/cdrom2@ - same as above
143 cddax://dev/cdrom2@53 - track 53 from /dev/cdrom2
144 cddax://dev/cdrom2@T53 - Same as above
145 cddax://dev/cdrom2@t53 - Same as above
146 cddax://@2 - track 2 from default device
147 cddax://3 - track 3 from default device
148 cddax:///tmp/ntsc.cue - track 1 from /tmp/ntsc.bin, (a bin/cue
150 cddax:///tmp/ntsc.cue@ - same as above
151 cddax://tmp/ntsc.cue@ - track 1 of tmp/ntsc.bin. NOT the
152 the same as above unless the cwd is /.
153 cddax://ntsc.nrg - track 1 of ntsc.nrg (a nero disk image)
154 cddax://tmp/ntsc.nrg@5 - track 5 of /tmp/ntsc.nrg
157 cddax://@x - x is not a number
159 cddax:/ - must start cddax://
161 -----------------------------------------------------------------
162 Configuration settings:
163 -----------------------------------------------------------------
165 Configuration settings in vlc are generally put in ~/.vlc/vlcrc. A
166 description of the ones specific to CDDAX are listed below.
169 cddax-cddb-title-format
171 This gives a format used in the playlist title string when CDDB is consulted.
172 Similar to the Unix date command, there are format specifiers
173 that start with a percent sign for which various information is filled
174 in dynamically. The control specifiers are given as below
176 %a : The album artist
177 %A : The album information
182 %m : The CD-DA Media Catalog Number (MCN)
183 %n : The number of tracks on the CD
184 %p : The artist/performer/composer in the track
185 %T : The track number
186 %s : Number of seconds in this track
188 %Y : The year 19xx or 20xx
197 This gives a format used in the playlist title string when CDDB is
198 *NOT* consulted. Similar to the Unix date command, there are format
199 specifiers that start with a percent sign for which various
200 information is filled in dynamically. The control specifiers are
204 %m : The CD-DA Media Catalog Number (MCN)
205 %n : The number of tracks on the CD
206 %T : The track number
207 %s : Number of seconds in this track
216 # email given on cddb requests
217 # string, default: me@home
222 # Do we use CDDB to retrieve CD information?
228 # Contact CDDB via the HTTP protocol?
234 # numeric, default: 8880
239 # The server CDDB contacts to get CD info
240 # string, default: freedb.freedb.org
245 An integer (interpreted as a bit mask) which shows additional
246 debugging information see the section below on debugging for more
247 information about the bits that can be set.
252 What to use if no drive specified. If null, we'll scan for CD
253 drives with a CD-DA loaded in it.
257 -----------------------------------------------------------------
258 Troubleshooting Guide
259 -----------------------------------------------------------------
261 This gives higher-level troubleshooting. More detailed and
262 lower-level information is given in the next section DEBUGGING.
264 Problem: something doesn't work. Start at step -1.
266 Problem: The program gets a SEGFAULT or gives core dump. Start at step
269 Problem: I don't get anything playing. I can't even get a playlist of
271 Determination: start at step 1.
273 Problem: Okay, I something plays menu now. But I don't see information
274 about the CD in the playlist.
275 Determination: start at step 5.
277 -1. (Something doesn't work.)
279 A lot of what is put here really is applicable to reporting
280 problems and troubleshooting in vlc and the concepts really
281 apply to any sort of bug reporting.
283 When reporting a problem it's helpful to have facts:
285 a) the version of vlc) you are using
287 b) the OS you are running on
289 c) the version of libcdio and/or libcddb you are using
290 versions of libcdio and libcddb can be obtained by running
291 pkg-config --modversion libcdio
292 pkg-config --modversion libcddb
294 d) what you input or requested (e.g. the full command line entered -
295 if it is possible to reproduce the problem by giving a
296 commandline that is desirable since it is probably the simplest
297 way to convey exactly what was requested)
299 People often give (some part) of an error message neglecting
300 to also include what was requested or entered that led to the
303 e) The setting for this plugin. That is the values of the
304 variables that start cddax- listed above. On Unix this can
305 generally be found in ~/.vlc/vlcrc
307 f) Exactly the messages that were what given. You can turn
308 increase the verbosity level by setting "verbosity=2" in the
309 vlc preferences files. On Unix the preferences file is
310 generally in ~/vlc/.vlcrc but there are GUI ways to set this
311 too. Give everything that is in the message log.
313 0. (The program gets a SEGFAULT or gives core dump.)
315 Get and send a stack trace.
317 In addition to -1. Make sure the program has been compiled with
318 debugging symbols put into the code. This is usually done by having
319 the "-g" flag set when compiling the program.
321 You can get a strack trace the GNU debugger using the "where"
322 command. For example on this might work:
324 gdb vlc *name-of-corefile*
328 1. (I don't get anything playing. I can't even get a playlist of
331 Do you even have the plugin loaded?
333 When you run the vlc GUI, under Settings/Preferences you should see
334 a "plugins" expandable list and under that another "access" list do
335 you see a expandable entry under "access" labeled "cddax"? If so,
338 a) If no "cddax" expandable list, then the CDDAX plugin isn't
339 loaded. Does a shared object exist? The plugin shared object is
340 called "libcddax_plugin.so" It should be in the directory that has
341 ...vlc/access. If this isn't around you need to build and install
344 b) if libcddax_plugin.so is in the filesystem, there might be a
345 loader error; perhaps libcdio is not installed or
346 are the wrong version. Use ldd on the file to see that it has all
347 of the libraries dependencies satisfied. Also you might be able
348 check if there was an attempt to load it by tracking system
349 calls. On Linux and other OS's) "strace" can be used to see if the
350 file gets accessed. On Solaris use "truss".
352 For example on Linux, among the many line of output when I run
353 "strace -e trace=file vlc" I see this along with a lot of other
357 stat64("/usr/local/lib/vlc/access/libcddax_plugin.so", {st_mode=S_IFREG|0755, st_size=238921, ...}) = 0
358 open("/usr/local/lib/vlc/access/libcddax_plugin.so", O_RDONLY) = 5
360 The parameters inside the calls may be different depending on where
361 vlc is installed and what release is installed. If the the file is
364 There may also be a message may under "setup/logs".
366 2. (There plugin was loaded and preferences found.) In the "cddax" tab
367 of preference. An important selection is "cddax-device." If this is
368 set to the empty string, CDDAX will try to scan your drives for a
369 suitable device if the driver has the capability to scan for
370 drives. However you can set the device to something of your
371 choosing. On GNU/Linux, this may be "/dev/cdrom" and on Solaris it
372 may be "/vol/dev/aliases/cdrom0". If you set this field, make sure
373 these are correct for your particular setup. For example, I
374 generally play out of the DVD device and this is called /dev/dvd
375 rather than /dev/cdrom.
377 3. (CD-DA Setup devices seems correct and there is a CD in the
378 drive.) Bring up the playlist. If you specified only a drive and
379 no track, you should see in the playlist a list of tracks on the CD.
381 a. If not something's wrong like step 2. Another tack may be to try
382 to read a disk image of a CD and thus eliminate any problems with
383 hardware. If this works, then this is a hardware problem.
385 4. (You have a list of entries describing the CD-DA or disk-file of
388 There should be at least one "track" listed for the CD-DA and track
389 1 will end with the digit 1. If there are NO tracks listed then
390 there may be a problem with the that particular medium. So as in
391 step 3 you can try a known good sample and perhaps burn a CD from
394 5. <<Fill in info about CDDB hacking>>
396 -----------------------------------------------------------------
398 -----------------------------------------------------------------
400 **General vlc debugging...
402 Before delving to things specific to this plugin, some preparation may
403 be in order. You'll probably want to configure vlc with "--enable-debug".
404 plugin with debug information. Instead of "make'ing" with "make", use
405 "make debug" and instead of installing using "make install" use "make
408 I use gdb to debug. Debugging vlc with the entire suite of plugins
409 under gdb is slow because it has to read in symbol tables from all the
410 plugins. There are two ways to make loading faster when debugging. The
411 simplest is just to go to the plugin directory and remove unused
412 plugins. Another approach is create a new directory and make
413 (symbolic) links into the complete plugin directory. Another way to
414 speed up gdb loading is to attach the debugger after vlc has started up
417 gdb -p *pid-of-vlc-process*
421 It's a fact of life that this plugin may be in an incomplete state
422 and/or will have bugs. So to facilitate tracking down problems we let
423 you see what's going on dynamically. Various debugging settings will
424 cause output to appear on vlc's plugin log and/or "standard error"
425 (assuming you've run vlc in a way that you can capture this).
427 You think of debug switches as a bit mask, that you specify as an
428 integers the various "bit" values (given in decimal) are listed below.
430 name value description
431 ---------- ----- -----------
432 META 1 Meta information
433 EVENT 2 Trace keyboard events
435 EXT 8 Calls from external routines
438 SEEK 64 Seeks to set location
439 CDIO 128 Debugging from CDIO library routines
440 CDDB 256 debugging from CDDB library routines
444 The tool cd-info from libcdio can be used to show the contents and
445 analyze the contents of a CD.
447 The tool cd-read from libcdio can be used to show the sectors of
448 the CD or CD image or extract sectors.