vlc-thumb: video thumbnailer for nautilus
[vlc.git] / doc / intf-vcd.txt
1 This file documents the ``Extended'' VLC Video CD Plugin
2
3 Copyright (C) 2003, 2004 Rocky Bernstein (rocky@panix.com)
4
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.
11
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
15 development.''
16
17 -----------------------------------------------------------------
18 Quick start
19 -----------------------------------------------------------------
20
21 The newer Video CD plugin (using libcdio and vcdimager) has some
22 navigation and playback capabilities. However full integration with
23 into vlc is a bit lacking and will probably take some a bit of work
24 and time.
25
26 Although, this plugin replaces the older VCD plugin, the old plugin is
27 still built and installed and used when the newer plugin is not found.
28
29 This document describes only the newer VCD plugin.
30
31 The next section is a general overview of Video CD's in general. If
32 you are in a hurry to find out how to use this plugin or know this
33 already, this section can be skipped. 
34
35 After that we describe the terms and concepts used in the remainder
36 Again, in a hurry, this section can be skipped or skimmed. If you come
37 across a term like "segment," or "lid" that confuses you, look in
38 this section.
39
40 The next section describes the MRL format that this plugin uses. If
41 you want to know how to control where to start playing, read this.
42 Even if you are familiar with vlc MRL's, you probably want to look
43 at this section. Some of the units in a VCD are a little different
44 than those in a DVD or audio CD. 
45
46 The next section gives key bindings that are used by this
47 plugin. Again to be able to control the plugin, especially for
48 playback control, you may need to read this section. 
49
50 The next section describes the configuration parameters you can set
51 for the plugin. Most of the default values I hope are what most
52 people will want to start out with. But for fine control of the
53 defaults, read this section.
54
55 One configuration variable is the debug output. The next section
56 describes the meaning of debug flags and how to troubleshoot the
57 plugin.
58
59 -----------------------------------------------------------------
60 About VCDs, SVCDs, and XVCDs.
61 -----------------------------------------------------------------
62 From: http://www.vcdhelp.com/vcd
63
64  VCD stands for 'Video Compact Disc' and basically it is a CD that
65  contains moving pictures and sound. If you're familiar with regular
66  audio/music CDs, then you will know what a Video CD looks like. A VCD
67  has the capacity to hold up to 74/80 minutes on 650MB/700MB CDs
68  respectively of full-motion video along with quality stereo
69  sound. VCDs use a compression standard called MPEG to store the video
70  and audio. A VCD can be played on almost all standalone DVD Players
71  and of course on all computers with a DVD-ROM or CD-ROM drive with
72  the help of a software based decoder / player. It is also possible to
73  use menus and chapters, similar to DVDs, on a VCD and also simple
74  photo album/slide shows with background audio. The quality of a very
75  good VCD is about the same as a VHS tape based movie but VCD is
76  usually a bit more blurry. If you want better quality checkout
77  SVCD,CVD or DVD.
78
79 From: http://www.vcdhelp.com/svcd.htm
80
81  SVCD stands for "Super VideoCD". A SVCD is very similar to a VCD, it
82  has the capacity to hold about 35-60 minutes on 74/80 min CDs of very
83  good quality full-motion video along with up to 2 stereo audio tracks
84  and also 4 selectable subtitles. A SVCD can be played on many
85  standalone DVD Players and of course on all computers with a DVD-ROM
86  or CD-ROM drive with the help of a software based decoder / player. It
87  is also possible to use menus and chapters, similar to DVDs, on a
88  SVCD and also simple photo album/slide shows with background
89  audio. The quality of a SVCD is much better than a VCD, especially
90  much more sharpen picture than a VCD because of the higher
91  resolution. But the quality depends how many minutes you choose to
92  store on a CD, less minutes/CD generally means higher quality.
93
94 From: http://www.vcdhelp.com/xvcd.htm
95
96  XVCD stands for eXtendedVCD. XVCD has same features as VCD but it is
97  possible to use higher bitrates and higher resolution to get higher
98  video quality. XVCD is basicly everything that uses MPEG1 video, is
99  not within the VCD standard and burnt in "VCD"-Mode.
100
101  XSVCD stands for eXtendedSVCD. XSVCD has same features as SVCD but it
102  is possible to use higher bitrates and higher resolution to get
103  higher video quality. XSVCD is basicly everything that uses MPEG2
104  video, is not within the SVCD standard and burnt in "SVCD"-Mode.
105
106
107 -----------------------------------------------------------------
108 Concepts used by this plugin.
109 -----------------------------------------------------------------
110
111 The remote control of a Video CD players (or the front panel)
112 generally has special keys or buttons. The author of a Video CD can
113 assign what action to use when these buttons are pressed. They buttons
114 are:
115
116  RETURN: Often used to return to the previous menu or previouly
117  interruped video segment. 
118
119  DEFAULT: Possibly take the default selection value. This function can
120  only be assigned when the LID refers to in a "Program Selection List"
121  or "Extended Program Selection List"
122
123  NEXT: Possibly the next entry, chapter, track, or menu.
124
125  PREVIOUS: Possibly the previous entry, chapter, track, or menu.
126
127 Contiguous non-overlapping regions of a Compact Disc are called
128 "Tracks".  The sum of the tracks forms the entire CD.  The CD
129 specifications standards say that between tracks there is to be a
130 150-sector gap.
131
132 In the MRL list described below, we generally don't list the first
133 track which we would call call "Track 0", but other tools like
134 VCDimager, cdinfo, and the CD-reading world in the general call this
135 "Track 1".  This first track usually contains an ISO 9660-format
136 filesystem with metadata describing what's on the CD. It may also
137 contain "segments" or small MPEGs that generally make up still frames
138 and menus.  Aside from the segments which are merely only parts of
139 track 0, it doesn't make sense to try to "play" track 0 (or track 1
140 depending on how you want to count), which is why we don't list it.
141 It seems natural to call the first thing you would want to play "track
142 1" (which in fact is track 2 to everyone else).
143
144 There are two other units that this plugin lists and are used
145 internally. One we call an "entry". This is a starting point of a
146 track which can include the beginning of the track, and when an entry
147 points to the beginning of a track, it is equivalent to listing the
148 track. However Video CD's often have multiple entry points into a
149 track. Logically this corresponds to a "Chapter" or "Scene" of a
150 larger uninterruptable unit. One might think a CD "track" could serve
151 this purpose with a collection of tracks making up a work or
152 movie. Alas, there is "track pregap" space between tracks which appear
153 as a time gaps when hardware players go between tracks - something
154 that doesn't have to happen switching between entries because there in
155 fact is no gap.
156
157 Another unit we use is a called a "segment." These are just the
158 playable units in track 0. Segments come in fixed-length units so
159 several may be combined to form a single logical playable unit.  Still
160 frames for menus are segments. A menu doesn't have to have a
161 still-frame associated with it; a menu might be implemented as a short
162 looped movie clip.  But all still frames are segments. Also, Video CD
163 specifications allow still frames to have higher resolution than
164 motion clips. All segments reside in track 0.
165
166 A "list ID" (also called a LID and and is one greater than a Play
167 Sequence descripter or "PSD" number) combines "entries" and "segments"
168 and "tracks" together with some navigation logic. "Playback Control"
169 (acronym PBC) is simply starting playback at a particular LID, and
170 unless otherwise specified you'd start with the first playback item
171 which we call P1.
172
173 Below we will refer to an "item" as combination of a unit name (track,
174 entry, segment, playback) and a whole number.
175
176 -----------------------------------------------------------------
177 MRLS:
178 -----------------------------------------------------------------
179
180 This vlc Video CD plugin, identifies itself in the vlc GUI preferences
181 vcdx. It also registers itelf to handle a class of MRL's that start
182 with vcdx://.
183
184 The VCDX MRL takes the following form:
185
186   vcdx://[path to file or vcd device][@[letter]number]]
187
188 (Note: eventually the trailing "x" will be dropped. In MRL's "vcd"
189 works as well as "vcdx".
190
191 A simple vcdx:// runs the default item (e.g. perhaps track 1 or the
192 playback control) the default VCD device (perhaps /dev/cdrom). Whether
193 to use playback control and the default device are user-configurable.
194
195 It is however also possible to specify both Video CD device/filename
196 and the kind of item explicitly in the MRL.
197
198 For example vcdx:/dev/dvd specifies the default entry using device
199 /dev/dvd which might useful if this is your DVD which is different
200 than your CD-ROM device and your DVD drive can play CD's. And
201 vcdx://test_svcd_ntsc.cue specifies the cue file for CD image on disk.
202 (test_svcd_ntsc.bin is the corresponding bin file, but using that
203 won't work.)
204
205 After the optional device name or file name, you can name the kind of
206 unit which preceded by an '@'. An MRL which ends in an @ is like
207 not adding it at all: the default entry type and number is used. Items
208 come in 4 flavors: "Track," "Entry," "Playback," and "Segment." See
209 the preceding section for an explaination of these terms. These units
210 are indicated with the capital first letter of each type: T, E, P, S,
211 s. 
212
213 --- In the future when we are able to control MRL display: 
214 An uppercase S in the MRL display indicates a NTS segment while a
215 lowercase S indicates a PAL segment. 
216 ----
217
218 However when you enter a MRL, the case of these letters is
219 insignificant.
220
221 You can configure various things that affect MRLs are selected when
222 there is some ambiguity in the MRL name. vcdx-PBC sets whether to 
223 to use PBC in a MRL is none is given.  Another configuration
224 setting, vcdx-device, determines what device to use if that part is
225 not given. 
226
227 Some examples of MRLS are given below. In the examples, we assume the
228 following configuration settings:
229
230   vcdx-PBC=1
231   vcdx-device=/dev/cdrom
232
233 vcdx://                   - Play (navigate) default item (in this
234                             case Entry ID 0) from the default device (in this
235                             case set to /dev/cdrom)
236 vcdx://@                  - same as above
237 vcdx:///dev/cdrom@        - same effect as above since the default device
238                             is set to /dev/cdrom. 
239 vcdx:///dev/cdrom@E0      - same as above. But note that this is
240                             because we have autoplay:entry which is
241                             no longer the default value
242 vcdx:///dev/cdrom2@       - Play (navigate) the default item of /dev/cdrom2
243 vcdx:///dev/cdrom2        - should be same as above but is currently broken?
244 vcdx:///dev/cdrom2@T1     - Play Track 1 from /dev/cdrom2
245 vcdx:///dev/cdrom@S1      - Play segment 1 from /dev/cdrom. This
246                             assumes there *is* a segment 1. Check
247                             the MRL list to see if that is the case.
248 vcdx://@P1                - Play LID item 1 from default device
249                             If there is no playback control, MRL will
250                             get converted into vcdx://@E0. Again
251                             check the MRL list to see if there is a P1.
252 vcdx://@P1*               - probably same as above.
253 vcdx:///dev/cdrom@E1      - Play Entry id 1 from default device
254 vcdx://@S0                - Play segment 0 from default device
255 vcdx://@3                 - Play track 3 from default device
256 vcdx:///dev/cdrom2:1      - Play track 1 from /dev/cdrom2
257 vcdx:///tmp/ntsc.cue@     - Play default item (E0) of /tmp/ntsc.bin. Note
258                             trailing @
259 vcdx://ntsc.cue/@E0       - Play entry 0 of ntsc.bin
260 vcdx:///tmp/ntsc.nrg/@E0  - Play entry 0 of /tmp/ntsc.nrg (Nero
261                             file) Works for some simple Nero images.
262
263 -----------------------------------------------------------------
264 Key bindings and non-PBC navigation.
265 -----------------------------------------------------------------
266
267 At present vlc doesn't have special hot-keys for "NEXT", "PREVIOUS",
268 "RETURN" or "DEFAULT". So we use some of other hot-key names that
269 don't seem to correspond to anything for a VCD. The key mapping names
270 are:
271
272 VLC NAME         VCD NAME
273 --------------------------
274 NAVIGATE UP      RETURN
275 NAVIGATE DOWN    DEFAULT
276 NAVIGATE LEFT    PREVIOUS
277 NAVIGATE RIGHT   NEXT
278
279 Also this plugin understand numeric input. Since the hot-keys don't
280 have assignments for numbers, the digits on the keyboard (also
281 available from the keypad if num-lock is on) are hard-coded. Even
282 though this isn't customizable, it's probably what most people would
283 expect and want.
284
285 The enter a number just type the digits of the number. To finish
286 specifying a number use the whatever key is bound to vlc's
287 "ACTIVATE" hot key - the default value is the "Enter" key.
288
289 However the next/previous/return buttons can be prefaced with a number
290 and that has the effect of hitting that button that many times. So
291 let's say you want to go forward 5 "Chapters" and hitting the "Next"
292 key 5 times would do that Instead, you could just enter the digit 5
293 followed by the key that is assigned to "NAVIGATE RIGHT", probably the
294 right-arrow key.
295
296 If you have better suggestions as to what functions the VCD buttons
297 would be better bound to how what fixed algorithm to use when not in
298 PBC, let me know.
299
300 -----------------------------------------------------------------
301 Configuration settings:
302 -----------------------------------------------------------------
303
304 Configuration settings in xine are generally put in ~/.vlc/vlcrc, but
305 can be configured via a vlc GUI. A description of the ones specific to
306 VCDX are listed below.
307
308 - -
309
310 vcdx-device
311
312 This specifies the name of the video device that will be used by default.
313 If you don't specify anything, the plugin scan for a suitable CD-ROM
314 device containing a Video CD in it.
315
316 The default device in a MRL when none is listed. The default is
317 determined by the appropriate name for the OS that you are running.
318
319 - - 
320
321 vcd-debug
322
323 An integer (interpreted as a bit mask) which shows additional
324 debugging information see the Debugging Section below for more
325 information about the bits that can be set.
326
327 -----------------------------------------------------------------
328 Troubleshooting Guide
329 -----------------------------------------------------------------
330
331 The VCD plugin leaves a bit to be desired and has many bugs. I expect
332 that there will not be covered below. But the below is a start.
333
334 This gives higher-level troubleshooting. More detailed and
335 lower-level information is given in the next section DEBUGGING. 
336
337 Problem: something doesn't work. Start at step -1.
338
339 Problem: The program gets a SEGFAULT or gives core dump. Start at step
340 0.
341
342 Problem: I don't get anything playing. I can't even get information 
343 listed in "Media and Stream Information" or the playlist.
344 Determination: start at step 1.
345
346 Problem: Okay, I something plays menu now. But I don't see information
347 about the CD in the playlist.
348 Determination: start at step 5.
349
350
351 -1. (Something doesn't work.)
352
353    A lot of what is put here really is applicable to reporting
354    problems and troubleshooting in vlc and the concepts really
355    apply to any sort of bug reporting. 
356
357    When reporting a problem it's helpful to have facts:
358
359      a) the version of vlc) you are using
360
361      b) the OS you are running on 
362
363      c) the version of libcdio and/or libcddb you are using 
364         versions of libcdio and libcddb can be obtained by running 
365           pkg-config --modversion libcdio
366           pkg-config --modversion libvcdinfo
367
368      d) what you input or requested (e.g. the full command line entered -
369         if it is possible to reproduce the problem by giving a
370         commandline that is desirable since it is probably the simplest
371         way to convey exactly what was requested)
372    
373         People often give (some part) of an error message neglecting
374         to also include what was requested or entered that led to the
375         output.
376   
377      e) The setting for this plugin. That is the values of the
378         variables that start cddax- listed above. On Unix this can
379         generally be found in ~/.vlc/vlcrc
380   
381   
382      f) Exactly the messages that were what given. You can turn
383         increase the verbosity level by setting "verbosity=2" in the
384         vlc preferences files. On Unix the preferences file is
385         generally in ~/vlc/.vlcrc but there are GUI ways to set this
386         too. Give everything that is in the message log.
387
388 0. (The program gets a SEGFAULT or gives core dump.)
389
390    Get and send a stack trace. 
391
392    In addition to -1. Make sure the program has been compiled with
393    debugging symbols put into the code. This is usually done by having
394    the "-g" flag set when compiling the program.
395
396    You can get a strack trace the GNU debugger using the "where"
397    command. For example on this might work:
398
399      gdb vlc *name-of-corefile*
400      where
401
402
403 1. (I don't get anything playing. I can't even get information 
404     listed in "Media and Stream Information" or the playlist)
405
406    Do you even have the plugin loaded? 
407
408    When you run the vlc GUI, under Settings/Preferences you should see
409    a "plugins" expandable list and under that another "access" list do
410    you see a expandalbe entry under "access" labeled "vcdx"? If so,
411    skip on to step 2.
412
413    a) If no "vcdx" expandable list, thent the VCDX plugin isn't
414    loaded. Does a shared object exist?  The plugin shared object is
415    called "libvcdx_plugin.so" It should be in the directory that has
416    ...vlc/access. If this isn't around you need to build and install
417    the VCDX plugin.
418
419    b) if libvcdx_plugin.so is in the fileystem, there might be a
420    loader error; perhaps libcdio or libvcdinfo are not installed or
421    are the wrong version. Use ldd on the file to see that it has all
422    of the libraries dependencies satisfied. Also you might be able
423    check if there was an attempt to load it by tracking system
424    calls. On Linux and other OS's) "strace" can be used to see if the
425    file gets accessed. On Solaris use "truss". 
426
427    For example on Linux, amonst the many line of output when I run
428    "strace -e trace=file vlc" I see this amongst lots of other
429    output:
430
431    ...
432    stat64("/usr/local/lib/vlc/access/libvcdx_plugin.so", {st_mode=S_IFREG|0755, st_size=302990, ...}) = 0
433   open("/usr/local/lib/vlc/access/libvcdx_plugin.so", O_RDONLY) = 5
434
435    The parameters inside the calls may be different depending on where
436    vlc is installed and what release is installed. If the the file is
437    found and "opened", 
438   
439    There may also be a message may under "setup/logs".
440
441 2. (There plugin was loaded and preferences found).  In the "vcdx" tab
442    of preference. An important selection is "vcdx-device."  If this is
443    set to the empty string, VCDX will try to scan your drives for a
444    suitable device if the driver has the capability to scan for
445    drives. However you can set the device to something of your
446    choosing. On GNU/Linux, this may be "/dev/cdrom" and on Solaris it
447    may be "/vol/dev/aliases/cdrom0".  If you set this field, make sure
448    these are correct for your particular setup. For example, I
449    generally play out of the DVD device and this is called /dev/dvd
450    rather than /dev/cdrom.
451
452 3. (Video CD Setup devices seems correct and there is a CD in the
453    drive).  
454    
455    when you run
456       vlc vcdx://
457
458    you should see your CD disk light go on if you have one. And the CD
459    should be read. 
460    
461    a. If not something's wrong like step 2. Another tack may be to try
462    to read a disk image of a Video CD and thus elimate any problems
463    with hardware. You can get a test Video CD disk image to test here:
464
465    http://www.vcdimager.org/pub/vcdimager/examples/test_svcd/test_svcd_pal.zip
466  
467    After unzipping this run there should be files test_svcd_pal.cue 
468    and test_svcd_pal.bin. Get out of xine and run from the directory
469    that contains those files: 
470      vcdx://test_svcd_pal.cue@E0
471    
472    If you see something playing then this is a hardware problem. 
473
474 -----------------------------------------------------------------
475 Debugging
476 -----------------------------------------------------------------
477
478 **General vlc debugging...
479
480 Before delving to things specific to this plugin, some preparation may
481 be in order. You'll probably want to configure vlc with "--enable-debug".
482 plugin with debug information. Instead of "make'ing" with "make", use
483 "make debug" and instead of installing using "make install" use "make
484 install-debug". 
485
486 I use gdb to debug. Debugging vlc with the entire suite of plugins
487 under gdb is slow because it has to read in symbol tables from all the
488 plugins. There are two ways to make loading faster when debugging. The
489 simplest is just to go to the plugin directory and remove unused
490 plugins. Another approach is create a new directory and make
491 (symbolic) links into the complete plugin directory. Another way to
492 speed up gdb loading is to attach the debugger after vlc has started up
493 via a command like:
494
495   gdb -p *pid-of-vlc-process*
496
497
498 **vcdx debugging...
499
500 It's a fact of life that this plugin is in an incomplete state and has
501 bugs. So to facilitate tracking down problems we let you see what's
502 going on dynamically. Various debugging settings will cause output to
503 appear on vlc plugin log and/or "standard error" (assuming you've run
504 xine in a way that you can capture this).
505
506 You think of debug switches as a bit mask, that you specifiy as an
507 integers the various "bit" values (given in decimal) are listed below.
508
509    name        value       description
510    ------      ----------  -----------
511    meta info            1  Trace Meta information
512    event info           2  Trace keyboard events
513    MRL                  4  Things involved getting lists of what's in the VCD
514    ext call             8  Trace vlc calls to the plugin routines
515    all calls   (10)    16  Trace all calls
516    LSN         (20)    32  Trace updates to the Logical sector number
517                            (basically reads)
518    PBC         (40)    64  Trace things involved with playback control
519    libcdio     (80)   128  Turn on CDIO debugging
520    seek-set    (100)  256  Trace "seek set" calls
521    seek-cur    (200)  512  Trace "seek cur" calls
522    still       (400) 1024  Trace Still-frames
523    vcdinfo     (800) 2048  Turn on VCDINFO debugging
524
525
526 **Video CD debugging...
527
528 The tool vcd-info from the cdio branch of vcdimager can be used to
529 show the entire contents of a Video CD or selected portions of
530 that. Until the cdio branch of vcdimager is completely merged with
531 vcdimager, the cd-info branch vresion has a few more
532 features. (However consult vcdimager for complete of the program).
533
534 vcdxrip can be used to extract portions of a Video CD and or create an
535 XML description file of the Video CD. This XML file and the extracted
536 files can be used by vcdxbuild to recreate another Video CD.
537
538 And finally see also tools cd-info an cd-read from libcdio.
539
540 -----------------------------------------------------------------
541 Other references
542 -----------------------------------------------------------------
543 http://www.vcdhelp.com/
544 http://www.vcdimager.org/
545 http://www.vcdimager.org/guides/#guides
546
547 $Id$