git.sesse.net Git - vlc/blob - doc/intf-cdda.txt

   1 Features over the older CD-DA plugin
   2
   3 Internally I think this is much much cleaner. It uses the
   4 libcdio for disk reading and libcddb to get CDDB information.
   5
   6 MRL handling:
   7 -  Can specify device as well as track.
   8 -  Because we use the libcdio library, the "device" can be a disk image
   9    to be burned (e.g. a cdrdao bin/cue pair and some primitive Nero
  10    support)
  11
  12 Features:
  13 -  Can customize the what to show in the play-list title
  14 -  Media information is shown using CDDB
  15 -  Dynamic debugging
  16 -  Will scan for a CD-ROM drive with a CD-DA loaded in it.
  17
  18 -----------------------------------------------------------------
  19 Quick start
  20 -----------------------------------------------------------------
  21 If you're new to using the plugin some, here are some common things
  22 that will probably trip you up.
  23
  24 -----------------------------------------------------------------
  25 MRLS:
  26 -----------------------------------------------------------------
  27
  28 the vlc CD-DA plugin, identifies itself in the vlc GUI as CDDAX. It
  29 also registers itelf to handle a class of MRL's that start with
  30 cddax://.
  31
  32 The CDDAX MRL takes the following form:
  33
  34   cddax://[path to file or CD-DA device][@[Tt]number]]
  35
  36 A simple cddax:// runs the default item: track 1 using the default CD
  37 device (perhaps /dev/cdrom). The default default device is
  38 user-configurable.
  39
  40 It is however also possible to specify both Compact Disc device/filename
  41 and item explicitly in the MRL.
  42
  43 For example cddax://dev/cdrom2 specifies using device /dev/cdrom2 which
  44 might useful if as I have /dev/cdrom is a burner and the /dev/cdrom2
  45 is a read-only device. And cddax://test_cdda.cue specifies the
  46 "cuesheet" file for a CD-DA image on disk created say with cdrdao.
  47 (test_cdda.bin is the corresponding bin file, but using that won't
  48 work.)
  49
  50 After the optional device name or file name, you can name the track
  51 number unit which preceded by a @ or an @ and T in either case. A MRL
  52 which ends in an @ is like not adding it at all.
  53
  54 Some examples of MRLS are given below. In the examples, we assume the
  55 following configuration setting:
  56
  57 cdda.default_device:/dev/cdrom
  58
  59     cddax://                   - track 1 of device: /dev/cdrom
  60     cddax://@                  - same as above
  61     cddax:///dev/cdrom         - probably same as above
  62     cddax:///dev/cdrom2        - track 1 of /dev/cdrom2
  63     cddax:///dev/cdrom2@       - same as above
  64     cddax://dev/cdrom2@53      - track 53 from /dev/cdrom2
  65     cddax://dev/cdrom2@T53     - Same as above
  66     cddax://dev/cdrom2@t53     - Same as above
  67     cddax://@2                 - track 2 from default device
  68     cddax://3                  - track 3 from default device
  69     cddax:///tmp/ntsc.cue      - track 1 from /tmp/ntsc.bin, (a bin/cue
  70                                  disk image)
  71     cddax:///tmp/ntsc.cue@     - same as above
  72     cddax://tmp/ntsc.cue@      - track 1 of tmp/ntsc.bin. NOT the
  73                                  the same as above unless the cwd is /.
  74     cddax://ntsc.nrg           - track 1 of ntsc.nrg (a nero disk image)
  75     cddax://tmp/ntsc.nrg@5     - track 5 of /tmp/ntsc.nrg
  76
  77   Bad MRL's
  78     cddax://@x                  - x is not a number
  79     cddax/tmp                   - no colon
  80     cddax:/                     - must start cddax://
  81
  82 -----------------------------------------------------------------
  83 Configuration settings:
  84 -----------------------------------------------------------------
  85
  86 Configuration settings in vlc are generally put in ~/.vlc/vlcrc. A
  87 description of the ones specific to CDDAX are listed below.
  88
  89 - -
  90 cddax-title-format
  91
  92 This gives a format used in the playlist title string.
  93 Similar to the Unix date command, there are format specifiers
  94 that start with a percent sign for which various information is filled
  95 in dynamically.  The control specifiers are given as below
  96
  97    %a : The album artist **
  98    %A : The album information **
  99    %C : Category **
 100    %I : CDDB disk ID **
 101    %G : Genre **
 102    %M : The current MRL
 103    %m : The CD-DA Media Catalog Number (MCN)
 104    %n : The number of tracks on the CD
 105    %p : The artist/performer/composer in the track **
 106    %T : The track number **
 107    %s : Number of seconds in this track
 108    %t : The name **
 109    %Y : The year 19xx or 20xx **
 110    %% : a %
 111
 112 ** Only available if CDDB is enabled
 113
 114 The default if CDDB is enabled is
 115   Track %T. %t - %p
 116 Or
 117   %T %M otherwise
 118
 119 - -
 120 cddax-cddb_email
 121
 122 # email given on cddb requests
 123 # string, default: me@home
 124
 125 - -
 126 cddax-cddb_enabled
 127
 128 # Do we use CDDB to retrieve CD information?
 129 # bool, default: 1
 130
 131 - -
 132 cddax-cddb-http
 133
 134 # Contact CDDB via the HTTP protocol?
 135 # bool, default: 0
 136
 137 - -
 138 cddax-cddb-port
 139
 140 # numeric, default: 8880
 141
 142 - -
 143 cddax-cddb-server
 144
 145 # The server CDDB contacts to get CD info
 146 # string, default: freedb.freedb.org
 147
 148 - -
 149 cddax-debug
 150
 151 An integer (interpreted as a bit mask) which shows additional
 152 debugging information see the section below on debugging for more
 153 information about the bits that can be set.
 154
 155 - -
 156 cddax-device
 157
 158 What to use if no drive specified. If null, we'll scan for CD
 159 drives with a CD-DA loaded in it.
 160
 161 # string, default:
 162
 163 -----------------------------------------------------------------
 164 Troubleshooting Guide
 165 -----------------------------------------------------------------
 166
 167 This gives higher-level troubleshooting. More detailed and
 168 lower-level information is given in the next section DEBUGGING.
 169
 170 Problem: I don't get anything playing. I can't even get a playlist of
 171 the CD.
 172 Determination: start at step 1.
 173
 174 Problem: Okay, I something plays menu now. But I don't see information
 175 about the CD in the playlist.
 176 Determination: start at step 5.
 177
 178 1. Do you even have the plugin loaded?
 179
 180    When you run the vlc GUI, under Settings/Preferences you should see
 181    a "plugins" expandable list and under that another "access" list do
 182    you see a expandalbe entry under "access" labeled "cddax"? If so,
 183    skip on to step 2.
 184
 185    a) If no "cddax" expandable list, thent the CDDAX plugin isn't
 186    loaded. Does a shared object exist?  The plugin shared object is
 187    called "libcddax_plugin.so" It should be in the directory that has
 188    ...vlc/access. If this isn't around you need to build and install
 189    the CDDAX plugin.
 190
 191    b) if libcddax_plugin.so is in the fileystem, there might be a
 192    loader error; perhaps libcdio is not installed or
 193    are the wrong version. Use ldd on the file to see that it has all
 194    of the libraries dependencies satisfied. Also you might be able
 195    check if there was an attempt to load it by tracking system
 196    calls. On Linux and other OS's) "strace" can be used to see if the
 197    file gets accessed. On Solaris use "truss".
 198
 199    For example on Linux, amonst the many line of output when I run
 200    "strace -e trace=file vlc" I see this amongst lots of other
 201    output:
 202
 203    ...
 204    stat64("/usr/local/lib/vlc/access/libcddax_plugin.so", {st_mode=S_IFREG|0755, st_size=238921, ...}) = 0
 205    open("/usr/local/lib/vlc/access/libcddax_plugin.so", O_RDONLY) = 5
 206
 207    The parameters inside the calls may be different depending on where
 208    vlc is installed and what release is installed. If the the file is
 209    found and "opened",
 210
 211    There may also be a message may under "setup/logs".
 212
 213 2. (There plugin was loaded and preferences found).  In the "cddax" tab
 214    of preference. An important selection is "vcdx-device."  If this is
 215    set to the empty string, CDDAX will try to scan your drives for a
 216    suitable device if the driver has the capability to scan for
 217    drives. However you can set the device to something of your
 218    choosing. On GNU/Linux, this may be "/dev/cdrom" and on Solaris it
 219    may be "/vol/dev/aliases/cdrom0".  If you set this field, make sure
 220    these are correct for your particular setup. For example, I
 221    generally play out of the DVD device and this is called /dev/dvd
 222    rather than /dev/cdrom.
 223
 224 3. (CD-DA Setup devices seems correct and there is a CD in the
 225    drive).  Bring up the playlist. If you specified only a drive and
 226    no track, you should see in the playlist a list of tracks on the CD.
 227
 228    a. If not something's wrong like step 2. Another tack may be to try
 229    to read a disk image of a CD and thus elimate any problems with
 230    hardware. If this works, then this is a hardware problem.
 231
 232 4. (You have a list of entries describing the CD-DA or disk-file of
 233    a CD-DA image.)
 234
 235    There should be at least one "track" listed for the CD-DA and track
 236    1 will end with the digit 1.  If there are NO tracks listed then
 237    there may be a problem with the that particular medium. So as in
 238    step 3 you can try a known good sample and perhaps burn a CD from
 239    that.
 240
 241 5. <<Fill in info about CDDB hacking>>
 242
 243 -----------------------------------------------------------------
 244 Debugging
 245 -----------------------------------------------------------------
 246
 247 **General vlc debugging...
 248
 249 Before delving to things specific to this plugin, some preparation may
 250 be in order. You'll probably want to configure vlc with "--enable-debug".
 251 plugin with debug information. Instead of "make'ing" with "make", use
 252 "make debug" and instead of installing using "make install" use "make
 253 install-debug".
 254
 255 I use gdb to debug. Debugging vlc with the entire suite of plugins
 256 under gdb is slow because it has to read in symbol tables from all the
 257 plugins. There are two ways to make loading faster when debugging. The
 258 simplest is just to go to the plugin directory and remove unused
 259 plugins. Another approach is create a new directory and make
 260 (symbolic) links into the complete plugin directory. Another way to
 261 speed up gdb loading is to attach the debugger after vlc has started up
 262 via a command like:
 263
 264   gdb -p *pid-of-vlc-process*
 265
 266 **cddax debugging...
 267
 268 It's a fact of life that this plugin may be in an incomplete state
 269 and/or will have bugs. So to facilitate tracking down problems we let
 270 you see what's going on dynamically. Various debugging settings will
 271 cause output to appear on vlc's plugin log and/or "standard error"
 272 (assuming you've run vlc in a way that you can capture this).
 273
 274 You think of debug switches as a bit mask, that you specifiy as an
 275 integers the various "bit" values (given in decimal) are listed below.
 276
 277    name    value  description
 278 ---------- -----  -----------
 279    META        1  Meta information
 280    EVENT       2  Trace keyboard events
 281    MRL         4  MRL debugging
 282    EXT         8  Calls from external routines
 283    CALL       16  all calls
 284    LSN        32  LSN changes
 285    SEEK       64  Seeks to set location
 286    CDIO      128  Debugging from CDIO
 287    CDDB      256  CDDB debugging
 288
 289 **CD debugging...
 290
 291 The tool cd-info from libcdio can be used to show the contents and
 292 analyze the contents of a CD.
 293
 294 The tool cd-read from libcdio can be used to show the sectors of
 295 the CD or CD image or extract sectors.
 296