From: Rémi Denis-Courmont Date: Tue, 9 Feb 2010 21:56:42 +0000 (+0200) Subject: Remove cddax documentation as cddax was already removed X-Git-Tag: 1.1.0-ff~230 X-Git-Url: https://git.sesse.net/?a=commitdiff_plain;h=ad5c94fdcb61376593969de006633fe457ece041;p=vlc Remove cddax documentation as cddax was already removed --- diff --git a/doc/Makefile.am b/doc/Makefile.am index 0b1fbc42e1..60397ae892 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -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 \ diff --git a/doc/intf-cdda.txt b/doc/intf-cdda.txt deleted file mode 100644 index 47a0669c47..0000000000 --- a/doc/intf-cdda.txt +++ /dev/null @@ -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. <> - ------------------------------------------------------------------ -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$