This file documents the ``Extended'' VLC Video CD Plugin

Copyright (C) 2003, 2004 Rocky Bernstein (rocky@panix.com)

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software'' and ``Free Software Needs
Free 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 have
freedom to copy and modify this GNU Manual, like GNU software. Copies
published by the Free Software Foundation raise funds for GNU
development.''
----------------------------------------------------------------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 just the
playable units in track 0. Segments come in fixed-length units so
several may be combined to form a single logical playable unit. Still
frames for menus are segments. A menu doesn't have to have a
still-frame associated with it; a menu might be implemented as a short
looped movie clip. But all still frames are segments. Also, Video CD
specifications allow still frames to have higher resolution than
motion clips. All segments reside in track 0.
A "list ID" (also called a LID and and is one greater than a Play
Sequence 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, 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://
vcdx://@
vcdx:///dev/cdrom@
vcdx:///dev/cdrom@E0

- Play (navigate) default item (in this

case Entry ID 0) from the default device (in this
case set to /dev/cdrom)
- same as above
- same effect as above since the default device
is set to /dev/cdrom.
- same as above. But note that this is
because we have autoplay:entry which is

vcdx:///dev/cdrom2@
vcdx:///dev/cdrom2
vcdx:///dev/cdrom2@T1
vcdx:///dev/cdrom@S1

vcdx://@P1

vcdx://@P1*
vcdx:///dev/cdrom@E1
vcdx://@S0
vcdx://@3
vcdx:///dev/cdrom2:1
vcdx:///tmp/ntsc.cue@

vcdx://ntsc.cue/@E0
vcdx:///tmp/ntsc.nrg/@E0 -

no longer the default value

Play (navigate) the default item of /dev/cdrom2
should be same as above but is currently broken?
Play Track 1 from /dev/cdrom2
Play segment 1 from /dev/cdrom. This
assumes there *is* a segment 1. Check
the MRL list to see if that is the case.
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.
probably same as above.
Play Entry id 1 from default device
Play segment 0 from default device
Play track 3 from default device
Play track 1 from /dev/cdrom2
Play default item (E0) of /tmp/ntsc.bin. Note
trailing @
Play entry 0 of ntsc.bin
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.
Problem: something doesn't work. Start at step -1.
Problem: The program gets a SEGFAULT or gives core dump. Start at step
0.
Problem: I don't get anything playing. I can't even get information
listed in "Media and Stream Information" or the playlist.
Determination: start at step 1.
Problem: Okay, I something plays menu now. But I don't see information
about the CD in the playlist.
Determination: start at step 5.
-1. (Something doesn't work.)
A lot of what is put here really is applicable to reporting
problems and troubleshooting in vlc and the concepts really
apply to any sort of bug reporting.
When reporting a problem it's helpful to have facts:
a) the version of vlc) you are using

b) the OS you are running on

c) the version of libcdio and/or libcddb you are using
versions of libcdio and libcddb can be obtained by running
pkg-config --modversion libcdio
pkg-config --modversion libvcdinfo
d) what you input or requested (e.g. the full command line entered if it is possible to reproduce the problem by giving a
commandline that is desirable since it is probably the simplest
way to convey exactly what was requested)
People often give (some part) of an error message neglecting
to also include what was requested or entered that led to the
output.
e) The setting for this plugin. That is the values of the
variables that start cddax- listed above. On Unix this can
generally be found in ~/.vlc/vlcrc
f) Exactly the messages that were what given. You can turn
increase the verbosity level by setting "verbosity=2" in the
vlc preferences files. On Unix the preferences file is
generally in ~/vlc/.vlcrc but there are GUI ways to set this
too. Give everything that is in the message log.
0. (The program gets a SEGFAULT or gives core dump.)
Get and send a stack trace.
In addition to -1. Make sure the program has been compiled with
debugging symbols put into the code. This is usually done by having
the "-g" flag set when compiling the program.
You can get a strack trace the GNU debugger using the "where"
command. For example on this might work:
gdb vlc *name-of-corefile*
where
1. (I don't get anything playing. I can't even get information
listed in "Media and Stream Information" or the playlist)
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
-----meta info
event info
MRL
ext call
all calls
LSN

value
---------1
2
4
8
(10)
16
(20)
32

PBC
libcdio
seek-set
seek-cur
still
vcdinfo

(40)
(80)
(100)
(200)
(400)
(800)

64
128
256
512
1024
2048

description
----------Trace Meta information
Trace keyboard events
Things involved getting lists of what's in the VCD
Trace vlc calls to the plugin routines
Trace all calls
Trace updates to the Logical sector number
(basically reads)
Trace things involved with playback control
Turn on CDIO debugging
Trace "seek set" calls
Trace "seek cur" calls
Trace Still-frames
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$