     [file version.texi not included]

This file documents GNU VCDImager, The GNU Video CD Authoring Tools.

Copyright (C) Herbert Valerio Riedel <hvr@gnu.org>

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 no Invariant Sections, one Front-Cover Text: "GNU VCDImager by Herbert Valerio Riedel et al." and one Back-Cover Text: "GNU VCDImager can be obtained at http://www.gnu.org/software/vcdimager/. The author is reachable at hvr@gnu.org".  A copy of the license is included in the section entitled "GNU Free Documentation License".

Introduction
************

This manual describes the GNU VCDImager (see http://www.gnu.org/software/vcdimager/) package, a tool-set for authoring, disassembling and analyzing Video CD's and Super Video CD's.

Supplied Tools
==============

The following command-line tools are provided with this package:

vcdimager
     Simple front-end, allowing for easy command-line controlled generation of basic VCD and SVCD disc images without an intermediate XML description.

vcd-info
     Selectively shows detailed information about the structure a Video CD. See Introduction (The GNU Video CD Info Dump Program).

vcdxgen
     XML VCD-description generator, with a command-line interface similar to the classic vcdimager front-end. See vcdxgen.

vcdxbuild
     Builds a VCD/SVCD according to a supplied XML description and files containing the MPEG program streams referred to in the XML description. See vcdxbuild.

vcdxrip
     Disassembles a given VCD or SVCD disc into a XML description and the contained MPEG program streams. See vcdxrip.

vcdxminfo
     This is a debugging tool for displaying some MPEG properties, as conceived by internal library libvcd and libvcdinfo. See vcdxminfo.

cdxa2mpeg
     A program to strip the RIFF header on CD-XA-format tracks.  See cdxa2mpeg.

The generated CD images created are suitable for being burnt on to CD-R, by the use of a CD-recording program which recognizes the BIN/CUE-format, such as cdrdao (see http://cdrdao.sourceforge.net), for instance.

Features
========

Features of the back-end library (the core of the GNU VCDImager package consists of a private library named libvcd and public library named libvcdinfo, the front-ends are just user interfaces to the exported C-API), on which all front-ends rely, include:

  * Support for Video CD 1.1 and 2.0 disc format.

  * Support for Super Video CD 1.0 and HQ Video CD 1.0 (based on the IEC-62107 specification with some extensions defined in the super-set SVCD System Specification 1.0. Some support for the deprecated Chinese SVCD format is available through option switches.) disc format.

  * Full PBC support, including fully customizable play lists, (multi default) selection lists and end lists.

  * Support for segment (play) items (SPI).

  * Support for up to 98 sequence items (MPEG tracks) per (Super) Video CD.

  * Support for additional entry points into sequence items.

  * Support for defining auto pause points in sequence items and segment items.

  * General facility for adding files as mode 2 form 1 and mixed form XA sectors to the ISO-9660 file-system and setting some labels in the ISO-9660 PVD

  * Supports 99 minute CD-R media (...though most devices will have problems with such an out-of-specification media. You may want use the --sector-2336 option for images longer than 80 minutes).

  * Image input support for GNU/Linux ioctl()-based cdrom devices, BIN/CUE images and NRG images.

Video CD Concepts
*****************

This chapter gives some background information regarding the underlying Video CD technology.

Warning: All information in this chapter is presented without any warranty of accuracy or correctness. You are encouraged to send corrections and improvements for this manual to bug-vcdimager@gnu.org.

Overview
========

The Video Compact Disc (Video CD or VCD) is a standardized digital video storage format. It is based on the commonly available Compact Disc technology, which allows for low cost video authoring. Video CD's can be played in most DVD standalone player, dedicated VCD players and finally, modern Personal Computers with multimedia support.

Anatomy of Video CD's
=====================

Basically a Video CD is made up of CD-ROM XA sectors, i.e. CD-ROM mode 2 form 1 & 2 sectors. Non-MPEG data is stored in mode 2 form 1 sectors with a user data area of 2048 byte, which have a similiar L2 error correction and detection (ECC/EDC) to CD-ROM mode 1 sectors. While realtime MPEG streams is stored in CD-ROM mode 2 form 2 sectors, which by have no L2 ECC, yield a ~14% greater user data area consisting of 2324 bytes (actually raw mode 2 sectors have a 2336 byte user data area, but parts of it are used for error codes and headers when using the mode 2 form 1 or form 2 configurations.)

Warning: Realtime MPEG streams on Video CD's are only protected by L2 error detection (but no correction!), EDC, and CIRC encoding. Thus Video CD's are more easily affected by scratches and alike on the CD-ROM media surface.

In general, a Video CD is made up of several mode 2 (and optionally CD-DA) tracks. The layout of a Video CD is as follows:

  * lead-in area containing the TOC.

  * Mandatory pre-gap consisting of 150 sectors (00:00:00 -- 00:01:74).

  * ISO-9660 data track. The beginning of this track is defined to have the LSN 0. See The ISO-9660 Track.

       * ISO-9660 structure at 00:02:00 consisting of 16 empty sectors, primary volume descriptor (PVD) and directory records with file pointers to information area structures (described below) and external pointers to MPEG/CD-DA tracks following the ISO-9660 data track.

       * Optional karaoke area at 00:03:00. (not supported yet by vcdimager)

       * Video CD information area at 00:04:00.

       * Optional segment play item area with MPEG items aligned in 150 sector segments. There can be up to 1980 segments on a disc.

       * Optional program and data file area, for additional files added to the ISO-9660 track.

  * Up to 98 MPEG mode 2 form 2 tracks wrapped in front and rear margin (Margins seem to be used, in order to compensate for inaccurate sector addressing issues on CD-ROM media. Interestingly, they have been abandoned for the Super Video CD.) empty sectors and preceded by (at least) 150 empty sector pre-gaps.

  * 150 sector post-gap after the last mpeg track, as required by the ECMA-130 standard.

  * Up to 97 (the maximum number of tracks on a Video CD must not exceed 99 tracks) CD-DA tracks. (not supported yet by vcdimager)

  * Lead-out area.

Known Video CD Flavors
======================

There are different Video CD flavors commonly used. The following sections tries to explain the differences amongst them.

See also http://www.dvdrhelp.com/vcd and http://www.dvdrhelp.com/svcd.

Video CD 1.1
------------

This is the most basic Video CD specification dating back to 1993 (actually this flavor was based on the Karaoke-CD, which was the first MPEG based CD-ROM format.), which has the following characteristics:

  * One mode 2 mixed form ISO-9660 track containing file pointers to the information areas.

  * Up to 98 multiplex-ed MPEG-1 audio/video streams or CD-DA audio tracks.

  * Up to 500 MPEG sequence entry points used as chapter divisions.

The Video CD specification requires the multiplex-ed MPEG-1 stream to have a CBR of less than 174300 bytes (1394400 bits) per second (2324 bytes of payload per sector * 75 sectors per second = 174300 bytes per second) in order to accommodate single speed CD-ROM drives. The specification allows for the following two resolutions (Actually even PAL resolution works depending on the playing device):

  * 352 x 240 @ 29.97 fps (NTSC SIF).

  * 352 x 240 @ 23.976 fps (FILM SIF).

The CBR MPEG-1, layer II audio stream is fixed at 224 kbps with 1 stereo or 2 mono channels.  It is recommended to keep the video bit-rate under 1151929.1 bps (It should be noted, that in addition to the audio stream and the video stream, there are also bits consumed by the program stream encapsulation which have to be taken into account for bit-rate calculations).

Video CD 2.0
------------

About two years after the Video CD 1.1 specification came out, an improved Video CD 2.0 standard was published in 1995. This one added the following items to the features already available in the Video CD 1.1 specification:

  * Support for MPEG segment play items (SPI), consisting of still pictures, motion pictures and/or audio (only) streams was added. See Segment Items.

  * Support for interactive playback control (PBC) was added.

  * Support for playing related access by providing a scan point index file was added. (/EXT/SCANDATA.DAT)

  * Support for closed captions.

  * Support for mixing NTSC and PAL content.

By adding PAL support to the Video CD 1.1 specification, the following resolutions became available:

  * 352 x 240 @ 29.97 fps (NTSC SIF).

  * 352 x 240 @ 23.976 fps (FILM SIF).

  * 352 x 288 @ 25 fps (PAL SIF).

For segment play items the following audio encodings became available:

  * Joint stereo, stereo or dual channel audio streams at 128, 192, 224 or 384 kbit/sec bit-rate.

  * Mono audio streams at 64, 96 or 192 kbit/sec bit-rate.

Also the possibility to have audio only streams and still pictures (in addition to the resolutions already defined for motion video, also high resolutions are available for still pictures, which are 704 x 480 (NTSC Full D1) and 704 x 576 (PAL Full D1)) was provided. The bit-rate of multiplex-ed streams should be kept under (Alas it seems, that for strict Video CD 2.0 compliance, it's required to pad the stream exactly to 1x muxrate. The Super Video CD format does not have this flaw.) 174300 bytes/sec (except for single still picture items) in order to accommodate single speed drives.

Extended Video CD
-----------------

Also known as XVCD, this is not an official standard. It's actually just a name for VCD's which do not conform with the official standards in order to use the additional performance of the DVD decoders and thus achieve better image quality. Such an XVCD may be unsupported by many available stand-alone playing devices.

See also http://www.dvdrhelp.com/xvcd.htm

Super Video CD 1.0
------------------

With the upcoming of the DVD-V media, a new VCD standard had to be published in order to be able to keep up with technology, so the Super Video CD specification was called into life 1999.

In the midst of 2000 a full subset (The features left out in this subset are: subtitles, command lists, extended pbc (hotspots and disc changer support).) of this Super Video CD specification was published as IEC-62107.

As the most notable change over Video CD 2.0 a switch from MPEG-1 CBR to MPEG-2 VBR encoding for the video stream was performed. The following new features---based on the Video CD 2.0 specification---are:

  * Use of MPEG-2 encoding instead of MPEG-1 for the video stream.

  * Allowed VBR encoding of MPEG-1 audio stream.

  * Higher resolutions (see below) for video stream resolution.

  * Up to 4 overlay graphics and text (OGT) sub-channels for user switchable subtitle displaying (There is also a non-compliant subtitle format widely used, having its origins in the forgotten China Video Disc or Chaoji VCD (CVD) specification, which is said to have been a competitor for the Video CD 2.0 successor. See http://www.dvdrhelp.com/forum/userguides/98177.php. Vcdimager recognizes both formats.) in addition to the already existing closed caption facility.

  * Command lists for controlling the SVCD virtual machine.

For the Super Video CD, only the following two resolutions are supported for motion video and (low resolution) still pictures (the same high resolutions as defined for Video CD 2.0 apply for Super Video CD's):

  * 480 x 480 @ 29.97 fps (NTSC 2/3 D1).

  * 480 x 576 @ 25 fps (PAL 2/3 D1).

See also http://www.dvdrhelp.com/svcd for another description of SVCD and http://www.dvdrhelp.com/glossary for a description of the acronyms used above.

HQ Video CD 1.0
---------------

This is actually just a minor variation defined in IEC-62107 on the Super Video CD 1.0 format for compatibility with current products in the market. It differs from the Super Video CD 1.0 format in the following items:

  * The system profile tag field in /SVCD/INFO.SVD is set to 1 instead of 0.

  * The system identification field value in /SVCD/INFO.SVD is set to HQ-VCD instead of SUPERVCD.

  * /EXT/SCANDATA.DAT is mandatory instead of being optional.

  * /SVCD/SEARCH.DAT is optional instead of being mandatory.

Extended Super Video CD
-----------------------

Just like the XVCD, and thus also known as XSVCD, this is not an official standard and may not work with all playing devices supporting SVCD's.

The ISO-9660 Track
==================

Primary Volume Descriptor
-------------------------

This ISO-9660 sector located at sector LSN 16 contains general information about the ISO-9660 file-system, such as volume label, the application used to create the CD, the preparer, the publisher, file-system size, pointer to the root directory and so on...

Directory Structure
-------------------

/VCD & /SVCD Directory
......................

This directories (/SVCD is used on Super Video CD's) contain file entries to structures contained in the information area of a (Super) Video CD.

/VCD/INFO.VCD
     General video disc information (e.g. album id, size of volume set and number of MPEG items)

/VCD/ENTRIES.VCD
     Entry point table.

/VCD/LOT.VCD
     List ID Offset Table into PSD.VCD (only allowed for Video CD 2.0 discs with PBC)

/VCD/PSD.VCD
     Play sequence descriptor file (only allowed for Video CD 2.0 discs with PBC). This file may contain so-called lists (selection lists, play lists and end lists) which represent the PBC.

/SVCD/INFO.SVD
/SVCD/ENTRIES.SVD
/SVCD/LOT.SVD
/SVCD/PSD.SVD
     These are the corresponding file names on Super Video CD's, and fulfill the same purpose as those defined for the Video CD 2.0 format.

/SVCD/SEARCH.DAT
     This file, mandatory for Super Video CD's, contains access point sector addresses. See Access Point Sectors.

/SVCD/TRACKS.SVD
     In this file additional information (e.g. playing time and stream characteristics) about each sequence track is recorded.

/MPEGAV & /MPEG2 Directory
..........................

This file contains file entries pointing to the sequence items contained in the tracks after the ISO-9660 track.

/CDDA Directory
...............

This file contains file entries pointing to optional CDDA tracks after the ISO-9660 track. This feature is not available for Super Video CD's.

/SEGMENT Directory
..................

This directory contains file entries to segment play items. See Segment Items.

/EXT Directory
..............

/EXT/LOT_X.VCD
/EXT/PSD_X.VCD
     These are only defined for Video CD 2.0, and contain the extended PBC, which adds area definitions for pointer based selection and/or highlighting of selection areas. (On Super Video CD's the extended PBC has been merged into the main /SVCD/PSD.SVD file)

/EXT/SCANDATA.DAT
     This file is optional, and defined (but with a different format) for Video CD 2.0 and Super Video CD 1.0 formats. It contains playing time related access information very similar to the /SVCD/SEARCH.DAT file.

/EXT/CAPTnn.DAT
     Closed caption data file entries.

/CDI Directory
..............

This directory is provided for CD-i player applications. (Only useful for Video CD's)

Constraints on MPEG streams
===========================

GNU VCDImager expects MPEG streams in a format suitable for (Super) Video CD production. Only a few cases where the MPEG streams fail to adhere to this requirement are detected, thus it's up to the user to ensure that the constraints are fulfilled. All MPEG streams are expected to be packetized program streams.

Video CD
--------

The Video CD specification requires the multiplex-ed MPEG-1 stream to have a bit rate of about 174300 bytes per second. The video stream is required to have one of the following resolutions:

  * 352 x 240 @ 29.97 fps (NTSC).

  * 352 x 240 @ 23.976 fps (FILM).

  * 352 x 288 @ 25 fps (PAL) (not supported on VCD 1.x!).

See also http://www.dvdrhelp.com/forum/userguides/94382.php and http://www.dvdrhelp.com/glossary for a description of the acronyms used above.

The audio stream must be MPEG-1 layer II, fixed to a 224 kbits/sec CBR with 1 joint stereo, stereo or dual channel audio stream, and a sampling rate of 44.1 kHz at 16 bit resolution.

Super Video CD
--------------

When creating Super Video CD images MPEG-2 VBR streams are expected with a maximum allowed bit-rate of approximately 2.6 mbits/sec.  The following video resolutions are (officially) supported (actually you can try other resolutions as well, but then you are leaving the SVCD specification behind you...):

  * 480 x 480 @ 29.97 fps (NTSC).

  * 480 x 576 @ 25 fps (PAL).

The audio stream must be MPEG-1 layer II, with a bit-rate ranging from 32 to 384 kbits/sec bit-rate (i.e. the audio stream is allowed to be VBR!) with up to 2 stereo or 4 mono channels, or 1 extended MPEG-1/2 multichannel (5+1) surround sound stream.

Scan Information Data
.....................

According to the specification, it is mandatory for Super Video CD's (It seems to be optionally supported for the Video CD 2.0) to encode scan information data into user data blocks in the picture layer of all intra coded picture. It can be used by playing devices for implementing fast forward & fast reverse scanning.

The already existing scan information data can be updated by enabling the update scan offsets option. See <option> Element.

SVCD Subtitles
..............

There exist two major subtitle formats for SVCD's, of which only one---Overlay Graphics Text or OGT---is officially supported.  The non-compliant one has it's origin in the so-called CVD format, a competitor for the Video CD 2.0 successor. The real SVCD subtitle format is part of the Super Video Specification, wheras the CVD-style subtitle format is not. Alas the latter one is more widely used, due to older pre-SVCD aged software only supporting the non-compliant CVD subtitle format.

Compliant SVCD subtitles are transported in a private_stream_1 stream with only the private_data_id 0x70 (While AC3 tracks use the private_data_id 0x80+, DVD subtitles 0x20 onwards and CVD subtitles 0x00 and up.). The sub_stream_id is used to distinguish between the 4 available subtitle channels.

As of the time of writing, there is only a proof of concept implementation (read hack) for creating proper SVCD subtitles. The source code is available from the contribs download directory, but its use is not recommended for production use. If you are searching for a new free software project, you could take this as an idea...

Common Constraints
------------------

Alignment
.........

The MPEG program streams should be aligned to 2324 byte MPEG packet boundaries (i.e. pack headers must be repeated every 2324 bytes, starting on byte 0). If the pack headers should happen not be aligned on 2324 byte boundaries, GNU VCDImager will try (aligning only works, if MPEG packets are not bigger than 2324 bytes.) to align them on the fly while issuing a warning that padding was needed. Warning: Padding the MPEG streams causes the bit-rate at which the data is read to be increased, this may lead to undesirable effects.

If the image generation process should abort with an MPEG related error message, it maybe either due to a bug or due to a corrupted or non-compliant MPEG stream coding. In this case re-encoding or re-multiplexing may help.

Access Point Sectors
....................

An Access Point Sector, APS, is an MPEG video sector on the VCD/SVCD which is suitable to be jumped to directly. APS are required for entry points and scantables.

APS have to fulfill the requirement to precede every I-frame by a GOP header which shall be preceded by a sequence header in its turn. The start codes of these 3 items are required to be contained all in the same mpeg pack/sector, thus forming a so-called access point sector.

This requirement can be relaxed by enabling the relaxed aps option, i.e. every sector containing an I-frame will be regarded as an APS. Warning: The sequence header is needed for a playing device to figure out display parameters, such as display resolution and frame rate, relaxing the aps requirement may lead to non-working entry points.

Play Items
==========

Play items are the MPEG payload on (Super) Video CD's. Sequences are useful for seamless play of larger video sections. However they can't be used for playing still frames. Segments on the other hand, are better for smaller items in interactive applications and can be used for still frames which are often used in menus.

Sequence Items
--------------

Each sequence is put in its own CD track. Motion video stream is required, with optionally up to 2 audio streams.

Advantages
..........

  * Can be directly accessed without requiring PBC.

  * Size of of sequence is not broken up into 150-sector units as it is with a segment.

  * Entry points which allow access to ``Chapters'' or ``Scenes'' within the larger segment unit.

Disadvantages
.............

  * Pre-gap of 150 empty sectors.

  * Limit of 98 sequences.

  * Must contain motion video (and audio for Video CD 2.0) --- no still frames!

Segment Items
-------------

Segment items are stored in the so-called SPI area, which consists of up to 1980 allocation units which are called segments. Each segment consists of 150 XA form 2 sectors.  Thus the SPI area can contain up to 658 MB of real-time data (1980 * 150 * 2324 = 690228000 bytes).

A segment (play) item is a MPEG stream stored in one or more consecutive segments. A segment item can be

  * MPEG video with optional MPEG audio.

  * MPEG encoded still pictures with optional MPEG audio.

  * MPEG audio only. (Which allows for several hours of audio only play back to fit on a CD-ROM.)

Advantages
..........

  * Up to 1980 segment items possible.

  * Still pictures and audio only MPEG streams allowed.

  * No pre-gaps.

Disadvantages
.............

  * Only accessible through PBC.

  * Segment item size limited by SPI area size.

  * Segment item size is fixed to 150 sectors (the same as the gap between tracks) which may be wasteful of space. If you have a large number of small motion videos, it might be advantageous to combine them into a track and use entry points into the track. ``Continued'' segments allow for logical segments (something you refer to as a segment in authoring) to be larger than 150 segments. However breaking a logical segments up into many small physical segments is not as clean as having one physical unit for one logical unit. And there may be additional fragmentation in the form of internal sector padding.

Playback Control
================

Playback control, PBC, is available for Video CD 2.0 and Super Video CD 1.0 disc formats. PBC allows control of the playback of play items (sequence items and segment items) and the possibility of interaction with the user through the remote control or some other input device available.

Function Keys for Interaction
-----------------------------

The following keys are usually found on the remote control belonging to the playing device.

NEXT
     May also look like >>| on the remote control.

PREVIOUS
     May also look like |<< on the remote control.

DEFAULT
     This key is usually mapped to the > or PLAY key.

RETURN
     This key may be mapped to the STOP key.

NUMERIC
     This is actually a pseudo key, representing the numeric keys 0, 1, ..., 9.

Linear Playback
---------------

This playback mode is active, when the PSD is not interpreted. In this mode, the NUMERIC key causes to start playback at the entry in ENTRY.VCD/ENTRY.SVD with the index number pressed. The NEXT and PREVIOUS keys play the next or previous entry in that the entry file. This mode allows for compliant playing devices to honor the entry points defined as chapter division markers (in fact even when the play item is contained in a play-list it should allow to jump between the entry points with the NEXT/PREVIOUS keys.). Alas, only a few playing devices are capable of honoring Video CD chapters.

PBC Lists
---------

The control structures involved in PBC are called lists and are stored in the play sequence descriptor file.

Play List
.........

A Play list is basically a collection of play items which are to be played in the order specified. Play lists allow to define target lists for the NEXT, PREVIOUS and RETURN keys on the remote control. Navigation for NEXT, PREVIOUS and RETURN are associated with the entire play-list. Thus, navigation is not updated if an entry passes through to the next entry, but only when passing from one list id to another.

Selection List
..............

Selection lists can be used to offer a user selection based on numeric (NUMERIC) input or---if available---pointer device based selection, while showing a play item.

All of the navigation units available in a play list (NEXT, PREVIOUS, RETURN can be used in a selection list. But in contrast to a play list, there are additional features: menu selection (mentioned above), random selection, default target (DEFAULT), timeout target and looping.

As with play lists, the navigation is associated with the entire list id. Thus, navigation is not updated if an entry passes through to the next entry; only when passing from one list id to another.

Hot-spots
.........

The Video CD format allows for so-called hot-spots in selection lists, which are used to define areas on the screen for selection targets, which can be used for pointer device based selection in addition to the NUMERIC input, and/or for highlighting of areas on the screen on selection.

The coordinate system used in menu-selection areas divides the entire viewable part of the screen into coordinates along the x and y axes from (x1,y1)=(0,0) in the upper left to the lower right (x2,y2)=(255,255), regardess the screen resolution or aspect ratio.

Alas menu-selection areas and menu highlighting, however useful may not supported among playing devices.

Multi Default Selection List
............................

Multi default selection lists are a special variant of selection lists which allow for defining different DEFAULT key targets, depending on which section of the play item the playback is currently in. The various sections are defined by using entry points which mark the boundaries.

End List
........

An end list can be used to terminate the interpretation of the PBC information.

Command List
............

Command lists are an optional feature defined for Super Video CD's, allowing to execute opcodes in a virtual machine, allowing for enhanced interactivity.

Applications
------------

...to be written...

Reference
*********

Tools
=====

vcdimager
---------

This is the classic front-end, which is maintained only for ease of use and because it does not relay on libxml2 and thus may be the only built front-end. vcdimager does not create a dummy PBC anymore as in the past. It is recommended to familiarize with the XML front-ends, in order to be able to use the extended features offered by GNU VCDImager.

There are a few command-line options for vcdimager at the moment, please issue vcdimager --help for an actual list of available options.

vcd-info
--------

Selectively shows detailed information about the structure a Video CD. This might be helpful in diagnosing problems. This program was originally called vcddebug. See Introduction (The GNU Video CD Dump Program).

vcdxgen
-------

This tool works almost like the vcdimager tool, except that it creates an intermediate XML description, instead of directly building the disc image. This XML can be used as a starting point for customization.

The XML file can then be fed to vcdxbuild for building the actual image file(s).

FIXME: write more

Adding Files to the Video CD
............................

Files can be added to the ISO file-system, that is the first track of the Video CD, by making use of the command-line options --add-file=FILE,ISO_FILENAME and --add-file-2336=FILE,ISO_FILENAME.  The latter option allows you to include files containing the complete user data of mode 2 CD-ROM sectors  (8 bytes for sub-header, 2324 bytes payload (which contains 276 bytes ECC for form 1) and finally 4 bytes for EDC).

The path name given as ISO_FILENAME determines where to link the file in the file-system of the Video CD. The given path name must be a valid ISO-9660 file name with the following restrictions:

  * The Character set is restricted to upper case letters, numbers, underscore _, dot . and slash /, see ISO646 d-Characters.

  * The maximum file name length is restricted to 31 characters, the directory nesting level is restricted to 8 and the maximum path length is limited to 255 characters.

  * File names must contain exactly one dot. (if no file name extension is supposed to exist the dot must be placed as a trailing dot.)

  * ISO-9660 conformance level 1 restrictions apply, i.e. file names are restricted to 8.3 characters.

  * The path-name must not begin or end with a slash nor should it contain slashes following directly each other.

If the parent directory for a file entry does not exist it will be created automatically on demand.

CD-i Support
............

There is no specific CD-i support in GNU VCDImager. But you can use the general facilities for adding a custom CD-i player application.

If you happen to have a CD-i application consisting of the files cdi_imag.rtf, cdi_text.fnt, cdi_vcd.app and cdi_vcd.cfg, with cdi_vcd.app being the main application executable, you could add the following lines to your ~/.popt popt (see documentation for popt for more information about option aliasing) aliasing file (add it to /etc/popt if the setting should be available system-wide)

     vcdimager alias --cdi \
         --iso-application-id "CDI/CDI_VCD.APP;1" \
         --add-file-2336 /usr/share/cdi/cdi_imag.rtf,CDI/CDI_IMAG.RTF \
         --add-file      /usr/share/cdi/cdi_text.fnt,CDI/CDI_TEXT.FNT \
         --add-file      /usr/share/cdi/cdi_vcd.app,CDI/CDI_VCD.APP \
         --add-file      /usr/share/cdi/cdi_vcd.cfg,CDI/CDI_VCD.CFG

vcdxbuild
---------

This program allows to actually build a disc image, based on a given XML description and the files referenced therein. It can be thought of a Video CD compiler for XML descriptions of Video CD's.

FIXME: write more

vcdxrip
-------

See Introduction (The GNU Video CD Ripping Program).

vcdxminfo
---------

This tool allows to show basic properties of MPEG streams as seen by the back-end library. Dumping of all APS contained in the stream is supported as well.

FIXME: write more

cdxa2mpeg
---------

A program to strip the RIFF header on CD-XA format tracks containing a RIFF header.

On Microsoft Windows, people would extract the payload tracks of Video CD's (e.g the tracks other than the first one) by simply copying the .dat/.mpg files as seen in the filesystem of a (Video) CD.

Since many MPEG players will play tracks copied this way, people tend to think of these as an MPEG files, but they are not. Instead they have a RIFF container around the MPEG stream, including some mode2 sector headers prepended to each MPEG ``sector''. Presumably the RIFF container is automatically inserted by the Operating System or filesystem; it isn't part of a Video CD.

In such a setting, cdxa2mpeg will extract the MPEG portion by stripping off the (inserted) RIFF container and mode2 sector headers.

The name cdxa2meg refers to the fact that the program reads the CD-XA format tracks and in such a circumstance where there is a RIFF header, strips that off ``2'' make an MPEG file.

The ability to see or copy the .dat/.mpg requires some sort of filesystem support to read or show the CD Mode2 XA tracks. Depending on the Operating System and filesystem support, seeing MPEG tracks or having the contained in a RIFF might not available or applicable.

A better, more universal way to extract MPEGs from a Video CD is to use the --tracks option of see vcdxrip.

Video CD XML Description
************************

The DTD the XML description conforms to, can be downloaded from http://www.gnu.org/software/vcdimager/videocd.dtd.

This chapter is merely a reference. Pointers to examples and more practical information about the XML structure used in vcdimager are available at http://www.vcdimager.org/.

The use of vcdxgen is recommended as a starting point point, when creating an advanced XML description. (Graphical user interfaces to aid XML editing are in development, if you want to join the GUI development group, please get into contact with me at <hvr@gnu.org>.)

XML Simplified Rules
====================

  * All attribute values must be quoted.

  * White space within content, including line breaks, is significant.

  * All start tags (<pbc>) must have corresponding end tags (</pbc>).

  * Tags without content and those which are empty elements must use the />-notation, e.g.: <next-volume-use-lid2 />.

  * Elements must not overlap; they may be nested, however.

  * Element names are case sensitive: <videocd> and <VideoCD> are two different entities.

DTD Notation Reference
======================

Each section of the description of the Video CD XML format begins with a fragment from the Video CD DTD. The following table gives a simplified (and incomplete) reference for the notational syntax.

#PCDATA
     parsed character data, i.e. only text without sub-elements allowed

EMPTY
     empty, i.e. no sub-element allowed

()
     grouping

A?
     A or nothing (A is optional, but at most one A)

A+
     one or more A's (at least one)

A*
     zero or more A's (A optional, but could be several A's)

(A | B | C)
     either A or B or C (but only one)

(A, B, C)
     first A, followed by B, then C (all, and in this order)

(A & B)
     both A and B, in any order

Video CD XML Conventions
========================

Time Values
-----------

All time related values---<wait>, <autowait>, <playtime>, <start-time-offset>, <entry> and <auto-pause>---are given in seconds.

For the <wait> and <autowait> time entries the values given are rounded to values of the following set:

-1
     meaning an infinite wait time. Negative values get rounded to -1.

0
     meaning no wait time.

1
     ranging from 1 to 60 in steps of 1, representing the time to wait in whole seconds.

60
     ranging from 60 to 2000 in steps of 10, representing the time to wait in whole seconds.

2000
     maximum wait time of 2000 seconds (33 minutes 20 seconds). Values larger will be truncated to this maximum wait time.

For <loop> and <playtime> the value 0 means repeat forever and play until end accordingly.

Item IDs
--------

Items and their associated IDs fall into two categories, play items and PSD items. Every reference to an ID has to be of the right class, otherwise the reference can't be resolved, due to a failing look up. A play item can be any of the following:

  * play nothing item, (omitted ref attribute, e.g.: <play-item />).

  * sequence item, <sequence-item>.

  * entry point into sequence item, <entry>.

  * segment item segment play item, <segment-item>.

Whereas a PSD item is required to be one of:

  * disabled, (omitted ref attribute, e.g.: <select />).

  * selection list, <selection>.

  * play list, <playlist>.

  * end list, <endlist>.

<videocd> Root
==============

     <!ELEMENT videocd                       (option*,
                                              info,
                                              pvd,
                                              filesystem?,
                                              segment-items?,
                                              sequence-items,
                                              pbc?)>
     <!ATTLIST videocd
       class        CDATA  #REQUIRED
       version      CDATA  #REQUIRED
       xmlns        %URI;  #FIXED 'http://www.gnu.org/software/vcdimager/1.0/'
     >

     <!ENTITY % URI "CDATA">

class
version

     Supported combinations of CLASS and VERSION are listed below:

     CLASS   VERSION   Description
     vcd    1.0
     Video CD 1.0/Karaoke CD experimental
     vcd    1.1
     Video CD 1.1
     vcd    2.0
     Video CD 2.0
     svcd    1.0
     Super Video CD 1.0 (IEC-62107)
     hqvcd    1.0
     HQ Video CD 1.0 (IEC-62107)

xmlns
     The xmlns attribute defines the XML name-space.

     <?xml version="1.0"?>
     <!DOCTYPE videocd PUBLIC "-//GNU//DTD VideoCD//EN"
               "http://www.gnu.org/software/vcdimager/videocd.dtd">
     <videocd xmlns="http://www.gnu.org/software/vcdimager/1.0/"
              class="svcd" version="1.0">
     ...
     </videocd>

<option> Element
----------------

     <!ELEMENT option                        EMPTY>
     <!ATTLIST option
       name         CDATA  #REQUIRED
       value        CDATA  #IMPLIED
     >

The following option NAME are recognized.

svcd vcd30 mpegav
     Rename /MPEG2 folder on SVCDs to (non-compliant) /MPEGAV.

     Allowed value content: true, false. Default: false.

svcd vcd30 entrysvd
     Enables the use of the (deprecated) signature ENTRYSVD instead of ENTRYVCD for the file /SVCD/ENTRY.SVD.

     Allowed value content: true, false. Default: false.

svcd vcd30 tracksvd
     Enables the use of the (deprecated) chinese /SVCD/TRACKS.SVD format which differs from the format defined in the IEC-62107 specification. The differences are most exposed on SVCDs containing more than one video track.

     Allowed value content: true, false. Default: false.

track pregap

     Used to set the track pre-gap for all tracks (except for the first one, which is hardwired to 150 sectors) in sectors globally. The specification requires the pre-gaps to be at least 150 sectors long.

     Allowed value content: [1..300]. Default: 150.

track front margin

     Set's the front margin for sequence items. For Video CD 1.0/1.1/2.0 this margin should be at least 15 sectors long.

     Allowed value content: [0..150]. Default: 30 for Video CD 1.0/1.1/2.0, otherwise (i.e. Super Video CD 1.0 and HQ-VCD 1.0) 0.

track rear margin

     Set's the rear margin for sequence items. For Video CD 1.0/1.1/2.0 this margin should be at least 15 sectors long.

     Allowed value content: [0..150]. Default: 45 for Video CD 1.0/1.1/2.0, otherwise 0.

leadout pregap

     This option (Should have been better named data track post-gap.)  allows to set the amount of empty sectors added before the lead-out area begins, i.e. the amount of post-gap sectors. The ECMA-130 specification requires the last data track before the lead-out to carry a post-gap of at least 150 sectors, which is used as default for this parameter.

     Some operating systems may encounter I/O errors due to read-ahead issues when reading the last mpeg track if this parameter is set to low.

     Allowed value content: [0..300]. Default: 150.

leadout pause

     DEPRECATED. Use leadout pregap instead. This option is equivalent to setting the leadout pregap option to the (default) value 150.

     Allowed value content: true, false. Default: true.

relaxed aps
     This controls whether APS constraints are strict or relaxed. See Access Point Sectors.

     Allowed value content: true, false. Default: false.

update scan offsets
     This controls whether to update the scan data information contained in the MPEG-2 video streams (It is required, that the stream has already user data groups with scan information data, in order for this feature to work). See Scan Information Data.

     Allowed value content: true, false. Default: false.

     ...
     <videocd xmlns=...
       <option name="relaxed aps" value="true"/>
       <info>
     ...

<info> Container
----------------

     <!ELEMENT info                          (album-id?,
                                              volume-count?,
                                              volume-number?,
                                              next-volume-use-sequence2?,
                                              next-volume-use-lid2?,
                                              restriction?,
                                              start-time-offset*)>

     <!ELEMENT album-id                      (#PCDATA)>
     <!ELEMENT volume-count                  (#PCDATA)>
     <!ELEMENT volume-number                 (#PCDATA)>
     <!ELEMENT next-volume-use-sequence2     EMPTY>
     <!ELEMENT next-volume-use-lid2          EMPTY>
     <!ELEMENT restriction                   (#PCDATA)>
     <!ELEMENT start-time-offset             (#PCDATA)>

The <info> section allows to customize the information contained in the VCD/INFO.VCD or VCD/INFO.SVD.

<album-id>
     Name of the album (An album is defined as a series of discs which contain related content) which the discs belongs to. This id is used in conjunction with the following elements to decide whether a disc is the next volume of the currently played one.

     The Content restricted to upto 16 d-characters, see ISO646 d-Characters.

<volume-count>
     Total number of volumes (discs) in the album identified by <album-id>.

     Allowed content: [1..65535]. Default: 1.

<volume-number>
     Ordinal number of the volume (disc) in the album.

     Allowed content: [0..65535]. Default: 1.

The following elements are only supported for Video CD 2.0, Super Video CD 1.0 and HQ Video CD 1.0.

<next-volume-use-sequence2/>
     If PBC interpretation is disabled, start the next disc if it has the same <album-id> at the second sequence instead of the first.

<next-volume-use-lid2/>
     If PBC is present and interpretation enabled, start the next disc if it has the same <album-id> at the second PBC list instead of the first one.

<restriction>
     Restriction category. This element allows to set viewing restrictions which may be interpreted by the playing device. The allowed range goes from 0, i.e. unrestricted, to 3, i.e. restriction category 3. (The exact meaning of the restriction categories is depending on the interpreting playing device.)

<start-time-offset>
     Only supported for Super Video CD 1.0 and HQ Video CD 1.0. Up to 5 <start-time-offset> may be defined, which represent the start time offsets for the first 5 discs of an album. not implemented yet

     ...
       <info>
         <album-id>GNU_WARS_EP9</album-id>
         <volume-count>2</volume-count>
         <volume-number>1</volume-number>
         <next-volume-use-sequence2/>
       </info>
     ...

<pvd> Container
---------------

     <!ELEMENT pvd                           (volume-id?,
                                              system-id?,
                                              application-id?,
                                              preparer-id?,
                                              publisher-id?)>

     <!ELEMENT volume-id                     (#PCDATA)>
     <!ELEMENT system-id                     (#PCDATA)>
     <!ELEMENT application-id                (#PCDATA)>
     <!ELEMENT preparer-id                   (#PCDATA)>
     <!ELEMENT publisher-id                  (#PCDATA)>

This part of the XML structure describes the primary volume descriptor of the disc.

<volume-id>
     Volume label of the CD-ROM. Content restricted to up to 32 d-characters, see ISO646 d-Characters. This is label usually shows up on computer systems as volume label.

<system-id>
     System id of the CD-ROM. Content restricted to up to 32 a-characters. Should be set to CD-RTOS CD-BRIDGE for Video CD's for CD-i compatibility.  This fields content is ignored by vcdimager and always set to CD-RTOS CD-BRIDGE.

<application-id>
     Defines the application pathname for CD-i playing devices.

<preparer-id>
     This field is used by vcdimager to put a version string on the Video CD, regardless of the content given in the XML description which is ignored.

<publisher-id>
     Data Preparer Identifier for the CD-ROM. Content restricted to up to 128 a-characterssee ISO646 a-Characters.

     ...
       <pvd>
         <volume-id>GNU_WARS_EP9_1_OF_2</volume-id>
         <system-id>CD-RTOS CD-BRIDGE</system-id>
         <publisher-id>John Doe</publisher-id>
       </pvd>
     ...

<filesystem> Container
----------------------

     <!ELEMENT filesystem                    (folder*,
                                              file*)>

This section of the XML description allows for the creation of additional folders and files into the ISO-9660 filesystem on the Video CD. See Adding Files to the Video CD.

<folder> Element/Container
..........................

     <!ELEMENT folder                        (name,
                                              folder*,
                                              file*)>

     <!ELEMENT name                          (#PCDATA)>

<name>
     Directory name in the ISO-9660 domain.

     ...
       <filesystem>
         <folder>
           <name>CDI</name>
           <file src=...>
     ...
         </folder>
       </filesystem>
     ...

<file> Element
..............

     <!ELEMENT file                          (name)>
     <!ATTLIST file
       src          %URI;  #REQUIRED
       format       (form1|mixed) "form1"
     >
     <!ELEMENT name                          (#PCDATA)>

<name>
     Filename in the ISO-9660 domain.

src
     Source location of the file.

format
     Whether file is an ordinary form1 file, or a mixed form real-time file containing the sector information in 2336 byte blocks.

     ...
         <folder>
           <name>CDI</name>
           <file src="/usr/share/cdi/cdi_imag.rtf" format="mixed">
             <name>CDI_IMAG.RTF</name>
           </file>
           <file src="/usr/share/cdi/cdi_text.fnt">
             <name>CDI_TEXT.FNT</name>
           </file>
     ...

<segment-items> Container
-------------------------

     <!ELEMENT segment-items                 (segment-item)+>

Only supported for Video CD 2.0, Super Video CD 1.0 and HQ Video CD 1.0.

<segment-item> Element
......................

     <!ELEMENT segment-item                  (auto-pause)*>
     <!ATTLIST segment-item
       id           ID     #REQUIRED
       src          %URI;  #REQUIRED
     >

     <!ELEMENT auto-pause                    (#PCDATA)>

<segment-item>
     Element representing a segment item. Segment play items need to be referenced from the <pbc> section in order to be accessible at all.

id
     Id string to be referenced in ref attributes.

src
     This attribute specifies the external file name of the item, i.e. the location of the file containing the MPEG stream to be included.

<auto-pause>
     See description in <sequence-item>.

     ...
       <segment-items>
     ...
         <segment-item src="stills/splash.mpg" id="seg-still-splash" />

         <segment-item src="animations/intro.mpg" id="seg-animation-intro" />

         <segment-item src="animations/intra.mpg" id="seg-animation-intra" />

         <segment-item src="animations/extro.mpg" id="seg-animation-extro" />
     ...
       <segment-items>
     ...

<sequence-items> Container
--------------------------

     <!ELEMENT sequence-items                (sequence-item)+>

<sequence-item> Element
.......................

     <!ELEMENT sequence-item                 (default-entry?,
                                              entry*,
                                              auto-pause*)>
     <!ATTLIST sequence-item
       id           ID     #IMPLIED
       src          %URI;  #REQUIRED
     >

     <!ELEMENT auto-pause                    (#PCDATA)>

     <!ELEMENT default-entry EMPTY>
     <!ATTLIST default-entry
       id           ID     #REQUIRED
     >

     <!ELEMENT entry                         (#PCDATA)>
     <!ATTLIST entry
       id           ID     #IMPLIED
     >

<sequence-item>
     Element representing a sequence item. Each sequence item corresponds to a single track in the resulting disc.

id
     ID value referenced in ref attributes.

src
     This attribute specifies the external file name of the item, i.e. MPEG stream, to be included.

<auto-pause>
     This element specifies where to insert auto pause points, whose wait time is controlled by play lists' <autowait>. The time is given in seconds from the beginning of the sequence.

<default-entry>
     Represents the mandatory default entry point pointing to the start of the sequence (Referencing the default entry point id should be equivalent to referencing the sequence id. Depending on the firmware of the playing device, the sequence id may reflect the start of the sequence as defined by the TOC, while the default entry id gets defined by the address defined in the ENTRY.VCD or ENTRY.SVD).

<entry>
     Defines an additional entry point into the sequence item. Up to 99 entry points (including the default entry point) can be defined per sequence, while only a maximum of 500 entry points (every sequence point has automatically an entry point defined, which must be subtracted from the maximum of 500 entry points) can be present in the whole disc. The entry point time is given in seconds from the beginning of the sequence.  If referenced from PBC the sequence which contains the entry point is played from the entry point to the end of the sequence, not to the next entry point! Similarly navigation values do not change if the next entry point is passed. See Access Point Sectors.

id
     Play item ID value referenced in ref attributes.

     ...
       <sequence-items>
     ...
         <sequence-item src="videos/movie.mpg" id="seq-movie">
           <default-entry id="ent-movie-0" />
           <entry id="ent-movie-1">90.32</entry>
           <entry id="ent-movie-2">710</entry>
           <entry id="ent-movie-3">1760.5</entry>
           <entry id="ent-movie-4">3050</entry>
         </sequence-item>

         <sequence-item src="videos/trailer1.mpg" id="seq-trailer-1" />

         <sequence-item src="videos/trailer2.mpg" id="seq-trailer-2">
           <auto-pause>15.300</auto-pause>
           <auto-pause>260.7</auto-pause>
         </sequence-item>
     ...
       <sequence-items>
     ...

<pbc> Container
---------------

     <!ELEMENT pbc                           (selection|
                                              playlist|
                                              endlist)+>

     <!ENTITY % pbcattrs
     " id           ID     #REQUIRED
       rejected     (true|false) 'false'"
     >

     <!ENTITY % XY "CDATA">

     <!ENTITY % ofsattrs
     " ref          IDREF  #REQUIRED
       x1           %XY;   #IMPLIED
       y1           %XY;   #IMPLIED
       x2           %XY;   #IMPLIED
       y2           %XY;   #IMPLIED"
     >

     <!ELEMENT play-item                      EMPTY>
     <!ATTLIST play-item
       ref          IDREF  #IMPLIED
     >

<pbc> container and sub-elements only supported for Video CD 2.0, Super Video CD 1.0 and HQ Video CD 1.0.

id
     ID value referenced in ref attributes.

rejected
     Attribute controlling, whether item is not listed, i.e. rejected, in the LOT. Lists which are not rejected may be---if supported by the playing device---select-able by user input of the automatically assigned List ID Number. It is recommended to enable the rejected property for but the very first PBC list, in order to make the unreferenced item check work better.  The first PBC Item must not be rejected.

x1 y1 x2 y2
     Screen coordinates for selection-hotspot areas. This is only supported for <selection> members; 0,0 is the upper left left screen coordinate and 255,255 is the lower-right screen coordinate.  x1 and y1 are required to be less than x2 and y2 respectively. This coordinate system is independent and does not vary due to actual screen resolution or aspect ratio that may be use in display.

     See Selection List.

play-item
     This empty element is used to reference play item ids. If the ref attribute is ommitted (e.g. <play-item />, the play nothing item is implicitly referenced.

<selection> Element
...................

     <!ELEMENT selection                     (bsn?,
                                              prev?,
                                              next?,
                                              return?,
                                              (multi-default|default)?,
                                              timeout?,
                                              wait?,
                                              loop?,
                                              play-item?,
                                              select*)>
     <!ATTLIST selection
       %pbcattrs;
     >

     <!ENTITY % ofsattrs
      ref       IDREF       #IMPLIED
      x1        %XY;        #IMPLIED
      y1        %XY;        #IMPLIED
      x2        %XY;        #IMPLIED
      y2        %XY;        #IMPLIED
     >

     <!ELEMENT      bsn                      (#PCDATA)>
     <!ELEMENT      prev                     EMPTY>
     <!ELEMENT      next                     EMPTY>
     <!ELEMENT      return                   EMPTY>

     <!ELEMENT      default                  EMPTY>
     <!ELEMENT      multi-default            EMPTY>
     <!ATTLIST multi-default
       numeric      (enabled|disabled)  'enabled'
     >

     <!ELEMENT      timeout                  EMPTY>
     <!ELEMENT      wait                     (#PCDATA)>

     <!ELEMENT      loop                     (#PCDATA)>
     <!ATTLIST loop
       jump-timing  (immediate|delayed) 'immediate'
     >

     <!ATTLIST prev      %ofsattrs>
     <!ATTLIST next      %ofsattrs>
     <!ATTLIST return    %ofsattrs>
     <!ATTLIST default   %ofsattrs>
     <!ATTLIST select    %ofsattrs>
     <!ATTLIST timeout   ref       IDREF     #IMPLIED>
     <!ATTLIST play-item ref       IDREF     #IMPLIED>

     <!ELEMENT      play-item                EMPTY>
     <!ELEMENT      select                   EMPTY>

<bsn>
     Base selection number, the numeric value which is taken as the first selection number. The default is 1 and the allowed range goes from 1 upto 99.

<prev>
     Target list id jumped to on PREVIOUS key press.

<next>
     Target list id jumped to on NEXT key press.

<return>
     Target list id jumped to on RETURN key press.

<default>
     Target list id jumped to on DEFAULT key press. May not be present at the same time with the following element.

     If a <default> target is defined, <loop> should not be set to loop forever (0) nor shall <wait> indicate an infinite time-out wait time, otherwise the target will be unreachable.

<multi-default>
     When present, causes the selection list to be a multi-default selection list, i.e. that the target list id of the DEFAULT depends on which part of the sequence item is playing. The numeric attributes, if disabled, allows to disable the NUMERIC keys. When using multi-default selections, the <bsn> must be set to 1 and the number of selection must match the number of all entry points of the sequence referenced by <play-item>.

<timeout>
     Target list id to be jumped on time-out of <wait>. If omitted (and <wait> is not set to an infinite time) one of the <select> targets is selected at random!

<wait>
     Time in seconds to wait after playback of <play-item> before triggering the <timeout> action (unless the user triggers some action before time ran up). Default: 0.

<loop>
     Times to repeat the playback of <play-item>. the jump-timing attribute controls whether the playback of <play-item> is finished, thus delayed, before executing user triggered action or an immediate jump is performed. After the specified amount of repetitions are completed, the <wait> time begins to count down, unless set to an infinite wait time by setting it to the value 0. If this element is omitted, a default of 1 is used, i.e. the <play-item> will be displayed once. The default for the jump-timing is IMMEDIATE.

     When the jump-timing is set to delayed, it is recommended that the length of the referenced <play-item> is not more than 5 seconds. The recommended setting for a play item consisting of one still picture and no audio is to loop once and have a delayed jump-timing.

     If <play-time> refers to an entry, the unit of looping is complete when the sequence that the entry is contained in is complete. The point to start again on repetition is still however the entry point, not the beginning of the sequence.

<play-item>
     The play item to be played while waiting for user intervention.

<select>
     Target list id(s) jumped to on NUMERIC key presses. There may be up to 99 select choices. The sum of <bsn> and the number of <select> elements per <selection> must not be greater than 100.

<playlist> Element
..................

     <!ELEMENT playlist                      (prev?,
                                              next?,
                                              return?,
                                              playtime?,
                                              wait?,
                                              autowait?,
                                              play-item+)>
     <!ATTLIST playlist
       %pbcattrs;
     >

     <!ELEMENT      prev                     EMPTY>
     <!ELEMENT      next                     EMPTY>
     <!ELEMENT      return                   EMPTY>
     <!ELEMENT      playtime                 (#PCDATA)>
     <!ELEMENT      wait                     (#PCDATA)>
     <!ELEMENT      autowait                 (#PCDATA)>
     <!ELEMENT      play-item                EMPTY>

<prev>
     Target list id jumped to on PREVIOUS key press.

<next>
     Target list id jumped to on NEXT key press.

<return>
     Target list id jumped to on RETURN key press.

<playtime>
     The amount of seconds to play of every <play-item>. The given time value is rounded to 1/15 second units. The allowed range has a maximum value of 4369.0 seconds, values equal or less than 0 cause each <play-item> to be played to its end. Default: 0

<wait>
     Time in seconds to wait after each playback of <play-item> before proceding. Default: 0.

<autowait>
     Time in seconds to wait at each defined <auto-pause> point for sequence items referenced in this play list. Default: 0.

<play-item>
     The play item(s) to play in order. Up to 255 <play-item> elements may be defined per <playlist>.

     ...
       <pbc>
     ...
         <playlist id="play-trailers">
           <prev ref="select-specialfeaturemenu"/>
           <next ref="select-specialfeaturemenu"/>
           <return ref="select-specialfeaturemenu"/>
           <wait>0</wait>
           <autowait>0</autowait>
           <play-item ref="seg-animation-intro"/>
           <play-item ref="seq-trailer-1"/>
           <play-item ref="seg-animation-intra"/>
           <play-item ref="seq-trailer-2"/>
           <play-item ref="seg-animation-intra"/>
           <play-item ref="seq-trailer-3"/>
           <play-item ref="seg-animation-extro"/>
         </playlist>
     ...
       </pbc>
     </videocd>
     ...

<endlist> Element
.................

     <!ELEMENT endlist                       (next-volume?,
                                              play-item?)>
     <!ATTLIST endlist
       %pbcattrs;
     >

     <!ELEMENT next-volume                   (#PCDATA)>

The following elements are only supported for Super Video CD 1.0 and HQ Video CD 1.0.

<next-volume>
     Only supported for Super Video CD's. If set to 0 stop PBC intepretation, otherwise switch to the selected volume number.

<play-item>
     Only supported for Super Video CD's. Displays the referenced image while waiting for a volume change. Referenced play item shall be a still picture.

     ...
         <endlist id="end-lid">
           <next-volume>2</next-volume>
           <play-item ref="change-disc-segitem"/>
         </endlist>
     ...
       </pbc>
     </videocd>
     ...

Examples
********

The general procedure for creating a (Super) Video CD involves the following steps:

 1. Get an idea for a Video CD.

 2. Collecting, creating or encoding the required MPEG items for inclusion on the Video CD.

 3. Design some sophisticated PBC flow and create a XML description reflecting that or use vcdxgen to generate a very simple Video CD structure.

 4. Let vcdxbuild process the XML description created in the previous step. If required fix warnings and errors displayed by vcdxbuild.

 5. Write the created disc image to a CD-R.

The steps of encoding compliant MPEG program streams are not covered in this manual. (see http://mjpeg.sourceforge.net/)

The last step, writing to a CD-R, can be accomplished by cdrdao (see http://cdrdao.sourceforge.net/) as simple as:

     $ cdrdao write --device 0,5,0 --speed 8 videocd.cue
     Cdrdao version 1.1.5 - (C) Andreas Mueller <andreas@daneb.de>
       SCSI interface library - (C) Joerg Schilling
       L-EC encoding library - (C) Heiko Eissfeldt
       Paranoia DAE library - (C) Monty

     Check http://cdrdao.sourceforge.net/drives.html#dt for current driver
     tables.

     Using libscg version 'schily-0.5'

     0,5,0: YAMAHA CRW8424S	Rev: 1.0j
     Using driver: Generic SCSI-3/MMC - Version 1.2 (options 0x0000)

     Starting write at speed 8...
     Pausing 10 seconds - hit CTRL-C to abort.
     Process can be aborted with QUIT signal (usually CTRL-\).
     Executing power calibration...
     Power calibration successful.
     Writing track 01 (mode MODE2_RAW/MODE2_RAW)...
     Writing track 02 (mode MODE2_RAW/MODE2_RAW)...
     Wrote 750 of 750 MB (Buffer 100%).
     Wrote 334544 blocks. Buffer fill min 96%/max 100%.
     Flushing cache...
     Writing finished successfully.
     $

Simple Multitrack Example
=========================

In the following example session, the files track1.mpg, track2.mpg and track3.mpg are mastered into the default output files videocd.cue and videocd.bin. The volume label is set to `My Test VCD'.

     $ vcdimager --iso-volume-label="MY_TEST_VCD" track1.mpg track2 track3.mpg
        INFO: scanning mpeg sequence item #0 for scanpoints...
        INFO: scanning mpeg sequence item #1 for scanpoints...
        INFO: scanning mpeg sequence item #2 for scanpoints...
        INFO: writing track 1 (ISO-9660)...
        INFO: writing track 2, MPEG1, NTSC SIF (352x240/29.97fps), 1 audio stream...
        INFO: writing track 3, MPEG1, PAL SIF (352x288/25fps), 1 audio stream...
        INFO: writing track 4, MPEG1, NTSC SIF (352x240/29.97fps), 1 audio stream...
     finished ok, image created with 13626 sectors [03:01.51]
     $

The same with XML based tools:

     $ vcdxgen --iso-volume-label="MY_TEST_VCD" track1.mpg track2 track3.mpg
     (Super) VideoCD xml description created successfully as `videocd.xml'
     $ vcdxbuild videocd.xml
        INFO: scanning mpeg sequence item #0 for scanpoints...
        INFO: scanning mpeg sequence item #1 for scanpoints...
        INFO: scanning mpeg sequence item #2 for scanpoints...
        INFO: writing track 1 (ISO-9660)...
        INFO: writing track 2, MPEG1, NTSC SIF (352x240/29.97fps), 1 audio stream...
        INFO: writing track 3, MPEG1, PAL SIF (352x288/25fps), 1 audio stream...
        INFO: writing track 4, MPEG1, MPEG1, NTSC SIF (352x240/29.97fps), 1 audio stream...
     finished ok, image created with 13626 sectors [03:01.51]
     $

Video CD Disassembling
======================

The next example show how to extract the PBC information and the MPEG streams contained in the image file videocd.bin (the resulting streams are stored in files named avseq##.mpg with ## being the track number, starting with 0).

     $ vcdxrip -c videocd.cue
        INFO: detected extended VCD2.0 PBC files
        INFO: extracting avseq00.mpg... (start lsn 450 (+4739))
        INFO: extracting avseq01.mpg... (start lsn 5189 (+4160))
        INFO: extracting avseq02.mpg... (start lsn 9349 (+4277))
        INFO: writing xml description to `videocd.xml'...
        INFO: done
     $

Video CD Low-level Information
==============================

The last example shows how to get lower-level layout information about a VCD using vcd-info. For more information see Introduction (The GNU Video CD Info Dump Program).

     $ vcd-info -c videocd.cue
     vcd-info - GNU VCDImager - (Super) Video CD Report
     $Id: vcdimager.texi,v 1.45 2005/06/18 04:11:08 rocky Exp $

     Source: image file `svcd_ogt_test_ntsc.cue'
     Image size: 4106 sectors
     SVCD detected
     -------------------------------------------------------------------------------
     ISO9660 primary volume descriptor
      ID: `CD001'
      version: 1
      system id: `CD-RTOS CD-BRIDGE'
      volume id: `SVCD_OGT_TEST_NTSC'
      volumeset id: `'
      publisher id: `'
      preparer id: `GNU VCDIMAGER 0.7.12 LINUX-GNU/I386'
      application id: `'
      ISO size: 376 blocks (logical blocksize: 2048 bytes)
      XA marker present: yes
     -------------------------------------------------------------------------------
     ISO9660 filesystem dump
      root directory in PVD set to LSN 18

      /:
       d d---1xrxrxr 0 0 [fn 00] [LSN     18]      2048  .
       d d---1xrxrxr 0 0 [fn 00] [LSN     18]      2048  ..
       d d---1xrxrxr 0 0 [fn 00] [LSN     19]      2048  EXT
       d d---1xrxrxr 0 0 [fn 00] [LSN     20]      2048  MPEG2
       d d---1xrxrxr 0 0 [fn 00] [LSN     21]      2048  SEGMENT
       d d---1xrxrxr 0 0 [fn 00] [LSN     22]      2048  SVCD

      /EXT/:
       d d---1xrxrxr 0 0 [fn 00] [LSN     19]      2048  .
       d d---1xrxrxr 0 0 [fn 00] [LSN     18]      2048  ..
       - ----1xrxrxr 0 0 [fn 00] [LSN    375]       201  SCANDATA.DAT;1

      /MPEG2/:
       d d---1xrxrxr 0 0 [fn 00] [LSN     20]      2048  .
       d d---1xrxrxr 0 0 [fn 00] [LSN     18]      2048  ..
       - ---2-xrxrxr 0 0 [fn 00] [LSN    526]   7971320 (  7024640)  AVSEQ01.MPG;1

      /SEGMENT/:
       d d---1xrxrxr 0 0 [fn 00] [LSN     21]      2048  .
       d d---1xrxrxr 0 0 [fn 00] [LSN     18]      2048  ..
       - ---2-xrxrxr 0 0 [fn 00] [LSN    225]    183596 (   161792)  ITEM0001.MPG;1

      /SVCD/:
       d d---1xrxrxr 0 0 [fn 00] [LSN     22]      2048  .
       d d---1xrxrxr 0 0 [fn 00] [LSN     18]      2048  ..
       - ----1xrxrxr 0 0 [fn 00] [LSN    151]      2048  ENTRIES.SVD;1
       - ----1xrxrxr 0 0 [fn 00] [LSN    150]      2048  INFO.SVD;1
       - ----1xrxrxr 0 0 [fn 00] [LSN    152]     65536  LOT.SVD;1
       - ----1xrxrxr 0 0 [fn 00] [LSN    184]        40  PSD.SVD;1
       - ----1xrxrxr 0 0 [fn 00] [LSN    186]       190  SEARCH.DAT;1
       - ----1xrxrxr 0 0 [fn 00] [LSN    185]      2048  TRACKS.SVD;1

     -------------------------------------------------------------------------------
     SVCD/INFO.SVD
      ID: `SUPERVCD'
      version: 0x01
      system profile tag: 0x00
      album id: `OGT_TEST_NTSC'
      volume count: 1
      volume number: 1
      pal flags: 00000000 00000000 00000000 00000000 00000000 00000000
       (bslbf)   00000000 00000000 00000000 00000000 00000000 00000000 00
      flags:
       reserved1: no
       restriction: 0
       special info: no
       user data cc: no
       start lid #2: no
       start track #2: no
       reserved2: no
      psd size: 40
      first segment addr: 00:05:00
      offset multiplier: 0x08
      maximum lid: 3
      number of segments: 1
      SEGMENT[0000]: track# 0, LSN    225 (MSF 00:05:00), 79 sectors
        audio: no stream, video: NTSC still, continuation no, OGT substream: None
      volume start time[0]: 0 secs
      volume start time[1]: 0 secs
      volume start time[2]: 0 secs
      volume start time[3]: 0 secs
      volume start time[4]: 0 secs
     -------------------------------------------------------------------------------
     SVCD/ENTRIES.SVD
      ID: `ENTRYVCD'
      version: 0x01
      system profile tag: 0x00
      entries: 1
      ENTRY[00]: track#  1 (SEQUENCE[0]), LSN    526 (MSF 00:09:01)
     -------------------------------------------------------------------------------
     SVCD/LOT.SVD
      LID[1]: offset = 0 (0x0000)
      LID[2]: offset = 16 (0x0002)
      LID[3]: rejected
     -------------------------------------------------------------------------------
     SVCD/PSD.SVD
      PSD[00] (LID[1] @0x0000): play list descriptor
       NOI: 1 | LID#: 1 (rejected: no)
       prev: LID[2] @0x0002 | next: LID[2] @0x0002 | return: LID[3] @0x0004
       playtime: 0/15s | wait: 1s | autowait: 0s
       play-item[0]: SEQUENCE[1] (0x0002)

      PSD[01] (LID[2] @0x0002): play list descriptor
       NOI: 1 | LID#: 2 (rejected: no)
       prev: LID[1] @0x0000 | next: LID[1] @0x0000 | return: LID[3] @0x0004
       playtime: 0/15s | wait: 6s | autowait: 0s
       play-item[0]: SEGMENT[0] (0x03e8)

      PSD[02] (LID[3] @0x0004): end list descriptor
       next disc number: 0 (if 0 stop PBC handling)
       change picture item: play nothing (0x0000)

     -------------------------------------------------------------------------------
     SVCD/TRACKS.SVD
      ID: `TRACKSVD'
      version: 0x01
      tracks: 1
      track[00]: 00:29:11, audio: 1 stream, video: NTSC stream, OGT stream: 0 available

     CVD interpretation (probably)
     (track[00]: 00:29:11 (cumulated), audio: 00, ogt: 4d)
     -------------------------------------------------------------------------------
     CD-ROM TRACKS (1 - 2)
       #: MSF       LSN     Type
       1: 00:02:00  000000  XA
       2: 00:09:01  000526  XA
     170: 00:56:56  004106  leadout
     -------------------------------------------------------------------------------
     SVCD/SEARCH.DAT
      ID: `SEARCHSV'
      version: 0x01
      scanpoints: 59
      scaninterval: 1 (in 0.5sec units -- must be `1')
      scanpoint[0000]: (real time: 00:00:00.0)  sector: LSN 527 (MSF 00:09:02)
      scanpoint[0001]: (real time: 00:00:00.5)  sector: LSN 596 (MSF 00:09:71)
      scanpoint[0002]: (real time: 00:00:01.0)  sector: LSN 596 (MSF 00:09:71)
      scanpoint[0003]: (real time: 00:00:01.5)  sector: LSN 671 (MSF 00:10:71)
      scanpoint[0004]: (real time: 00:00:02.0)  sector: LSN 737 (MSF 00:11:62)
      scanpoint[0005]: (real time: 00:00:02.5)  sector: LSN 808 (MSF 00:12:58)
      scanpoint[0006]: (real time: 00:00:03.0)  sector: LSN 877 (MSF 00:13:52)
      scanpoint[0007]: (real time: 00:00:03.5)  sector: LSN 877 (MSF 00:13:52)
      scanpoint[0008]: (real time: 00:00:04.0)  sector: LSN 944 (MSF 00:14:44)
      scanpoint[0009]: (real time: 00:00:04.5)  sector: LSN 1012 (MSF 00:15:37)
      scanpoint[0010]: (real time: 00:00:05.0)  sector: LSN 1106 (MSF 00:16:56)
      scanpoint[0011]: (real time: 00:00:05.5)  sector: LSN 1183 (MSF 00:17:58)
      scanpoint[0012]: (real time: 00:00:06.0)  sector: LSN 1183 (MSF 00:17:58)
      scanpoint[0013]: (real time: 00:00:06.5)  sector: LSN 1257 (MSF 00:18:57)
      scanpoint[0014]: (real time: 00:00:07.0)  sector: LSN 1333 (MSF 00:19:58)
      scanpoint[0015]: (real time: 00:00:07.5)  sector: LSN 1408 (MSF 00:20:58)
      [..skipping...]
      scanpoint[0044]: (real time: 00:00:22.0)  sector: LSN 3097 (MSF 00:43:22)
      scanpoint[0045]: (real time: 00:00:22.5)  sector: LSN 3173 (MSF 00:44:23)
      scanpoint[0046]: (real time: 00:00:23.0)  sector: LSN 3246 (MSF 00:45:21)
      scanpoint[0047]: (real time: 00:00:23.5)  sector: LSN 3246 (MSF 00:45:21)
      scanpoint[0048]: (real time: 00:00:24.0)  sector: LSN 3321 (MSF 00:46:21)
      scanpoint[0049]: (real time: 00:00:24.5)  sector: LSN 3387 (MSF 00:47:12)
      scanpoint[0050]: (real time: 00:00:25.0)  sector: LSN 3455 (MSF 00:48:05)
      scanpoint[0051]: (real time: 00:00:25.5)  sector: LSN 3519 (MSF 00:48:69)
      scanpoint[0052]: (real time: 00:00:26.0)  sector: LSN 3519 (MSF 00:48:69)
      scanpoint[0053]: (real time: 00:00:26.5)  sector: LSN 3584 (MSF 00:49:59)
      scanpoint[0054]: (real time: 00:00:27.0)  sector: LSN 3654 (MSF 00:50:54)
      scanpoint[0055]: (real time: 00:00:27.5)  sector: LSN 3727 (MSF 00:51:52)
      scanpoint[0056]: (real time: 00:00:28.0)  sector: LSN 3801 (MSF 00:52:51)
      scanpoint[0057]: (real time: 00:00:28.5)  sector: LSN 3801 (MSF 00:52:51)
      scanpoint[0058]: (real time: 00:00:29.0)  sector: LSN 3874 (MSF 00:53:49)
     -------------------------------------------------------------------------------
     EXT/SCANDATA.DAT
      ID: `SCAN_VCD'
      version: 0x01
      reserved: 0x00
      scandata_count: 59
      sequence_count: 1
      segment_count: 0
       cumulative_playingtime[0]: 00:29:11
      sequence scandata ofs: 3
       track [0]: TOC num: 2, sd offset: 3
      (scanpoint[0] offset = 3)
       scanpoint[0000] (ofs:    3): LSN 527 (MSF 00:09:02)
       scanpoint[0001] (ofs:    6): LSN 596 (MSF 00:09:71)
       scanpoint[0002] (ofs:    9): LSN 596 (MSF 00:09:71)
       scanpoint[0003] (ofs:   12): LSN 671 (MSF 00:10:71)
       scanpoint[0004] (ofs:   15): LSN 737 (MSF 00:11:62)
       scanpoint[0005] (ofs:   18): LSN 808 (MSF 00:12:58)
       scanpoint[0006] (ofs:   21): LSN 877 (MSF 00:13:52)
       scanpoint[0007] (ofs:   24): LSN 877 (MSF 00:13:52)
       scanpoint[0008] (ofs:   27): LSN 944 (MSF 00:14:44)
       scanpoint[0009] (ofs:   30): LSN 1012 (MSF 00:15:37)
       scanpoint[0010] (ofs:   33): LSN 1106 (MSF 00:16:56)
       scanpoint[0011] (ofs:   36): LSN 1183 (MSF 00:17:58)
       scanpoint[0012] (ofs:   39): LSN 1183 (MSF 00:17:58)
       scanpoint[0013] (ofs:   42): LSN 1257 (MSF 00:18:57)
       scanpoint[0014] (ofs:   45): LSN 1333 (MSF 00:19:58)
       scanpoint[0015] (ofs:   48): LSN 1408 (MSF 00:20:58)
      [..skipping...]
       scanpoint[0044] (ofs:  135): LSN 3097 (MSF 00:43:22)
       scanpoint[0045] (ofs:  138): LSN 3173 (MSF 00:44:23)
       scanpoint[0046] (ofs:  141): LSN 3246 (MSF 00:45:21)
       scanpoint[0047] (ofs:  144): LSN 3246 (MSF 00:45:21)
       scanpoint[0048] (ofs:  147): LSN 3321 (MSF 00:46:21)
       scanpoint[0049] (ofs:  150): LSN 3387 (MSF 00:47:12)
       scanpoint[0050] (ofs:  153): LSN 3455 (MSF 00:48:05)
       scanpoint[0051] (ofs:  156): LSN 3519 (MSF 00:48:69)
       scanpoint[0052] (ofs:  159): LSN 3519 (MSF 00:48:69)
       scanpoint[0053] (ofs:  162): LSN 3584 (MSF 00:49:59)
       scanpoint[0054] (ofs:  165): LSN 3654 (MSF 00:50:54)
       scanpoint[0055] (ofs:  168): LSN 3727 (MSF 00:51:52)
       scanpoint[0056] (ofs:  171): LSN 3801 (MSF 00:52:51)
       scanpoint[0057] (ofs:  174): LSN 3801 (MSF 00:52:51)
       scanpoint[0058] (ofs:  177): LSN 3874 (MSF 00:53:49)
     -------------------------------------------------------------------------------
     $

Tips and Hints
**************

SVCD Player Compatibility
=========================

If you have problems with your playing device failing to detect a created SVCD, you can may the following things (some of the advices below apply to VCDs as well):

 1. Take warnings serious! If there were warnings issued during the image building process, chances are the problems are related to them.

 2. Make sure the SVCD is physically OK (e.g., analyze the disc with vcddebug or try it on some other playing device).

 3. Try creating the SVCD by enabling the svcd vcd30 mpegav and svcd vcd30 entrysvd options.

 4. Add an empty /SEGMENT directory, if it isn't created due to inclusion of SPIs.

 5. If you have confusing time readings for discs with more than one video track, you might need to use the svcd vcd30 tracksvd option.

Fast Forward & Fast Rewind with Super Video CD's
================================================

Because of the VBR encoding of the MPEG-2 streams on SVCDs, there's no fixed relation between sector index and playing time. If scanning doesn't work with your playing device it can be caused by:

  * The playing device does not support FF/RW with SVCDs. (Sometimes upgrading the player firmware may help.)

  * The MPEG-2 streams playing time longer that can be handled by the playing device. (Some devices don't support programs with a playing time of over about 40 minutes. This is to be seen as bug or limitation of the firmware, as SVCD's can have programs with up to 100 minute playing times.)

  * The MPEG-2 stream does not include the mandatory scan information data or when included, it doesn't follow the specification (libvcd warns if scan information is missing or syntactically wrong.). See Scan Information Data.

  * Some playing devices require a sequence header before each GOP header. See Access Point Sectors.

ISO 9660 Character Sets
***********************

ISO646 d-Characters
===================

       | 0 1 2 3 4 5 6 7
     --+-----------------
     0 |       0   P
     1 |       1 A Q
     2 |       2 B R
     3 |       3 C S
     4 |       4 D T
     5 |       5 E U
     6 |       6 F V
     7 |       7 G W
     8 |       8 H X
     9 |       9 I Y
     a |         J Z
     b |         K
     c |         L
     d |         M
     e |         N
     f |         O _

ISO646 a-Characters
===================

       | 0 1 2 3 4 5 6 7
     --+-----------------
     0 |       0   P
     1 |     ! 1 A Q
     2 |     " 2 B R
     3 |       3 C S
     4 |       4 D T
     5 |     % 5 E U
     6 |     & 6 F V
     7 |     ' 7 G W
     8 |     ( 8 H X
     9 |     ) 9 I Y
     a |     * : J Z
     b |     + ; K
     c |     , < L
     d |     - = M
     e |     . > N
     f |     / ? O _

Glossary
********

     [file glossary.texi not included]

GNU General Public License
**************************

Version 2, June 1991
     [file gpl.texi not included]

GNU Free Documentation License
******************************

Version 1.1, March 2000
     [file fdl.texi not included]