mirror of
https://code.videolan.org/videolan/vlc
synced 2024-08-27 04:21:53 +02:00
Remove cddax documentation as cddax was already removed
This commit is contained in:
parent
8c4abfd8a7
commit
ad5c94fdcb
@ -31,7 +31,6 @@ EXTRA_DIST = \
|
||||
$(man1_MANS) \
|
||||
bugreport-howto.txt \
|
||||
fortunes.txt \
|
||||
intf-cdda.txt \
|
||||
intf-vcd.txt \
|
||||
release-howto.txt \
|
||||
arm-crosscompile-howto.sgml \
|
||||
|
@ -1,450 +0,0 @@
|
||||
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$
|
Loading…
Reference in New Issue
Block a user