--- /dev/null
+-----------------------------------------------------------------
+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 $
projects / vlc / commitdiff