   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"(1) package, a tool-set for
authoring, disassembling and analyzing Video CD's and Super Video CD's.

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

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

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 (vcd-info).

`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(1), for instance.

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

   (1) see `http://cdrdao.sourceforge.net'

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 private
library named `libvcd' and public library named `libvcdinfo', 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

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

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

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

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

1.3.1 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 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(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

1.3.2 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(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 D1) and 704 x 576 (PAL Full D1)

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

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

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

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

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

   (1) The features left out in this subset are: subtitles, command
lists, extended pbc (hotspots and disc changer support).

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

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

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

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

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

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

1.4.2 Directory Structure
-------------------------

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1.5.2.1 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. See <option> Element.

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

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

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

1.5.3 Common Constraints
------------------------

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

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

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

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

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

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

   (1) 1980 * 150 * 2324 = 690228000 bytes

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

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

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

   (1) sequence items and segment items

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

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

1.7.3 PBC Lists
---------------

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

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

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

1.7.3.3 End List
................

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

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

1.7.4 Applications
------------------

_...to be written..._

2 Reference
***********

2.1 Tools
=========

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

2.1.2 `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 (vcd-info).

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

2.1.3.1 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 `/', 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.(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.

2.1.3.2 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

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

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

See Introduction (vcdxrip).

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

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

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

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

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

3.2 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

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

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

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

3.4.2 `<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, 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.(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.

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

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

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

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

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

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

3.4.6 `<sequence-items>' Container
----------------------------------

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

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

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

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

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

   (2) every sequence point has automatically an entry point defined,
which must be subtracted from the maximum of 500 entry points

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

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

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

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

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

   The last step, writing to a CD-R, can be accomplished by `cdrdao'(2)
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.
     $

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

   (1) see `http://mjpeg.sourceforge.net/'

   (2) see `http://cdrdao.sourceforge.net/'

4.1 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]
     $

4.2 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
     $

4.3 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 (vcd-info).

     $ 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)
     -------------------------------------------------------------------------------
     $

Appendix A Tips and Hints
*************************

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

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

   * The MPEG-2 streams playing time longer that can be handled by the
     playing device.(2)

   * The MPEG-2 stream does not include the mandatory scan information
     data or when included, it doesn't follow the specification(3).
     See Scan Information Data.

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

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

   (1) Sometimes upgrading the player firmware may help.

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

   (3) `libvcd' warns if scan information is missing or syntactically
wrong.

Appendix B ISO 9660 Character Sets
**********************************

B.1 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 _

B.2 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 _

Appendix C Glossary
*******************

See also `http://www.dvdrhelp.com/glossary'.

APS
     Access Point Sector

CBR
     Constant Bit Rate. Used in MPEG-1's.

CD
     Compact Disc

CD-DA
     Compact Disc Digital Audio, described in the "Red Book" or ICE
     908. This commonly referred to as an audio CD and what most people
     think of when you play a CD as it was the first to use the CD
     medium.

CD-ROM
     Compact Disc Read Only Memory or "Yellow Book" describe in
     Standards ISO/IEC 10149. The data stored on it can be either in
     the form of audio, computer or video files.

CD-ROM Mode 1 and Mode2
     The Yellow Book specifies two types of tracks, Mode 1 and Mode 2.
     Mode 1 is used for computer data and text and has an extra error
     correction layer. Mode 2 is for audio and video data and has no
     extra correction layer. CD-ROM/XA An expansion of the CD-ROM Mode
     2 format that allows both computer and audio/video to be mixed in
     the same track.

CD XA
     CD-ROM EXtended Architecture. A modification to the CD-ROM
     specification that defines two new types of sectors.  CD-ROM XA was
     developed jointly by Sony, Philips, and Microsoft, and announced in
     August 1988. Its specifications were published in an extension to
     the Yellow Book.  CD-i, Photo CD, Video CD and CD-EXTRA have all
     subsequently been based on CD-ROM XA.

     CD-XA defines another way of formatting sectors on a CD-ROM,
     including headers in the sectors that describe the type (audio,
     video, data) and some additional info (markers, resolution in case
     of a video or audio sector, file numbers, etc).

     The data written on a CD-XA is consistent with and can be in
     ISO-9660 file system format and therefore be readable by ISO-9660
     file system translators. But also a CD-I player can also read
     CD-XA discs even if its own `Green Book' file system only
     resembles ISO 9660 and isn't fully compatible.

CVD
     Chaoji VCD or China Video Disc
     `http://www.dvdrhelp.com/forum/userguides/98177.php'

DVD
     Digital Versatile Disc  `http://www.dvddemystified.com/dvdfaq.html'

DVD-V
     DVD for Video.

DVD-A
     DVD for Audio.

Entry Point
     A starting point within an MPEG track including the beginning of
     the track.  Video CD's can have multiple entry points inside a
     track. Logically this corresponds to a "Chapter" or "Scene" of a
     larger uninterruptable unit.

     One might think a CD MPEG "track" could serve this purpose with a
     collection of tracks making up a work or movie. Alas, the CD
     specification requires a "track pregap" space of 150 sectors before
     a track. These often appear as a time gaps when hardware players go
     between tracks; this doesn't happen switching between entries in a
     track because there in fact is no gap.

     Physically on the CD an entry is stored as an INDEX inside a track.

FourCC
     A four character code that uniquely identifies a data stream
     format. Software will look up the FourCC code then look for the
     codec associated to the code for that code.  This idea was used in
     the IFF multimedia format developed by Electronic Arts for the
     Amiga in the early 1980s. This file format was copied by Apple
     (who called it AIFF) and Microsoft (RIFF).
     `http://www.fourcc.org/fcccodec.htm'

FSF
     Free Software Foundation, `http://www.fsf.org/'

GNU
     GNU is not UNIX, `http://www.gnu.org/'

LOT
     List ID Offset Table.

MPEG
     Movie Picture Experts Group `http://mpeg.telecomitalialab.com'.
     Two sub formats used by Video CD's are MPEG-1 for VCD 1.0, 1.1 and
     2.0 and MPEG-2. For SVCD, and HQVCD.

NTSC
     National Television Standards Committee. The NTSC is responsible
     for setting television and video standards in the United.  States

OGT
     Overlay Graphics & Text. A subtitle format devised by Philips. The
     format has subtitle meta-information before an interleaved bitmap
     of 4 palette entries. Palette color 0 entries can be run-length
     encoded.

     A more detailed description of this format can be found in the
     documentation directory of VCDimager.

LBA
     Logical Block Addressing. Mapped integer numbers from CD Red Book
     Addressing MSF.  The starting sector is -150 and ending sector is
     449849, which correlates directly to MSF: 00:00:00 to 99:59:74.
     Because an LBA is a single number it is often easier to work with
     in programming than an MSF.

LID
     List ID. A unit of playback control navigation inside a PSD.
     Numbering starts from 1.

LSN
     Logical Sector Number. Mapped integer numbers from CD Red Book
     Addressing MSF.  The starting sector is 0 and ending sector is
     449699, which correlates to MSF: 00:00:00 to 99:59:74.  Because an
     LSN is a single number it is often easier to work with in
     programming than an MSF. Because it starts at 0 rather than -150
     as is the case of an LBA it can be represented as an unsigned
     value.

PAL
     Phase Alternating Line, the dominant television standard in Europe.

PEM
     Program End Marker.

PBC
     Play-back Control.

PSD
     Play Sequence Descriptor. A section of a Video CD related to
     playback control. Also the individual units inside that section.
     We start numbering from 0.  See also LID.

PVD
     Primary Volume Descriptor. A section of a Video CD.

RIFF
     Resource Interchange File Format. A way to tag multimedia files
     developed by Microsoft. Inside a RIFF is a 4-letter character code
     (which fits nicely in a 32-bit word) for each type of object called
     FOURCC. This idea was taken Electronic Arts which used in Amigia's
     IFF (Interchange File Format) and copied by Apple in their AIFF.

SIF
     Source Interchange Format. A video resolution standard.

SPI
     Segment Play Items.

SVCD
     Super VCD `http://www.dvdrhelp.com/svcd'

VBR
     Variable Bit Rate. Used in MPEG-2's

Track
     A unit of data of a CD. The size of a track can vary; it can occupy
     the entire contents of the CD. Most CD standards however require
     that tracks have a 150 frame (or "2 second") lead-in gap.

VCD
     Video CD `http://www.dvdrhelp.com/vcd'

XA
     See CD XA

XML
     eXtensible Markup Language, `http://www.w3.org/XML/'.

XSVCD
     eXtended SVCD, `http://www.dvdrhelp.com/xvcd.htm'.

XVCD
     eXtended VCD, `http://www.dvdrhelp.com/xvcd.htm'.

Appendix D GNU General Public License
*************************************

                         Version 2, June 1991
     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
     59 Temple Place - Suite 330, Boston, MA  02111-1307, USA

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

Preamble
========

The licenses for most software are designed to take away your freedom
to share and change it.  By contrast, the GNU General Public License is
intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

   When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it in
new free programs; and that you know you can do these things.

   To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

   For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

   We protect your rights with two steps: (1) copyright the software,
and (2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

   Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

   Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

   The precise terms and conditions for copying, distribution and
modification follow.

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
  0. This License applies to any program or other work which contains a
     notice placed by the copyright holder saying it may be distributed
     under the terms of this General Public License.  The "Program",
     below, refers to any such program or work, and a "work based on
     the Program" means either the Program or any derivative work under
     copyright law: that is to say, a work containing the Program or a
     portion of it, either verbatim or with modifications and/or
     translated into another language.  (Hereinafter, translation is
     included without limitation in the term "modification".)  Each
     licensee is addressed as "you".

     Activities other than copying, distribution and modification are
     not covered by this License; they are outside its scope.  The act
     of running the Program is not restricted, and the output from the
     Program is covered only if its contents constitute a work based on
     the Program (independent of having been made by running the
     Program).  Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
     source code as you receive it, in any medium, provided that you
     conspicuously and appropriately publish on each copy an appropriate
     copyright notice and disclaimer of warranty; keep intact all the
     notices that refer to this License and to the absence of any
     warranty; and give any other recipients of the Program a copy of
     this License along with the Program.

     You may charge a fee for the physical act of transferring a copy,
     and you may at your option offer warranty protection in exchange
     for a fee.

  2. You may modify your copy or copies of the Program or any portion
     of it, thus forming a work based on the Program, and copy and
     distribute such modifications or work under the terms of Section 1
     above, provided that you also meet all of these conditions:

       a. You must cause the modified files to carry prominent notices
          stating that you changed the files and the date of any change.

       b. You must cause any work that you distribute or publish, that
          in whole or in part contains or is derived from the Program
          or any part thereof, to be licensed as a whole at no charge
          to all third parties under the terms of this License.

       c. If the modified program normally reads commands interactively
          when run, you must cause it, when started running for such
          interactive use in the most ordinary way, to print or display
          an announcement including an appropriate copyright notice and
          a notice that there is no warranty (or else, saying that you
          provide a warranty) and that users may redistribute the
          program under these conditions, and telling the user how to
          view a copy of this License.  (Exception: if the Program
          itself is interactive but does not normally print such an
          announcement, your work based on the Program is not required
          to print an announcement.)

     These requirements apply to the modified work as a whole.  If
     identifiable sections of that work are not derived from the
     Program, and can be reasonably considered independent and separate
     works in themselves, then this License, and its terms, do not
     apply to those sections when you distribute them as separate
     works.  But when you distribute the same sections as part of a
     whole which is a work based on the Program, the distribution of
     the whole must be on the terms of this License, whose permissions
     for other licensees extend to the entire whole, and thus to each
     and every part regardless of who wrote it.

     Thus, it is not the intent of this section to claim rights or
     contest your rights to work written entirely by you; rather, the
     intent is to exercise the right to control the distribution of
     derivative or collective works based on the Program.

     In addition, mere aggregation of another work not based on the
     Program with the Program (or with a work based on the Program) on
     a volume of a storage or distribution medium does not bring the
     other work under the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
     under Section 2) in object code or executable form under the terms
     of Sections 1 and 2 above provided that you also do one of the
     following:

       a. Accompany it with the complete corresponding machine-readable
          source code, which must be distributed under the terms of
          Sections 1 and 2 above on a medium customarily used for
          software interchange; or,

       b. Accompany it with a written offer, valid for at least three
          years, to give any third party, for a charge no more than your
          cost of physically performing source distribution, a complete
          machine-readable copy of the corresponding source code, to be
          distributed under the terms of Sections 1 and 2 above on a
          medium customarily used for software interchange; or,

       c. Accompany it with the information you received as to the offer
          to distribute corresponding source code.  (This alternative is
          allowed only for noncommercial distribution and only if you
          received the program in object code or executable form with
          such an offer, in accord with Subsection b above.)

     The source code for a work means the preferred form of the work for
     making modifications to it.  For an executable work, complete
     source code means all the source code for all modules it contains,
     plus any associated interface definition files, plus the scripts
     used to control compilation and installation of the executable.
     However, as a special exception, the source code distributed need
     not include anything that is normally distributed (in either
     source or binary form) with the major components (compiler,
     kernel, and so on) of the operating system on which the executable
     runs, unless that component itself accompanies the executable.

     If distribution of executable or object code is made by offering
     access to copy from a designated place, then offering equivalent
     access to copy the source code from the same place counts as
     distribution of the source code, even though third parties are not
     compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense or distribute the Program is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

  5. You are not required to accept this License, since you have not
     signed it.  However, nothing else grants you permission to modify
     or distribute the Program or its derivative works.  These actions
     are prohibited by law if you do not accept this License.
     Therefore, by modifying or distributing the Program (or any work
     based on the Program), you indicate your acceptance of this
     License to do so, and all its terms and conditions for copying,
     distributing or modifying the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
     Program), the recipient automatically receives a license from the
     original licensor to copy, distribute or modify the Program
     subject to these terms and conditions.  You may not impose any
     further restrictions on the recipients' exercise of the rights
     granted herein.  You are not responsible for enforcing compliance
     by third parties to this License.

  7. If, as a consequence of a court judgment or allegation of patent
     infringement or for any other reason (not limited to patent
     issues), conditions are imposed on you (whether by court order,
     agreement or otherwise) that contradict the conditions of this
     License, they do not excuse you from the conditions of this
     License.  If you cannot distribute so as to satisfy simultaneously
     your obligations under this License and any other pertinent
     obligations, then as a consequence you may not distribute the
     Program at all.  For example, if a patent license would not permit
     royalty-free redistribution of the Program by all those who
     receive copies directly or indirectly through you, then the only
     way you could satisfy both it and this License would be to refrain
     entirely from distribution of the Program.

     If any portion of this section is held invalid or unenforceable
     under any particular circumstance, the balance of the section is
     intended to apply and the section as a whole is intended to apply
     in other circumstances.

     It is not the purpose of this section to induce you to infringe any
     patents or other property right claims or to contest validity of
     any such claims; this section has the sole purpose of protecting
     the integrity of the free software distribution system, which is
     implemented by public license practices.  Many people have made
     generous contributions to the wide range of software distributed
     through that system in reliance on consistent application of that
     system; it is up to the author/donor to decide if he or she is
     willing to distribute software through any other system and a
     licensee cannot impose that choice.

     This section is intended to make thoroughly clear what is believed
     to be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
     certain countries either by patents or by copyrighted interfaces,
     the original copyright holder who places the Program under this
     License may add an explicit geographical distribution limitation
     excluding those countries, so that distribution is permitted only
     in or among countries not thus excluded.  In such case, this
     License incorporates the limitation as if written in the body of
     this License.

  9. The Free Software Foundation may publish revised and/or new
     versions of the General Public License from time to time.  Such
     new versions will be similar in spirit to the present version, but
     may differ in detail to address new problems or concerns.

     Each version is given a distinguishing version number.  If the
     Program specifies a version number of this License which applies
     to it and "any later version", you have the option of following
     the terms and conditions either of that version or of any later
     version published by the Free Software Foundation.  If the Program
     does not specify a version number of this License, you may choose
     any version ever published by the Free Software Foundation.

 10. If you wish to incorporate parts of the Program into other free
     programs whose distribution conditions are different, write to the
     author to ask for permission.  For software which is copyrighted
     by the Free Software Foundation, write to the Free Software
     Foundation; we sometimes make exceptions for this.  Our decision
     will be guided by the two goals of preserving the free status of
     all derivatives of our free software and of promoting the sharing
     and reuse of software generally.

                                NO WARRANTY
 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
     WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
     HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
     QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
     PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
     SERVICING, REPAIR OR CORRECTION.

 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
     INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
     OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
     OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

                      END OF TERMS AND CONDITIONS
Appendix: How to Apply These Terms to Your New Programs
=======================================================

If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

   To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
     Copyright (C) YYYY  NAME OF AUTHOR

     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.

     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

   Also add information on how to contact you by electronic and paper
mail.

   If the program is interactive, make it output a short notice like
this when it starts in an interactive mode:

     Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items--whatever suits your
program.

   You should also get your employer (if you work as a programmer) or
your school, if any, to sign a "copyright disclaimer" for the program,
if necessary.  Here is a sample; alter the names:

     Yoyodyne, Inc., hereby disclaims all copyright interest in the program
     `Gnomovision' (which makes passes at compilers) written by James Hacker.

     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice

   This General Public License does not permit incorporating your
program into proprietary programs.  If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library.  If this is what you want to do, use the
GNU Library General Public License instead of this License.

Appendix E GNU Free Documentation License
*****************************************

                        Version 1.1, March 2000
     Copyright (C) 2000 Free Software Foundation, Inc.
     59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     written document "free" in the sense of freedom: to assure everyone
     the effective freedom to copy and redistribute it, with or without
     modifying it, either commercially or noncommercially.  Secondarily,
     this License preserves for the author and publisher a way to get
     credit for their work, while not being considered responsible for
     modifications made by others.

     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.
     We recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work that contains a
     notice placed by the copyright holder saying it can be distributed
     under the terms of this License.  The "Document", below, refers to
     any such manual or work.  Any member of the public is a licensee,
     and is addressed as "you".

     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A "Secondary Section" is a named appendix or a front-matter
     section of the Document that deals exclusively with the
     relationship of the publishers or authors of the Document to the
     Document's overall subject (or to related matters) and contains
     nothing that could fall directly within that overall subject.
     (For example, if the Document is in part a textbook of
     mathematics, a Secondary Section may not explain any mathematics.)
     The relationship could be a matter of historical connection with
     the subject or with related matters, or of legal, commercial,
     philosophical, ethical or political position regarding them.

     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in
     the notice that says that the Document is released under this
     License.

     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.

     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, whose contents can be viewed and edited directly
     and straightforwardly with generic text editors or (for images
     composed of pixels) generic paint programs or (for drawings) some
     widely available drawing editor, and that is suitable for input to
     text formatters or for automatic translation to a variety of
     formats suitable for input to text formatters.  A copy made in an
     otherwise Transparent file format whose markup has been designed
     to thwart or discourage subsequent modification by readers is not
     Transparent.  A copy that is not "Transparent" is called "Opaque".

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and
     standard-conforming simple HTML designed for human modification.
     Opaque formats include PostScript, PDF, proprietary formats that
     can be read and edited only by proprietary word processors, SGML
     or XML for which the DTD and/or processing tools are not generally
     available, and the machine-generated HTML produced by some word
     processors for output purposes only.

     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow
     the conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies of the Document numbering more than
     100, and the Document's license notice requires Cover Texts, you
     must enclose the copies in covers that carry, clearly and legibly,
     all these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the
     title equally prominent and visible.  You may add other material
     on the covers in addition.  Copying with changes limited to the
     covers, as long as they preserve the title of the Document and
     satisfy these conditions, can be treated as verbatim copying in
     other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a
     machine-readable Transparent copy along with each Opaque copy, or
     state in or with each Opaque copy a publicly-accessible
     computer-network location containing a complete Transparent copy
     of the Document, free of added material, which the general
     network-using public has access to download anonymously at no
     charge using public-standard network protocols.  If you use the
     latter option, you must take reasonably prudent steps, when you
     begin distribution of Opaque copies in quantity, to ensure that
     this Transparent copy will remain thus accessible at the stated
     location until at least one year after the last time you
     distribute an Opaque copy (directly or through your agents or
     retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of
     copies, to give them a chance to provide you with an updated
     version of the Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with
     the Modified Version filling the role of the Document, thus
     licensing distribution and modification of the Modified Version to
     whoever possesses a copy of it.  In addition, you must do these
     things in the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of
          previous versions (which should, if there were any, be listed
          in the History section of the Document).  You may use the
          same title as a previous version if the original publisher of
          that version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has less than five).

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document's
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section entitled "History", and its title, and
          add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on
          the Title Page.  If there is no section entitled "History" in
          the Document, create one stating the title, year, authors,
          and publisher of the Document as given on its Title Page,
          then add an item describing the Modified Version as stated in
          the previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in
          the "History" section.  You may omit a network location for a
          work that was published at least four years before the
          Document itself, or if the original publisher of the version
          it refers to gives permission.

       K. In any section entitled "Acknowledgments" or "Dedications",
          preserve the section's title, and preserve in the section all
          the substance and tone of each of the contributor
          acknowledgments and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document,
          unaltered in their text and in their titles.  Section numbers
          or the equivalent are not considered part of the section
          titles.

       M. Delete any section entitled "Endorsements".  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section as "Endorsements" or to
          conflict in title with any Invariant Section.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option
     designate some or all of these sections as invariant.  To do this,
     add their titles to the list of Invariant Sections in the Modified
     Version's license notice.  These titles must be distinct from any
     other section titles.

     You may add a section entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties--for example, statements of peer review or that the text
     has been approved by an organization as the authoritative
     definition of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end
     of the list of Cover Texts in the Modified Version.  Only one
     passage of Front-Cover Text and one of Back-Cover Text may be
     added by (or through arrangements made by) any one entity.  If the
     Document already includes a cover text for the same cover,
     previously added by you or by arrangement made by the same entity
     you are acting on behalf of, you may not add another; but you may
     replace the old one, on explicit permission from the previous
     publisher that added the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination
     all of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections entitled
     "History" in the various original documents, forming one section
     entitled "History"; likewise combine any sections entitled
     "Acknowledgments", and any sections entitled "Dedications".  You
     must delete all sections entitled "Endorsements."

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the
     documents in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow
     this License in all other respects regarding verbatim copying of
     that document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of
     a storage or distribution medium, does not as a whole count as a
     Modified Version of the Document, provided no compilation
     copyright is claimed for the compilation.  Such a compilation is
     called an "aggregate", and this License does not apply to the
     other self-contained works thus compiled with the Document, on
     account of their being thus compiled, if they are not themselves
     derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one
     quarter of the entire aggregate, the Document's Cover Texts may be
     placed on covers that surround only the Document within the
     aggregate.  Otherwise they must appear on covers around the whole
     aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License provided that you also include the
     original English version of this License.  In case of a
     disagreement between the translation and the original English
     version of this License, the original English version will prevail.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided for under this License.  Any other
     attempt to copy, modify, sublicense or distribute the Document is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

 10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     `http://www.gnu.org/copyleft/'.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If
     the Document does not specify a version number of this License,
     you may choose any version ever published (not as a draft) by the
     Free Software Foundation.

ADDENDUM: How to use this License for your documents
====================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

       Copyright (C)  YEAR  YOUR NAME.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.1
       or any later version published by the Free Software Foundation;
       with the Invariant Sections being LIST THEIR TITLES, with the
       Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
       A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.

   If you have no Invariant Sections, write "with no Invariant Sections"
instead of saying which ones are invariant.  If you have no Front-Cover
Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
LIST"; likewise for Back-Cover Texts.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.