This file documents the ``Extended'' VLC Video CD PluginCopyright (C) 2003, 2004 Rocky Bernstein (rocky@panix.com)Permission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.1 orany later version published by the Free Software Foundation; with theInvariant Sections being ``Free Software'' and ``Free Software NeedsFree Documentation'', with the Front-Cover Texts being ``A GNU Manual,''and with the Back-Cover Texts as in (a) below.(a) The Free Software Foundation's Back-Cover Text is: ``You havefreedom to copy and modify this GNU Manual, like GNU software.  Copiespublished by the Free Software Foundation raise funds for GNUdevelopment.''-----------------------------------------------------------------Quick start-----------------------------------------------------------------The newer Video CD plugin (using libcdio and vcdimager) has somenavigation and playback capabilities. However full integration withinto vlc is a bit lacking and will probably take some a bit of workand time.Although, this plugin replaces the older VCD plugin, the old plugin isstill 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. Ifyou are in a hurry to find out how to use this plugin or know thisalready, this section can be skipped. After that we describe the terms and concepts used in the remainderAgain, in a hurry, this section can be skipped or skimmed. If you comeacross a term like "segment," or "lid" that confuses you, look inthis section.The next section describes the MRL format that this plugin uses. Ifyou 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 lookat this section. Some of the units in a VCD are a little differentthan those in a DVD or audio CD. The next section gives key bindings that are used by thisplugin. Again to be able to control the plugin, especially forplayback control, you may need to read this section. The next section describes the configuration parameters you can setfor the plugin. Most of the default values I hope are what mostpeople will want to start out with. But for fine control of thedefaults, read this section.One configuration variable is the debug output. The next sectiondescribes the meaning of debug flags and how to troubleshoot theplugin.-----------------------------------------------------------------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 canassign what action to use when these buttons are pressed. They buttonsare: 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 CDspecifications standards say that between tracks there is to be a150-sector gap.In the MRL list described below, we generally don't list the firsttrack which we would call call "Track 0", but other tools likeVCDimager, cdinfo, and the CD-reading world in the general call this"Track 1".  This first track usually contains an ISO 9660-formatfilesystem with metadata describing what's on the CD. It may alsocontain "segments" or small MPEGs that generally make up still framesand menus.  Aside from the segments which are merely only parts oftrack 0, it doesn't make sense to try to "play" track 0 (or track 1depending 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 "track1" (which in fact is track 2 to everyone else).There are two other units that this plugin lists and are usedinternally. One we call an "entry". This is a starting point of atrack which can include the beginning of the track, and when an entrypoints to the beginning of a track, it is equivalent to listing thetrack. However Video CD's often have multiple entry points into atrack. Logically this corresponds to a "Chapter" or "Scene" of alarger uninterruptable unit. One might think a CD "track" could servethis purpose with a collection of tracks making up a work ormovie. Alas, there is "track pregap" space between tracks which appearas a time gaps when hardware players go between tracks - somethingthat doesn't have to happen switching between entries because there infact is no gap.Another unit we use is a called a "segment." These are just theplayable units in track 0. Segments come in fixed-length units soseveral may be combined to form a single logical playable unit.  Stillframes for menus are segments. A menu doesn't have to have astill-frame associated with it; a menu might be implemented as a shortlooped movie clip.  But all still frames are segments. Also, Video CDspecifications allow still frames to have higher resolution thanmotion clips. All segments reside in track 0.A "list ID" (also called a LID and and is one greater than a PlaySequence descripter or "PSD" number) combines "entries" and "segments"and "tracks" together with some navigation logic. "Playback Control"(acronym PBC) is simply starting playback at a particular LID, andunless otherwise specified you'd start with the first playback itemwhich 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 preferencesvcdx. It also registers itelf to handle a class of MRL's that startwith 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 theplayback control) the default VCD device (perhaps /dev/cdrom). Whetherto use playback control and the default device are user-configurable.It is however also possible to specify both Video CD device/filenameand 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 differentthan your CD-ROM device and your DVD drive can play CD's. Andvcdx://test_svcd_ntsc.cue specifies the cue file for CD image on disk.(test_svcd_ntsc.bin is the corresponding bin file, but using thatwon't work.)After the optional device name or file name, you can name the kind ofunit which preceded by an '@'. An MRL which ends in an @ is likenot adding it at all: the default entry type and number is used. Itemscome in 4 flavors: "Track," "Entry," "Playback," and "Segment." Seethe preceding section for an explaination of these terms. These unitsare 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 alowercase S indicates a PAL segment. ----However when you enter a MRL, the case of these letters isinsignificant.You can configure various things that affect MRLs are selected whenthere is some ambiguity in the MRL name. vcdx-PBC sets whether to to use PBC in a MRL is none is given.  Another configurationsetting, vcdx-device, determines what device to use if that part isnot given. Some examples of MRLS are given below. In the examples, we assume thefollowing configuration settings:  vcdx-PBC=1  vcdx-device=/dev/cdromvcdx://                   - Play (navigate) default item (in this                            case Entry ID 0) from the default device (in this                            case set to /dev/cdrom)vcdx://@                  - same as abovevcdx:///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 valuevcdx:///dev/cdrom2@       - Play (navigate) the default item of /dev/cdrom2vcdx:///dev/cdrom2        - should be same as above but is currently broken?vcdx:///dev/cdrom2@T1     - Play Track 1 from /dev/cdrom2vcdx:///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 LID 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 devicevcdx://@S0                - Play segment 0 from default devicevcdx://@3                 - Play track 3 from default devicevcdx:///dev/cdrom2:1      - Play track 1 from /dev/cdrom2vcdx:///tmp/ntsc.cue@     - Play default item (E0) of /tmp/ntsc.bin. Note                            trailing @vcdx://ntsc.cue/@E0       - Play entry 0 of ntsc.binvcdx:///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 thatdon't seem to correspond to anything for a VCD. The key mapping namesare:VLC NAME         VCD NAME--------------------------NAVIGATE UP      RETURN