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