This is vcdimager.info, produced by makeinfo version 4.0b from
vcdimager.texi.

   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".

INFO-DIR-SECTION Miscellaneous
START-INFO-DIR-ENTRY
* GNU VCDImager: (vcdimager).                   GNU Video CD imaging utilities
* vcddebug: (vcdimager).                        Video CD debugging tool
* vcdxgen: (vcdimager).                         Video CD XML template generator
* vcdxbuild: (vcdimager).                       Video CD XML formatter
* vcdxrip: (vcdimager).                         Video CD XML dis-assembler
END-INFO-DIR-ENTRY


File: vcdimager.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

* Menu:

* Introduction::
* Video CD Concepts::
* Reference::
* Video CD XML Description::
* Examples::
* Tips and Hints::
* Character Sets::
* Acronym Expansions::
* GNU General Public License::
* GNU Free Documentation License::
* XML Tag Index::
* Concept Index::


File: vcdimager.info,  Node: Introduction,  Next: Video CD Concepts,  Prev: Top,  Up: Top

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

   This manual describes the "GNU VCDImager"(1) package, a tool-set for
authoring, disassembling and analyzing Video CD's and Super Video CD's.

* Menu:

* Supplied Tools::
* Features::

   ---------- Footnotes ----------

   (1) see `http://www.gnu.org/software/vcdimager/'


File: vcdimager.info,  Node: Supplied Tools,  Next: Features,  Prev: Introduction,  Up: Introduction

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.

`vcddebug'
     Analyzing tool and report generator for VCD and SVCD discs.

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

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

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

`vcdxminfo'
     This is a debugging tool for displaying some MPEG properties, as
     conceived by `libvcd'.

`cdxa2mpeg'
     Simple tool for converting MPEG streams wrapped in RIFF CDXA
     files, as created by some operating systems, to plain mpeg streams
     suitable for vcdimager input.

   The generated CD-ROM 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(1), for instance.

   ---------- Footnotes ----------

   (1) see `http://www.ping.de/sites/daneb/cdrdao.html'


File: vcdimager.info,  Node: Features,  Prev: Supplied Tools,  Up: Introduction

Features
========

   Features of the back-end library(1), 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(2) 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(3).

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


   ---------- Footnotes ----------

   (1) the core of the GNU VCDImager package consists of a library
named `libvcd', the front-ends are just user interfaces to the exported
C-API

   (2) 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.

   (3) ...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


File: vcdimager.info,  Node: Video CD Concepts,  Next: Reference,  Prev: Introduction,  Up: Top

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>.

* Menu:

* Overview::
* Anatomy of Video CDs::
* Known Video CD Flavors::
* The ISO-9660 Track::
* Constraints on MPEG streams::
* Play Items::
* Playback Control::


File: vcdimager.info,  Node: Overview,  Next: Anatomy of Video CDs,  Prev: Video CD Concepts,  Up: Video CD Concepts

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.


File: vcdimager.info,  Node: Anatomy of Video CDs,  Next: Known Video CD Flavors,  Prev: Overview,  Up: Video CD Concepts

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(1)

   *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'. *Note 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(2) 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(3) CD-DA tracks. (not supported yet by vcdimager)

   * Lead-out area.


   ---------- Footnotes ----------

   (1) 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.

   (2) 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.

   (3) the maximum number of tracks on a Video CD must not exceed 99
tracks


File: vcdimager.info,  Node: Known Video CD Flavors,  Next: The ISO-9660 Track,  Prev: Anatomy of Video CDs,  Up: Video CD Concepts

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

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

* Menu:

* Video CD 1.1::
* Video CD 2.0::
* Extended Video CD::
* Super Video CD 1.0::
* HQ Video CD 1.0::
* Extended Super Video CD::


File: vcdimager.info,  Node: Video CD 1.1,  Next: Video CD 2.0,  Prev: Known Video CD Flavors,  Up: Known Video CD Flavors

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

   This is the most basic Video CD specification dating back to
1993(1), 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(2) in
order to accommodate single speed CD-ROM drives. The specification
allows for the following two resolutions(3):

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

   * 352 x 240 @ 23.976 Hz (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(4).

   ---------- Footnotes ----------

   (1) actually this flavor was based on the Karaoke-CD, which was the
first MPEG based CD-ROM format.

   (2) 2324 bytes of payload per sector * 75 sectors per second =
174300 bytes per second

   (3) Actually even PAL resolution works depending on the playing
device

   (4) 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


File: vcdimager.info,  Node: Video CD 2.0,  Next: Extended Video CD,  Prev: Video CD 1.1,  Up: Known Video CD Flavors

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.
     *Note 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 Hz (NTSC SIF).

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

   * 352 x 288 @ 25 Hz (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(1) was provided. The bit-rate of multiplex-ed streams should
be kept under(2) 174300 bytes/sec (except for single still picture
items) in order to accommodate single speed drives.

   ---------- Footnotes ----------

   (1) 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 D-2) and 704 x 576 (PAL Full D-2)

   (2) 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.


File: vcdimager.info,  Node: Extended Video CD,  Next: Super Video CD 1.0,  Prev: Video CD 2.0,  Up: Known Video CD Flavors

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.


File: vcdimager.info,  Node: Super Video CD 1.0,  Next: HQ Video CD 1.0,  Prev: Extended Video CD,  Up: Known Video CD Flavors

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 of this Super Video CD specification was published as
IEC-62107.

   As the most notable change over Video CD 2.0 is a switch from MPEG-1
CBR to MPEG-2 VBR encoding for the video stream was performed. The
following new features--building upon 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(1) 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(2):

   * 480 x 480 @ 29.97 Hz (NTSC 2/3 D-2).

   * 480 x 576 @ 25 Hz (PAL 2/3 D-2).

   ---------- Footnotes ----------

   (1) There is also a non-compliant subtitle format widely used,
having its origins in the forgotten "CVD" specification, which is said
to have been a competitor for the Video CD 2.0 successor. Vcdimager
recognizes both formats.

   (2) the same high resolutions as defined for Video CD 2.0 apply for
Super Video CD's


File: vcdimager.info,  Node: HQ Video CD 1.0,  Next: Extended Super Video CD,  Prev: Super Video CD 1.0,  Up: Known Video CD Flavors

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.



File: vcdimager.info,  Node: Extended Super Video CD,  Prev: HQ Video CD 1.0,  Up: Known Video CD Flavors

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.


File: vcdimager.info,  Node: The ISO-9660 Track,  Next: Constraints on MPEG streams,  Prev: Known Video CD Flavors,  Up: Video CD Concepts

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

* Menu:

* Primary Volume Descriptor::
* Directory Structure::


File: vcdimager.info,  Node: Primary Volume Descriptor,  Next: Directory Structure,  Prev: The ISO-9660 Track,  Up: 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,
various IDs, file-system size, pointer to the root directory and so
on...


File: vcdimager.info,  Node: Directory Structure,  Prev: Primary Volume Descriptor,  Up: The ISO-9660 Track

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

* Menu:

* /VCD & /SVCD Directory::
* /MPEGAV & /MPEG2 Directory::
* /CDDA Directory::
* /SEGMENT Directory::
* /EXT Directory::
* /CDI Directory::


File: vcdimager.info,  Node: /VCD & /SVCD Directory,  Next: /MPEGAV & /MPEG2 Directory,  Prev: Directory Structure,  Up: 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. *Note Access Point Sectors::.

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


File: vcdimager.info,  Node: /MPEGAV & /MPEG2 Directory,  Next: /CDDA Directory,  Prev: /VCD & /SVCD Directory,  Up: Directory Structure

`/MPEGAV' & `/MPEG2' Directory
..............................

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


File: vcdimager.info,  Node: /CDDA Directory,  Next: /SEGMENT Directory,  Prev: /MPEGAV & /MPEG2 Directory,  Up: Directory Structure

`/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.


File: vcdimager.info,  Node: /SEGMENT Directory,  Next: /EXT Directory,  Prev: /CDDA Directory,  Up: Directory Structure

`/SEGMENT' Directory
....................

   This directory contains file entries to segment play items. *Note
Segment Items::.


File: vcdimager.info,  Node: /EXT Directory,  Next: /CDI Directory,  Prev: /SEGMENT Directory,  Up: Directory Structure

`/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.


File: vcdimager.info,  Node: /CDI Directory,  Prev: /EXT Directory,  Up: Directory Structure

`/CDI' Directory
................

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


File: vcdimager.info,  Node: Constraints on MPEG streams,  Next: Play Items,  Prev: The ISO-9660 Track,  Up: Video CD Concepts

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.

* Menu:

* Video CD::
* Super Video CD::
* Common Constraints::


File: vcdimager.info,  Node: Video CD,  Next: Super Video CD,  Prev: Constraints on MPEG streams,  Up: Constraints on MPEG 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 Hz (NTSC).

   * 352 x 240 @ 23.976 Hz (FILM).

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

   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.


File: vcdimager.info,  Node: Super Video CD,  Next: Common Constraints,  Prev: Video CD,  Up: Constraints on MPEG streams

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(1):

   * 480 x 480 @ 29.97 Hz (NTSC).

   * 480 x 576 @ 25 Hz (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.

* Menu:

* Scan Information Data::
* SVCD Subtitles::

   ---------- Footnotes ----------

   (1) actually you can try other resolutions as well, but then you are
leaving the SVCD specification behind you...


File: vcdimager.info,  Node: Scan Information Data,  Next: SVCD Subtitles,  Prev: Super Video CD,  Up: Super Video CD

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

   According to the specification, it is mandatory for Super Video
CD's(1) 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. *Note <option> Element::.

   ---------- Footnotes ----------

   (1) It seems to be optionally supported for the Video CD 2.0


File: vcdimager.info,  Node: SVCD Subtitles,  Prev: Scan Information Data,  Up: Super Video CD

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

   There exist two major subtitle formats for SVCD's, of which only one
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'(1). 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...

   ---------- Footnotes ----------

   (1) While AC3 tracks use the `private_data_id' `0x80+', DVD
subtitles `0x20' onwards and CVD subtitles `0x00' and up.


File: vcdimager.info,  Node: Common Constraints,  Prev: Super Video CD,  Up: Constraints on MPEG streams

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

* Menu:

* Alignment::
* Access Point Sectors::


File: vcdimager.info,  Node: Alignment,  Next: Access Point Sectors,  Prev: Common Constraints,  Up: Common Constraints

Alignment
.........

   The MPEG program streams should be aligned to 2324 byte MPEG packet
boundaries(1). If the pack headers should happen not be aligned on 2324
byte boundaries, GNU VCDImager will try(2) 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.

   ---------- Footnotes ----------

   (1) i.e. pack headers must be repeated every 2324 bytes, starting on
byte 0

   (2) aligning only works, if MPEG packets are _not_ bigger than 2324
bytes.


File: vcdimager.info,  Node: Access Point Sectors,  Prev: Alignment,  Up: Common Constraints

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.


File: vcdimager.info,  Node: Play Items,  Next: Playback Control,  Prev: Constraints on MPEG streams,  Up: Video CD Concepts

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

   "Play items" are the MPEG payload on (Super) Video CD's. Sequences
are useful for seamless play of larger video sections, whereas segments
are better for smaller items in interactive applications.

* Menu:

* Sequence Items::
* Segment Items::


File: vcdimager.info,  Node: Sequence Items,  Next: Segment Items,  Prev: Play Items,  Up: Play Items

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.

   * Entry points.


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

   * Pre-gap of 150 empty sectors.

   * Limit of 98 sequences.

   * Must contain motion video (and audio for Video CD 2.0).



File: vcdimager.info,  Node: Segment Items,  Prev: Sequence Items,  Up: Play Items

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(1).

   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.(2)

Advantages
..........

   * Up to 1980 segment items possible.

   * Still pictures and audio only MPEG streams allowed.

   * No pre-gaps.


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

   * Only PBC accessible through PBC.

   * Segment item size limited by SPI area size.


   ---------- Footnotes ----------

   (1) 1980 * 150 * 2324 = 690228000 bytes

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


File: vcdimager.info,  Node: Playback Control,  Prev: Play Items,  Up: Video CD Concepts

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(1) and the possibility of interaction with the user through the
remote control or some other input device available.

* Menu:

* Function Keys for Interaction::
* Linear Playback::
* PBC Lists::
* Applications::

   ---------- Footnotes ----------

   (1) sequence items and segment items


File: vcdimager.info,  Node: Function Keys for Interaction,  Next: Linear Playback,  Prev: Playback Control,  Up: Playback Control

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>.


File: vcdimager.info,  Node: Linear Playback,  Next: PBC Lists,  Prev: Function Keys for Interaction,  Up: Playback Control

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(1). Alas, only a few playing
devices are capable of honoring Video CD chapters.

   ---------- Footnotes ----------

   (1) 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.


File: vcdimager.info,  Node: PBC Lists,  Next: Applications,  Prev: Linear Playback,  Up: Playback Control

PBC Lists
---------

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

* Menu:

* Play List::
* Selection List::
* End List::
* Command List::


File: vcdimager.info,  Node: Play List,  Next: Selection List,  Prev: PBC Lists,  Up: PBC Lists

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.


File: vcdimager.info,  Node: Selection List,  Next: End List,  Prev: Play List,  Up: PBC Lists

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

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

   Also features such as random selection, default target (<DEFAULT>),
timeout target and looping are supported.

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.

   Alas, this very useful feature is not widely supported amongst
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.


File: vcdimager.info,  Node: End List,  Next: Command List,  Prev: Selection List,  Up: PBC Lists

End List
........

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


File: vcdimager.info,  Node: Command List,  Prev: End List,  Up: PBC Lists

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.


File: vcdimager.info,  Node: Applications,  Prev: PBC Lists,  Up: Playback Control

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

   _...to be written..._


File: vcdimager.info,  Node: Reference,  Next: Video CD XML Description,  Prev: Video CD Concepts,  Up: Top

Reference
*********

* Menu:

* Tools::


File: vcdimager.info,  Node: Tools,  Prev: Reference,  Up: Reference

Tools
=====

* Menu:

* vcdimager::
* vcddebug::
* vcdxgen::
* vcdxbuild::
* vcdxrip::
* vcdxminfo::


File: vcdimager.info,  Node: vcdimager,  Next: vcddebug,  Prev: Tools,  Up: 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.


File: vcdimager.info,  Node: vcddebug,  Next: vcdxgen,  Prev: vcdimager,  Up: Tools

`vcddebug'
----------

   While this project went along, `vcddebug' was used to analyze and
reverse engineer existing Video CD's and later Super Video CD's. It has
grown into a valuable debugging tool and report generator for (Super)
Video CD's.

   It is recommended to make use of this tool if compatibility problems
arise, to identify what the difference between working discs and
non-working discs are, and thus help to improve GNU VCDImager.


File: vcdimager.info,  Node: vcdxgen,  Next: vcdxbuild,  Prev: vcddebug,  Up: Tools

`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_

* Menu:

* Adding Files to the Video CD ::
* CD-i Support::


File: vcdimager.info,  Node: Adding Files to the Video CD,  Next: CD-i Support,  Prev: vcdxgen,  Up: vcdxgen

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 (1).

   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 `/', *Note 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.(2)

   * 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.

   ---------- Footnotes ----------

   (1) 8 bytes for sub-header, 2324 bytes payload (which contains 276
bytes ECC for form 1) and finally 4 bytes for EDC

   (2) if no file name extension is supposed to exist the dot must be
placed as a trailing dot.


File: vcdimager.info,  Node: CD-i Support,  Prev: Adding Files to the Video CD,  Up: vcdxgen

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(1) aliasing file(2)

     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

   ---------- Footnotes ----------

   (1) see documentation for popt for more information about option
aliasing

   (2) add it to `/etc/popt' if the setting should be available
system-wide


File: vcdimager.info,  Node: vcdxbuild,  Next: vcdxrip,  Prev: vcdxgen,  Up: Tools

`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_


File: vcdimager.info,  Node: vcdxrip,  Next: vcdxminfo,  Prev: vcdxbuild,  Up: Tools

`vcdxrip'
---------

   This tool implements the inverse operation to `vcdxbuild', i.e.,
taking an already built disc image and outputting all the file items and
the XML description necessary to recreate this (Super) Video CD
including any PBC information.

`--output-file'
`-o'
     This option allows to specify the xml file name for output.
     default: `videocd.xml'.

`--norip'
     By the use of this option, only the XML description is created,
     without actually extracting any files or mpeg streams contained.

   _FIXME: write more_


File: vcdimager.info,  Node: vcdxminfo,  Prev: vcdxrip,  Up: Tools

`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_


File: vcdimager.info,  Node: Video CD XML Description,  Next: Examples,  Prev: Reference,  Up: Top

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.(1)

* Menu:

* Common Rules::
* <videocd> Root::

   ---------- Footnotes ----------

   (1) 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>>.


File: vcdimager.info,  Node: Common Rules,  Next: <videocd> Root,  Prev: Video CD XML Description,  Up: Video CD XML Description

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>'.


File: vcdimager.info,  Node: <videocd> Root,  Prev: Common Rules,  Up: Video CD XML Description

`<videocd>' Root
================

* Menu:

* <option> Element::
* <info> Container::
* <pvd> Container::
* <filesystem> Container::
* <segment-items> Container::
* <sequence-items> Container::
* <pbc> Container::

     <!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>


File: vcdimager.info,  Node: <option> Element,  Next: <info> Container,  Prev: <videocd> Root,  Up: <videocd> Root

`<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(1) 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(2)  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. *Note
     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(3). *Note Scan Information
     Data::.

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

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

   ---------- Footnotes ----------

   (1) except for the first one, which is hardwired to 150 sectors

   (2) Should have been better named `data track post-gap'.

   (3) It is required, that the stream has already user data groups
with scan information data, in order for this feature to work


File: vcdimager.info,  Node: <info> Container,  Next: <pvd> Container,  Prev: <option> Element,  Up: <videocd> Root

`<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(1) 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, *Note 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.(2)

`<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>
     ...

   ---------- Footnotes ----------

   (1) An _album_ is defined as a series of discs which contain related
content

   (2) The exact meaning of the restriction categories is depending on
the interpreting playing device.

