From 6378fd38a8de472e186f98f6f92bf7c507c26f82 Mon Sep 17 00:00:00 2001 From: Rocky Bernstein Date: Sun, 23 Nov 2003 17:06:43 +0000 Subject: [PATCH] Some basic help for the VCD plugin. --- doc/intf-vcd.txt | 459 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 459 insertions(+) create mode 100644 doc/intf-vcd.txt diff --git a/doc/intf-vcd.txt b/doc/intf-vcd.txt new file mode 100644 index 0000000000..c03ad80722 --- /dev/null +++ b/doc/intf-vcd.txt @@ -0,0 +1,459 @@ +----------------------------------------------------------------- +Quick start +----------------------------------------------------------------- + +The newer Video CD plugin (using libcdio and vcdimager) has some +navigation and playback capabilities. However full integration with +into vlc is a bit lacking and will probably take some a bit of work +and time. + +Although, this plugin replaces the older VCD plugin, the old plugin is +still built and installed and used when the newer plugin is not found. + +This document describes only the newer VCD plugin. + +The next section is a general overview of Video CD's in general. If +you are in a hurry to find out how to use this plugin or know this +already, this section can be skipped. + +After that we describe the terms and concepts used in the remainder +Again, in a hurry, this section can be skipped or skimmed. If you come +across a term like "segment," or "lid" that confuses you, look in +this section. + +The next section describes the MRL format that this plugin uses. If +you want to know how to control where to start playing, read this. +Even if you are familiar with vlc MRL's, you probably want to look +at this section. Some of the units in a VCD are a little different +than those in a DVD or audio CD. + +The next section gives key bindings that are used by this +plugin. Again to be able to control the plugin, especially for +playback control, you may need to read this section. + +The next section describes the configuration parameters you can set +for the plugin. Most of the default values I hope are what most +people will want to start out with. But for fine control of the +defaults, read this section. + +One configuration variable is the debug output. The next section +describes the meaning of debug flags and how to troubleshoot the +plugin. + +----------------------------------------------------------------- +About VCDs, SVCDs, and XVCDs. +----------------------------------------------------------------- +From: http://www.vcdhelp.com/vcd + + VCD stands for 'Video Compact Disc' and basically it is a CD that + contains moving pictures and sound. If you're familiar with regular + audio/music CDs, then you will know what a Video CD looks like. A VCD + has the capacity to hold up to 74/80 minutes on 650MB/700MB CDs + respectively of full-motion video along with quality stereo + sound. VCDs use a compression standard called MPEG to store the video + and audio. A VCD can be played on almost all standalone DVD Players + and of course on all computers with a DVD-ROM or CD-ROM drive with + the help of a software based decoder / player. It is also possible to + use menus and chapters, similar to DVDs, on a VCD and also simple + photo album/slide shows with background audio. The quality of a very + good VCD is about the same as a VHS tape based movie but VCD is + usually a bit more blurry. If you want better quality checkout + SVCD,CVD or DVD. + +From: http://www.vcdhelp.com/svcd.htm + + SVCD stands for "Super VideoCD". A SVCD is very similar to a VCD, it + has the capacity to hold about 35-60 minutes on 74/80 min CDs of very + good quality full-motion video along with up to 2 stereo audio tracks + and also 4 selectable subtitles. A SVCD can be played on many + standalone DVD Players and of course on all computers with a DVD-ROM + or CD-ROM drive with the help of a software based decoder / player. It + is also possible to use menus and chapters, similar to DVDs, on a + SVCD and also simple photo album/slide shows with background + audio. The quality of a SVCD is much better than a VCD, especially + much more sharpen picture than a VCD because of the higher + resolution. But the quality depends how many minutes you choose to + store on a CD, less minutes/CD generally means higher quality. + +From: http://www.vcdhelp.com/xvcd.htm + + XVCD stands for eXtendedVCD. XVCD has same features as VCD but it is + possible to use higher bitrates and higher resolution to get higher + video quality. XVCD is basicly everything that uses MPEG1 video, is + not within the VCD standard and burnt in "VCD"-Mode. + + XSVCD stands for eXtendedSVCD. XSVCD has same features as SVCD but it + is possible to use higher bitrates and higher resolution to get + higher video quality. XSVCD is basicly everything that uses MPEG2 + video, is not within the SVCD standard and burnt in "SVCD"-Mode. + + +----------------------------------------------------------------- +Concepts used by this plugin. +----------------------------------------------------------------- + +The remote control of a Video CD players (or the front panel) +generally has special keys or buttons. The author of a Video CD can +assign what action to use when these buttons are pressed. They buttons +are: + + RETURN: Often used to return to the previous menu or previouly + interruped video segment. + + DEFAULT: Possibly take the default selection value. This function can + only be assigned when the LID refers to in a "Program Selection List" + or "Extended Program Selection List" + + NEXT: Possibly the next entry, chapter, track, or menu. + + PREVIOUS: Possibly the previous entry, chapter, track, or menu. + +Contiguous non-overlapping regions of a Compact Disc are called +"Tracks". The sum of the tracks forms the entire CD. The CD +specifications standards say that between tracks there is to be a +150-sector gap. + +In the MRL list described below, we generally don't list the first +track which we would call call "Track 0", but other tools like +VCDimager, cdinfo, and the CD-reading world in the general call this +"Track 1". This first track usually contains an ISO 9660-format +filesystem with metadata describing what's on the CD. It may also +contain "segments" or small MPEGs that generally make up still frames +and menus. Aside from the segments which are merely only parts of +track 0, it doesn't make sense to try to "play" track 0 (or track 1 +depending on how you want to count), which is why we don't list it. +It seems natural to call the first thing you would want to play "track +1" (which in fact is track 2 to everyone else). + +There are two other units that this plugin lists and are used +internally. One we call an "entry". This is a starting point of a +track which can include the beginning of the track, and when an entry +points to the beginning of a track, it is equivalent to listing the +track. However Video CD's often have multiple entry points into a +track. Logically this corresponds to a "Chapter" or "Scene" of a +larger uninterruptable unit. One might think a CD "track" could serve +this purpose with a collection of tracks making up a work or +movie. Alas, there is "track pregap" space between tracks which appear +as a time gaps when hardware players go between tracks - something +that doesn't have to happen switching between entries because there in +fact is no gap. + +Another unit we use is a called a "segment." These are used in menus +an still frames. A menu doesn't have to have a still-frame associated +with it; A menu might be implimented as a short looped movie clip. +However Video CD specifications allow still frames to have higher +resolution than motion clips. And several segments can reside in track +0. + +A "playback list item" (also called a "list id or LID) combines +"entries" and "segments" and "tracks" together with some navigation +logic. "Playback Control" is simply starting playback at a particular +playback list item, and unless otherwise specified you'd start with +the first playback item which we call P1. + +Below we will refer to an "item" as combination of a unit name (track, +entry, segment, playback) and a whole number. + +----------------------------------------------------------------- +MRLS: +----------------------------------------------------------------- + +This vlc Video CD plugin, identifies itself in the vlc GUI preferences +vcdx. It also registers itelf to handle a class of MRL's that start +with vcdx://. + +The VCDX MRL takes the following form: + + vcdx://[path to file or vcd device][@[letter]number]] + +(Note: eventually the trailing "x" will be dropped. In MRL's "vcd" +works as well as "vcdx". + +A simple vcdx:// runs the default item (e.g. perhaps track 1 or the +playback control) the default VCD device (perhaps /dev/cdrom). Whether +to use playback control and the default device are user-configurable. + +It is however also possible to specify both Video CD device/filename +and the kind of item explicitly in the MRL. + +For example vcdx:/dev/dvd specifies the default entry using device +/dev/dvd which might useful if this is your DVD which is different +than your CD-ROM device and your DVD drive can play CD's. And +vcdx://test_svcd_ntsc.cue specifies the cue file for CD image on disk. +(test_svcd_ntsc.bin is the corresponding bin file, but using that +won't work.) + +After the optional device name or file name, you can name the kind of +unit which preceded by an '@'. An MRL which ends in an @ is like +not adding it at all: the default entry type and number is used. Items +come in 4 flavors: "Track," "Entry," "Playback," and "Segment." See +the preceding section for an explaination of these terms. These units +are indicated with the capital first letter of each type: T, E, P, S, +s. + +--- In the future when we are able to control MRL display: +An uppercase S in the MRL display indicates a NTS segment while a +lowercase S indicates a PAL segment. +---- + +However when you enter a MRL, the case of these letters is +insignificant. + +You can configure various things that affect MRLs are selected when +there is some ambiguity in the MRL name. vcdx-PBC sets whether to +to use PBC in a MRL is none is given. Another configuration +setting, vcdx-device, determines what device to use if that part is +not given. + +Some examples of MRLS are given below. In the examples, we assume the +following configuration settings: + + vcdx-PBC=1 + vcdx-device=/dev/cdrom + +vcdx:// - Play (navigate) default item (in this + case Entry ID 0) from the default device (in this + case set to /dev/cdrom) +vcdx://@ - same as above +vcdx:///dev/cdrom@ - same effect as above since the default device + is set to /dev/cdrom. +vcdx:///dev/cdrom@E0 - same as above. But note that this is + because we have autoplay:entry which is + no longer the default value +vcdx:///dev/cdrom2@ - Play (navigate) the default item of /dev/cdrom2 +vcdx:///dev/cdrom2 - should be same as above but is currently broken? +vcdx:///dev/cdrom2@T1 - Play Track 1 from /dev/cdrom2 +vcdx:///dev/cdrom@S1 - Play segment 1 from /dev/cdrom. This + assumes there *is* a segment 1. Check + the MRL list to see if that is the case. +vcdx://@P1 - Play Playlist item 1 from default device + If there is no playback control, MRL will + get converted into vcdx:/:E0. Again + check the MRL list to see if there is a P1. +vcdx://@P1* - probably same as above. +vcdx:///dev/cdrom@E1 - Play Entry id 1 from default device +vcdx://@S0 - Play segment 0 from default device +vcdx://@3 - Play track 3 from default device +vcdx:///dev/cdrom2:1 - Play track 1 from /dev/cdrom2 +vcdx:///tmp/ntsc.cue@ - Play default item (E0) of /tmp/ntsc.bin. Note + trailing @ +vcdx://ntsc.cue/@E0 - Play entry 0 of ntsc.bin +vcdx:///tmp/ntsc.nrg/@E0 - Play entry 0 of /tmp/ntsc.nrg (Nero + file) Works for some simple Nero images. + +----------------------------------------------------------------- +Key bindings and non-PBC navigation. +----------------------------------------------------------------- + +At present vlc doesn't have special hot-keys for "NEXT", "PREVIOUS", +"RETURN" or "DEFAULT". So we use some of other hot-key names that +don't seem to correspond to anything for a VCD. The key mapping names +are: + +VLC NAME VCD NAME +-------------------------- +NAVIGATE UP RETURN +NAVIGATE DOWN DEFAULT +NAVIGATE LEFT PREVIOUS +NAVIGATE RIGHT NEXT + +Also this plugin understand numeric input. Since the hot-keys don't +have assignments for numbers, the digits on the keyboard (also +available from the keypad if num-lock is on) are hard-coded. Even +though this isn't customizable, it's probably what most people would +expect and want. + +The enter a number just type the digits of the number. To finish +specifying a number use the whatever key is bound to vlc's +"ACTIVATE" hot key - the default value is the "Enter" key. + +However the next/previous/return buttons can be prefaced with a number +and that has the effect of hitting that button that many times. So +let's say you want to go forward 5 "Chapters" and hitting the "Next" +key 5 times would do that Instead, you could just enter the digit 5 +followed by the key that is assigned to "NAVIGATE RIGHT", probably the +right-arrow key. + +If you have better suggestions as to what functions the VCD buttons +would be better bound to how what fixed algorithm to use when not in +PBC, let me know. + +----------------------------------------------------------------- +Configuration settings: +----------------------------------------------------------------- + +Configuration settings in xine are generally put in ~/.vlc/vlcrc, but +can be configured via a vlc GUI. A description of the ones specific to +VCDX are listed below. + +- - + +vcdx-device + +This specifies the name of the video device that will be used by default. +If you don't specify anything, the plugin scan for a suitable CD-ROM +device containing a Video CD in it. + +The default device in a MRL when none is listed. The default is +determined by the appropriate name for the OS that you are running. + +- - + +vcd-debug + +An integer (interpreted as a bit mask) which shows additional +debugging information see the Debugging Section below for more +information about the bits that can be set. + +----------------------------------------------------------------- +Troubleshooting Guide +----------------------------------------------------------------- + +The VCD plugin leaves a bit to be desired and has many bugs. I expect +that there will not be covered below. But the below is a start. + +This gives higher-level troubleshooting. More detailed and +lower-level information is given in the next section DEBUGGING. + +1. 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 expandalbe entry under "access" labeled "vcdx"? If so, + skip on to step 2. + + a) If no "vcdx" expandable list, thent the VCDX plugin isn't + loaded. Does a shared object exist? The plugin shared object is + called "libvcdx_plugin.so" It should be in the directory that has + ...vlc/access. If this isn't around you need to build and install + the VCDX plugin. + + b) if libvcdx_plugin.so is in the fileystem, there might be a + loader error; perhaps libcdio or libvcdinfo are 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, amonst the many line of output when I run + "strace -e trace=file vlc" I see this amongst lots of other + output: + + ... + stat64("/usr/local/lib/vlc/access/libvcdx_plugin.so", {st_mode=S_IFREG|0755, st_size=302990, ...}) = 0 + open("/usr/local/lib/vlc/access/libvcdx_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 "vcdx" tab + of preference. An important selection is "vcdx-device." If this is + set to the empty string, VCDX 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. (Video CD Setup devices seems correct and there is a CD in the + drive). + + when you run + vlc vcdx:// + + you should see your CD disk light go on if you have one. And the CD + should be read. + + a. If not something's wrong like step 2. Another tack may be to try + to read a disk image of a Video CD and thus elimate any problems + with hardware. You can get a test Video CD disk image to test here: + + http://www.vcdimager.org/pub/vcdimager/examples/test_svcd/test_svcd_pal.zip + + After unzipping this run there should be files test_svcd_pal.cue + and test_svcd_pal.bin. Get out of xine and run from the directory + that contains those files: + vcdx://test_svcd_pal.cue@E0 + + If you see something playing then this is a hardware problem. + +----------------------------------------------------------------- +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* + + +**vcdx debugging... + +It's a fact of life that this plugin is in an incomplete state and has +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 plugin log and/or "standard error" (assuming you've run +xine in a way that you can capture this). + +You think of debug switches as a bit mask, that you specifiy as an +integers the various "bit" values (given in decimal) are listed below. + + name value description + ------ ---------- ----------- + meta info 1 Trace Meta information + event info 2 Trace keyboard events + MRL 4 Things involved getting lists of what's in the VCD + ext call 8 Trace vlc calls to the plugin routines + all calls (10) 16 Trace all calls + LSN (20) 32 Trace updates to the Logical sector number + (basically reads) + PBC (40) 64 Trace things involved with playback control + libcdio (80) 128 Turn on CDIO debugging + seek-set (100) 256 Trace "seek set" calls + seek-cur (200) 512 Trace "seek cur" calls + still (400) 1024 Trace Still-frames + vcdinfo (800) 2048 Turn on VCDINFO debugging + + +**Video CD debugging... + +The tool vcd-info from the cdio branch of vcdimager can be used to +show the entire contents of a Video CD or selected portions of +that. Until the cdio branch of vcdimager is completely merged with +vcdimager, the cd-info branch vresion has a few more +features. (However consult vcdimager for complete of the program). + +vcdxrip can be used to extract portions of a Video CD and or create an +XML description file of the Video CD. This XML file and the extracted +files can be used by vcdxbuild to recreate another Video CD. + +And finally see also tools cd-info an cd-read from libcdio. + +----------------------------------------------------------------- +Other references +----------------------------------------------------------------- +http://www.vcdhelp.com/ +http://www.vcdimager.org/ +http://www.vcdimager.org/guides/#guides + +$Id: intf-vcd.txt,v 1.1 2003/11/23 17:06:43 rocky Exp $ -- 2.39.2