Structure of the GNU VCDImager XML file

last updated: 20-Dec-2002 | introduction | general | detailed | conclusions | back to index

Donate! If you like using this guide, then please help with its development by donation!  You can do so by clicking on the button to the left.  The donation is handled securely via PayPal.  Thank you.

The following information is derived from the GNU VCDImager manual.

Introduction

GNU VCDImager v0.7.0 and above uses an XML file to describe the structure of the video CD (VCD) or super video CD (SVCD). Through the use of the included command line program VCDXGEN.EXE, or one of the third party graphical user interfaces (GUIs), a simple XML of the putative VCD can be created. The XML file can then be further edited (via a simple text editor) to create the desired interactivity on the VCD.

This XML "descriptor" file can then be processed with VCDXBUILD.EXE and a CUE/BIN disc image of the VCD generated. This disc image can then subsequently be recorded onto CD-R or CD-RW media.

Although there is a relatively steep learning curve involved with editing the XML file to create the desired interactivity, once mastered, it is relatively simple. Anyone with any experience with HTML should be able to quickly understand the basics. Most of the difficulty, in fact, is in understanding what sort of interactivity a S/VCD is capable of.

 

General structure of the XML file

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

<videocd> 
	<option />

	<info>
	</info>

	<pvd>
	</pvd>

	<filesystem>
	</filesystem>

	<segment-items>
	</segment-items>

	<sequence-items>
	</sequence-items>

	<pbc>
	</pbc>
</videocd>

Generally, the following sections are used for:

<videocd> This defines whether the VCD created will be VCD1.1, VCD2.0 or SVCD. For info on the differences between these, read the manual that comes with VCDImager.
<option> This element allows for the use of a number of optional settings in VCDImager.
<info> This section defines some information about the VCD.
<pvd> This section defines the "primary volume descriptor". Again, it's some information about the VCD.
<filesystem> This section allows you to add additional files to the ISO9660 filesystem to the VCD.
<segment-items> This section allows you to reference the media files that will be placed in the "SEGMENT" area/folder of the VCD. The most common item that are placed here as segment items are MPEG still images used for menus.
<sequence-items> This section allows you to reference the MPEG video clips that will be placed on the S/VCD
<pbc> This is usually the main section of the XML file. The "play back control" of the VCD is authored here. This is the section where the menus, playlists, etc., are authored.

 

Detailed examination of the individual sections

What is written here is not comprehensive, but rather, an instructive guide to authoring VCDs using the XML system in VCDImager. For a complete list of all the possible tags and functions, read the manual that comes with GNU VCDImager and have a look at the VIDEOCD.DTD file.

 

<videocd>

An example:

 

<videocd xmlns="http://www.gnu.org/software/vcdimager/1.0/" class="vcd" version="2.0">

 

xmlns: This defines a URL. Just leave it alone.
class: vcd (standard video-CD)
svcd (super video-CD)
version: 1.0, 1.1 or 2.0 (this is context specific, read below)

 

Possible values:

class="vcd" version="1.1" VCD1.1
class="vcd" version="2.0" VCD2.0
class="svcd" version="1.0" SVCD 1.0 (IEC-62107)

 

<option>

This element is optional. If you are not invoking any of these options (that is, not changing them from their default values), then there is no need to include this in your XML file at all.

An example:

 

<option name="relaxed aps" value="true"/>

 

Possible values:

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

This is required by some stand-alone DVD players for SVCDs to play properly.

Default: false

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

This is required by some stand-alone DVD players for SVCDs to play properly

Default: false

name = "relaxed aps" This controls whether APS constraints are strict or relaxed.

This setting refers to the placement of "entrypoints". If the MPEG-1 file doesn't have regular MPEG sequence headers throughout the file (e.g., before each GOP), then you must set this option to true for entrypoints to be placed at the desired positions. Although this will work on some stand-alone players, on others, they will need the sequence header to play the track properly. Thus, it is better to put the MPEG sequence headers in your MPEG stream rather than to force VCDImager to use this option.

Default: false — note: access point sectors in the VCDImager manual

name = "update scan offsets" This controls whether to update the scan data information contained in the MPEG-2 video streams

This can correct the scan information in the MPEG-2 video stream.

Default: false

 

<info>

This section contains some information about the VCD being authored. An example:

  <info>
    <album-id>DEMO_VCD</album-id>
    <volume-count>1</volume-count>
    <volume-number>1</volume-number>
    <restriction>0</restriction>
  </info>

A number of elements are allowed for under <info> (e.g., <album-id> in the above example). These include:

<album-id> Name of the "album" of the S/VCD
<volume-count> ?Total number of discs in the S/VCD album
<volume-number> ?Number of the current disc in album (e.g., the volume-count may be 2, while the current disc is 1 — that is, disc 1 of 2)
<next-volume-use-sequence2> ?? — but not essential in most discs
<next-volume-use-lid2> ?? — but not essential in most discs (these two tags refer to the ability of some multi-disc stand-alone players to instantly start playing the next disc once the current disc as finished playing)
<restriction> ?? — not essential in most discs
<time-offset> ?? — not essential in most discs

 

<pvd>

This part of the XML describes the primary volume descriptor of the disc. An example:

  <pvd>
    <volume-id>PAL_VCDDEMO</volume-id>
    <system-id>CD-RTOS CD-BRIDGE</system-id>
    <application-id>CDI/CDI_VCD.APP;1</application-id>
    <preparer-id/>
    <publisher-id>MICHAEL TAM - VITUALIS PRODUCTIONS</publisher-id>
  </pvd>

A number of elements are available under the <pvd> section, e.g., the <volume-id> tag in the above example.

<volume-id> This sets the volume name of the VCD (i.e., the name of the VCD that will appear when you place it in your PC's CD-ROM drive). Remember, there is a limited character set and the length is limited to 11 characters. Read the VCDImager manual for the character set available.
<system-id> ?? — unsure of the significance of this
<application-id> This sets the location and name of the CD-i application on the VCD. This is required for the play back of the VCD in a CD-i player. CD-i compatibility is required for a VCD to be White Book compliant. In the above example, the CD-i application is the file "CDI_VCD.APP" in the CD-i folder of the VCD.

SVCDs do not support CD-i players so neither the CD-i application or this tag is required.

<preparer-id> This tag can be ignored. VCDImager will place some information about itself here (despite what you put down — you can use VCDXRIP on the built disc image to see what VCDImager puts here).
<publisher-id> Information about the author can be place here.

 

<filesystem>

This section of the XML file allows for the creation of additional folders and files into the ISO9660 filesystem on the VCD. An example:

  <filesystem>
    <folder>
      <name>EXTRA</name>

      <file src="source_file.txt" format="form1">
        <name>source.txt</name>
      </file>

    </folder>
  </filesystem>

Within the <filesystem> section, the element/container "folder" and the element "file" are available.

<folder> This creates an additional folder on the ISO9660 filesystem.
  <name> If it is used within the <folder></folder> tags, then this gives the NAME of the folder. In the above example, the name of the folder is "EXTRA".

Note, there is a limited character set that you can use and the folder names are limited to the 8+3 format. You must give the folder a name, and you can obviously only name any given folder once.

<file> src = the location of the source file — if the full directory isn't given, the location of the file is presumed to be in the same directory as the XML file

format = "form1" — file is added to the filesystem in form1 sectors (default)

format = "mixed" — ??mixed mode sectors are used — unsure of significance, but not required for normal files — it is required for the CD-i application, however.

  <name> This is used in a similar way as <name> is used under the <folder> element. The same restrictions in the character set and 8+3 format applies.

Note: If the <file> element is used WITHIN the <folder></folder> tags, then that file will be created within that folder. In the above example, the file "SOURCE.TXT" is placed within the folder "EXTRA".

Similarly, if the <file> element is used OUTSIDE of a <folder></folder> set of tags, then that file will be created in the root directory of the VCD.

 

<segment-items>

An example:

  <segment-items>
    <segment-item src="mainmenu.mpg" id="seg-mainmenu"/>
  </segment-items>

The only element under the section <segment-items> is <segment-item>. The meaning of the values in segment-item:

src = Location of the source file. In the above example, the source file is called "mainmenu.mpg" and is located in the same folder as the XML file.
id = The name that this "segment-item" will be referred to as in the XML. In the above example, this segment item will be referred to as "seg-mainmenu" in the rest of the XML file.

 

Segment items are those media files that are written in the first track of the VCD and are located in the "SEGMENT" folder of the filesystem. Usually, only items pertaining to menus are placed here. The types of media files that can be placed here include: MPEG still images, MPEG video clips, and audio-only MPEG clips.

It's a good idea to name segment items (i.e., the "id" value) in a sensible way. Otherwise, it may be confusing later on.

 

<sequence-items>

An example:

  <sequence-items>
    <sequence-item src="track1.mpg" id="seq-track1"/>

    <sequence-item src="track2.mpg" id="seq-track2">
      <entry id="chapter1">0.00</entry>
      <entry id="chapter2">30.00</entry>
      <entry id="chapter3">60.00</entry>
    </sequence-item>

    <sequence-item src="track3.mpg" id="seq-track3">
      <auto-pause>30</auto-pause>
      <auto-pause>60</auto-pause>
    </sequence-item>

  </sequence-items>

The element under <sequence-items> is logically <sequence-item>. The meaning of the values of <sequence-item> is quite similar to that of <segment-item>:

src = The name and location of the source MPEG video clip. In the above example, the names of the source files are "track1.mpg", "track2.mpg" and "track3.mpg" and they are located in the same folder as the XML file.
id = The name that the sequence item will be referred to as in the rest of the XML file. In the above example, these three tracks well be referred to as "seq-track1", "seq-track2" and "seq-track3".

Again, it is a good idea to name sequence items in a logical way.

The MPEG files referenced under <sequence-items> must be S/VCD compliant MPEG-1/2 video clips which are longer than 4 seconds in length. Each of the MPEG video clips referenced in <sequence-items> is recorded as a separate track on the VCD. The order in which they are referenced are the order of the tracks as they will be burnt. In the above example, the first video track on the VCD will be created from "track1.mpg", the second from "track2.mpg" and the third from "track3.mpg".

Under <sequence-item>, two additional elements are supported:

<entry> This allows for the definition of "entrypoints".

"id" is the name of the entrypoints (in the above example, the names of the three entrypoints are "chapter1", "chapter2" and "chapter3").

The numerical value gives the starting point of the entrypoint in seconds from the beginning of that sequence-item (i.e., MPEG track). That is:

chapter1: starts at the beginning of track2.mpg

chapter2: starts at 30s of track2.mpg

chapter3: starts at 60s of track2.mpg

A total of 500 entrypoints can be referenced in a VCD with a 99 entrypoint limit on any one sequence-item.

<auto-pause> This allows for the definition of "autopause" points.

The numerical value gives these points in seconds from the beginning of the sequence-item (i.e., MPEG track). This works in conjunction with the <autowait> tag in playlists:

<auto-pause> defines WHERE/WHEN to pause

<autowait> defines HOW LONG to pause

In the above example, if "seq-track3" is used in a playlist, then depending on the <autowait> setting, playback will automatically pause at the 30s and 60s mark.

 

<auto-pause> and <entry> settings can be used concurrently in the same <sequence-item>.

<auto-pause> settings should NEVER be defined on a <sequence-item> that is intended to be used in a <selection>. This application of <auto-pause> in this case is not defined and can lead to inconsistent playback depending on the VCD player's interpretation.

 

<pbc>

This is the part of the XML file where the real authoring takes place. The above sections simply defined options and referenced files to be used in the VCD. The section is too large to give a simple example. Rather, examples of the three elements under <pbc> will be given. These elements are:

<playlist> This is used to give simple playback of a media file (still, video track, audio only). Interactivity is limited.
<selection> This is used if more "selections" or "interactive choices" are required.
<endlist> This is used to end the VCD playback and PBC interpretation (i.e., as if you pressed "STOP").

 

<playlist>

An example:

    <playlist id="play-track1">
      <prev ref="play-track0"/>
      <next ref="play-track2"/>
      <return ref="select-mainmenu"/>
      <playtime>0</playtime>
      <wait>0</wait>
      <autowait>0</autowait>
      <play-item ref="seq-track1"/>
    </playlist>

 

Interpretation of this example:

 

Meaning of values:

id = The name that this <playlist> will be referenced by for the entire XML file. Again, logical naming is a virtue.

 

Under <playlist>, there are a number of elements:

<prev> ref = name of item to go to when the "PREV" button is selected by the user. This item must be another <playlist>, <selection>, or <endlist>. In the above example, if "PREV" is used, then "play-track0" will be chosen.

If the <prev> function is not required or desired, then you can simply leave this element out (pressing "PREV" will do nothing).

<next> ref = name of item to go to when the "NEXT" button is selected by the user. There are similar constraints as above. In the above example, if "NEXT" is used, then "play-track2" will be chosen.

Also, when the current <playlist> has finished playing, it will also automatically go to the item defined in <next>.

Like above, this element can be left out if its functionality isn't required.

<return> ref = name of item to go to when the "RETURN" button is selected by the user. In the above example, if "RETURN" is used, then "select-mainmenu" will be chosen.

This element can be left out if its functionality isn't required

<playtime> The value here determines how long that the playlist will play for in seconds. For example, if the value is 60, then the <play-item> will play for 60s only.

If the value is 0 (default), then it will play the entire <play-item>. This element can be left out if the intention is to play the entire <play-item>.

<wait> The value determines how long in seconds that the VCD will pause after the playlist has finished playing. For example, if the value is 5, then there will be a 5s pause before going to the item defined in <next>.

If the value is 0 (default), then there will be no/minimal pause before going to the next item.

If the value is -1, then the VCD will pause indefinitely (until "NEXT", "PREV" or "RETURN" is pressed).

<autowait> The value determines how long in seconds that the VCD will pause when an <auto-pause> point is reached. <auto-pause> settings are defined under <sequence-item>.

If the value is 0 (default), then there will be NO autowait even if <auto-pause> settings have been defined.

If the value is -1, then the VCD will pause indefinitely at the first <auto-pause> point.

If no <auto-pause> settings have been defined for the <sequence-item> referenced in the <play-item>, then the <autowait> tag is meaningless. This element can be left out if there is no intention to use the <autowait> feature.

<play-item> ref = name of the item to play (can be either a <segment-item> or a <sequence-item> ).

 

If a <playlist> is used for an MPEG still image (i.e., a <segment-item> ), then the <wait> setting must be set to something other than 0.

If <playlist> items ar used for a multi-track VCD, playback from one <playlist> to the next WILL NOT be seamless, even if the <wait> setting is 0. For DVD-style "chapters", then "entrypoints" must be used.

 

<selection>

An example:

    <selection id="select-mainmenu">
      <bsn>1</bsn>
      <prev ref="play-intro"/>
      <next ref="select-mainmenu2"/>
      <return ref="play-opening"/>
      <default ref="play-track1"/>
      <timeout ref="play-opening"/>
      <wait>60</wait>
      <loop jump-timing="delayed">1</loop>
      <play-item ref="seg-mainmenu"/>
      <select ref="play-track1"/>
      <select ref="select-ss1"/>
    </selection>

Interpretation of this example:

 

Meaning of values:

id = The name that this <selection> will be referenced by for the entire XML file. Logical naming is a virtue.

 

Under <selection>, there are a number of elements:

<bsn> This is the base selection number. The first numerical choice is numerically the number that is defined here. In the above example, the first selection choice is "1" and the second "2".

For example, if the <bsn> defined was "5", then the first selection choice would be "5" and the second "6", and etc.

<prev> ref = name of item to go to when the "PREV" button is selected by the user. This item must be another <playlist>, <selection>, or <endlist>. In the above example, if "PREV" is used, then "play-intro" will be chosen.

If the <prev> function is not required or desired, then you can simply leave this element out (pressing "PREV" will do nothing).

<next> ref = name of item to go to when the "NEXT" button is selected by the user. There are similar constraints as above. In the above example, if "NEXT" is used, then "select-mainmenu2" will be chosen.

When the current <selection> background has finished playing, it DOES NOT automatically go to the item defined in <next>. This is an IMPORTANT DIFFERENCE between the behaviour of <playlist> and <selection>.

This element can be left out if its functionality isn't required.

<return> ref = name of item to go to when the "RETURN" button is selected by the user. In the above example, if "RETURN" is used, then "play-opening" will be chosen.

This element can be left out if its functionality isn't required.

<default> ref = name of item to go to when the "DEFAULT" button is selected by the user. In the above example, if "DEFAULT" is used, then "play-opening" will be chosen.

This element can be left out if its functionality isn't required.

<timeout> ref = name of the item to go to when <wait> time is over. In the above example, when <wait> time is over, the VCD will automatically go to "play-opening"

This doesn't have to be defined (i.e., can be left out) if <wait> is on indefinite, or <loop> is on indefinite.

If <wait> time is over and <timeout> isn't defined, then the VCD will choose one of the <select> choices at random (this is a method to author a random event on a VCD).

<wait> The value determines how long in seconds that the VCD will pause after the <selection> has finished playing and looping. In the above example, the VCD will pause for 60s before going to the item defined in <timeout>.

If the value is 0 (default), then there will be no/minimal pause before going to the timeout item.

If the value is -1, then the VCD will pause indefinitely (until "NEXT", "PREV", "RETURN", "DEFAULT" or one of the numerical key presses is pressed).

<loop> jump-timing = immediate (default) — VCD reacts immediately to a key press (especially relevant where the <play-item> of the <selection> is a movie clip rather than a still)

jump-timing = delayed — VCD doesn't execute user's choice until <play-item> has finished playing

The number defined is the number of times that <play-item> will be looped before going to <wait>. If the value is 0, then the <play-item> will be looped indefinitely

<play-item> ref = name of the item to play (can be either a <segment-item> or a <sequence-item> ).
<select> ref = name of the item to go to when the relevant numeric key press is chosen. There can be multiple <select> defined. The first one has a numerical key press assigned as the same value as <bsn>. All subsequent <select> have values consecutively larger.

If numerical key press choices are not required, no <select> needs to be defined.

 

If the <selection> has an MPEG still image as the <play-item> (i.e., the background), then be sure the <loop> value is set to "1" (i.e., the VCD displays the background once only), and set the <wait> value to a suitable time. Setting a loop value greater than 1 or indefinite can have unpredictable effects depending on the interpretation of the VCD player.

If the <selection> has a video clip as the <play-item>, then be sure the "jump-timing" in <loop> is set to "immediate". Otherwise, user input may not be possible until the <play-item> has finished playing.

Furthermore, if a <sequence-item> is used as the <play-item> in a <selection>, be sure that <auto-pause> settings ARE NOT defined. If they are, then the <selection> will play in an unpredictable way, depending on the interpretation of the VCD player.

Also, make sure that <timeout> is defined if the random choice function is not desired (usually isn't). If <wait> time is over and <timeout> isn't defined AND there are no <select> choices, the VCD player may hang. This scenario isn't defined in White Book.

Understanding of all the possible instructions in <selection> is probably the most difficult part in authoring VCDs. However, once mastered, you should be able to create stunningly authored VCDs.

 

Conclusions

The XML used with GNU VCDImager isn't hard to master, but as with all things, there is a learning curve. Luckily, the syntax of the XML is relatively simple and familiar, especially for anyone with some HTML experience.

The most difficult part of learning to use the XML system is actually learning how PBC on VCDs work. This knowledge once gained, can be applied to other VCD authoring programs as well.

A number of simple GUIs have been recently released for GNU VCDImager that can create some PBC structures in XML. Although simplifying the task of creating XML files, manual editing with a text editor is still required for a truly customised VCD.

 


Michael Tam <vitualis (at) michaeltam.com>
anti-spam device - replace (at) with @ to send me e-mail

(c) 20 December, 2002