next_inactive up previous


VCDMeta Version 0.20

Kevin Atkinson
kevina@gnu.org


Contents

1. Introduction

VCDMeta is a Perl script which makes creating easy to navigate VCD extremely simple. It takes in a simplified XML documents which simply contains a list of the Videos you want to include and how you want them to be arranged. From that it will output a XML document suitable for use with vcdimager complete with easy to navigate menus. A text file ``0VCDINDX.TXT'' is also created which contains the complete contents of the CD for easy navigations when reading the VCD on a computer without VCD menu support. If images are not provided for the menus it will create the menus for you. When the supplied patch is applied to VCDImager, VCDMeta can generating special easy to use mpeg files for use on a computer complete with an HTML index.

2. Requirements

For verifying the input XML file:

For creating and converting images:

For converting images into mpeg stills:

VCDMeta has not been tested on platforms where Image::Magick is not installed. At very least the line:

use Image::Magick;
needs to be commented out in VCDMeta. When Image::Magick is not installed the menu images need to be provided as mpeg stills or else the VCDMeta will give errors about not being able to find methods via the Image::Magick package.

So far VCDMeta has only been testing on Linux but it should work on any Unix like operating system. It should also work on Windows provided the right Perl modules are installed with a little effort. I believe all the required libraries and tools have been ported to Windows, but I have not actually tested VCDMeta on Windows. A windows port of mjpegtools can be found with VCDEasy (http://www.vcdeasy.org/).

3. Installation

To install simply unpack the tarbar somewhere such as /usr/local:

cd /usr/local/ 
tar xfvz vcdmeta-X.tar.gz
where X is the version of the VCDMeta. If "tar xfvz" doesn't work try "gtar xfvz" or "gunzip -c vcdmeta-X.tar.gz | tar xfv -". This will create a directory ``vcdmeta-X''. If necessary edit the paths at the top of the VCDMeta script. Then add this directory to your path or create a symbolic link to VCDMeta in a directory already in your path. For example:

cd /usr/local/bin/ 
ln -s /usr/local/vcdmeta-X/vcdmeta
Do not just copy the VCDMeta script. If you do VCDMeta will not be able to find its data files.

That should be all thats required.

By default some free Type 1 fonts are used for menu creation. For nicer looking menus VCDMeta can use Windows (or any other) True Type fonts. See the top of VCDMeta for what to do to enable them.

4. Status

So Far VCDMeta has only been extensively tested when creating NTSC VCDs. I have verified that VCDMeta runs without errors when creating PAL VCDs but I have not actually tested the VCDs as I have no way of playing them on my DVD player and I have not found any free software that will play VCDs with menu support. Furthermore, even though using mpeg movies for menus should work, this has not been tested at all.

The latest version of VCDMeta can be found at http://kevin.atkinson.dhs.org/vcdmeta/.

5. XML Syntax

First the header:

<?xml version="1.0"?> 
<!DOCTYPE videocd-meta SYSTEM "videocd-meta.dtd">
since the DTD is not stable yet I have chosen not to make it public. Once I am happy with it I will find a place to put it on the web and make it public.

5.1 videocd-meta

The root element is videocd-meta. It has the following required parameters

album-id
The album-id same as the album-id for vcdimager
norm
either "ntsc" or "pal"
class
must be "vcd" for now
and the following optional parameters:

title
The title for the VCD. No limitation on which characters that can be used
extra
Additional information on the VCD. Displayed below the main title in smaller text when creating menus.
volume-id
The volume-id as given to vcdimager, if it is not given it will be the same as album-id
publisher-id
The publisher-id as given to vcdimager
nice-mpeg-file-names
either ``true'' or ``false'' see section 7 for more info.
create-mpeg-link-files
either ``true'' or ``false'' see section 8 for more info.
The videocd-element contains the following elements (in the order given)

5.2 filesystem

The first optional element inside videocd-meta is "filesystem". This is for adding additional files to the filesystem on the VCD. Its syntax is similar to that used by vcdimager but not the same as I really didn't like how the DTD was done.

The filesystem can contain any number of "folder", and "file" elements.

A folder takes one required parameter, "name" which is simply the name of the folder. The contents of the folder are the exact same as there are for the filesystem element that is it can contain any number of "folder", and "file" elements.

The file element has one required parameter: "src", and two optional ones: "name" and "format". The "src" is the name of the file to include. The "name" is the name of the file as it will appear on the CD. If defaults to the basename of "src" if it is not given. The "format" can either be "form1" or "mixed" and if given is passed on to vcdimager as is.

Here is an example of a really stupid filesystem:

<filesystem>
<folder name="bla">
<folder name="bla2">
<file src="bla.txt"/>
<file src="dkldkldkld.hxj" name="kdlkdl.djk"/>
</folder>
<file src="bla.txt"/>
<file src="dkldkldkld.hxj" name="kdlkdl.djk"/>
</folder>
<file src="bla.txt"/>
<file src="dkldkldkld.hxj" name="kdlkdl.djk"/>
</filesystem>

5.3 options

The next optional element in videocd-meta is "options". It contains several optional parameters: ``auto-split'', "menu-wait", "menu-loop", "menu-video-wait", all of which control defaults for the "page" elements. The meaning of these parameters will be explained latter.

5.4 page

Every VCD must contain at least one page. Multiple pages may be specified. Each page has the following optional parameters:

title
The title used for this page. By default it is the same as the group title.
extra
Supplementary information for this page displayed below the title. By default it is the same as the group.
auto-split
Whether to auto split this page if there are more menu items on this page than can fit on a single screen. Either ``true'' or ``false''. By default it is set to true unless the ``auto-split'' option for this group is false. If more than one page is specified for any particular group this false is automatically set to false.
src
the source image for the menu. If the extensions is ".m1p" than is assumed to be a mpeg still. If the extension is ".mpg" or ".mpeg" than it is assumed to be an mpeg movie. Otherwise it is assumed to be an image. The image will be converted into an mpeg still for you. The format of the image can be any format ImageMagick can recognize which included jpeg, gif, png, and many others. The image will automatically scaled to the correct size. Finally if this parameter is left out a menu will be created for you.
wait
how long to wait after the image is displayed or video sequence is complete. A value of "-1" means to wait indefinitely until an choice is made. Defaults to "-1" for the root menu. Otherwise defaults to the value of the "menu-wait" parameter specified in the options element if src is a still, or "menu-video-wait" if src is a mpeg video.
loop
how many times to loop an mpeg video. A value of 0 means to loop forever until a choice is made. Defaults to 0 for the root menu or "menu-loop" otherwise. This option should only be specified if src is an mpeg video.
The defaults for the parameters of the "options" element are as follows:

auto-split true
menu-wait 30
menu-loop 1
menu-video-wait 0

Each page then contains 1 or more "video" and "group" elements in any order. If the auto-split parameter is set to true any number of elements can be specified. If more menu items are specified than can fit on a page than the page will automatically be split into 2 or more pages. If the auto-split parameter is set to false than a maximum of 9 items can be specified if there is one page. If there is more than one page than a maximum of 8 items can be specified for each page except for the last in which case a maximum of 9 items can be specified.

5.5 video

The "video" element is for an actual mpeg video. It contains the following parameters:

src
the mpeg file (required)
fname
the mpeg file name to use if ``nice-mpeg-file-names'' is set.
title
the title of the video as it will appear in the menu
extra
any additional information for the video. This will appear in smaller type below the video's title in the menu if there is room.

5.5.1 entry

The video element may contain any number of ``entry'' points. An entry point is simply a way of skipping into the middle of an mpeg movie. Each entry point creates a separate menu item as if it was a separate video. A video can have any number of entry points up until the limits of the VCD standard. The ``entry'' elements contains the following parameters:

time
the position in the mpeg movie. This can either be given in seconds or ``minute:seconds'' format. For example to set the time position to 90 seconds the time parameter can either be ``90'' or ``1:30''. (required)
fname
the mpeg link file name to use if ``create-mpeg-link-files'' is set. If not set, then it is derived from the corresponding video ``fname''.
title
the title of the entry point as it will will appear in the menu. Treated the exact same way as the title parameter for the video element
extra
any additional information for the entry point. Treated the exact same way as the extra parameter for the video element
If an entry point at time ``0'' is not defined it will automatically be created for you. The title and extra parameter will be the same as the video's title and extra.

5.6 group

The "group" element is for creating a sub-menu. It has the following parameters:

title
the title of the group
menu-title
the title of the group as it will appear in the menu choice for this group. Defaults to "title".
extra
any additional information for the video. This will appear in smaller type below the group's title.
menu-extra
any additional information as it will appear in the menu choice. Defaults to "extra".
Instead of writing this:

menu-title = "60 Minutes, July 2002"
menu-extra = "Dancing With Wolves"
title = "60 Minutes"
extra = "July 2002"
You can instead:

title = "60 Minutes,, July 2002"
menu-extra = "Dancing With Wolves"
Notice the double comma in the title. A similar thing can be done with a double colon (::), or double semi-colon (;;)

The contents of the "group" elements is almost the same as the videocd-meta element except that the filesystem element is not allowed. More specifically the group may contain the following elements which behave the same way as the do in videocd-meta unless otherwise specified.

options
any options specified control the defaults for this group and any of its sub-groups
page
(required)

5.7 Examples

And thats all there is to it. Here are some illustrative examples. A basic single level menu VCD:

<?xml version="1.0"?> 
<!DOCTYPE videocd-meta SYSTEM "videocd-meta.dtd"> 
<videocd-meta 
  album-id = "SIMPLE" 
  title    = "Simple Sample VCD" 
  norm     = "ntsc" 
  class    = "vcd" 

  <page> 
    <video title="Video 1" src="video1.mpg"/> 
    <video title="Video 2" src="video1.mpg"/> 
    <video title="Video 3" src="video3.mpg"/> 
  </page> 
</videocd-meta>
A more complex VCD:

<?xml version="1.0"?> 
<!DOCTYPE videocd-meta SYSTEM "videocd-meta.dtd"> 
<videocd-meta 
  album-id = "COMPLEX" 
  title    = "Complex Sample VCD" 
  norm     = "ntsc" 
  class    = "vcd" 

  <options menu-wait="15"/> 
  <page src="root.mpg"/> 
    <group title="Menu One"> 
      <page src="menu1.png"/> 
        <video src="video1.mpg"> 
          <entry time="0" title="Video 1 Part 1"/> 
          <entry time="30" title="Video 1 Part 2"/> 
        </video> 
        <video title="Video 2" extra="Video 2 Description" 
               src="video1.mpg"/> 
      </page> 
    </group> 
    <group title="Menu Two,, 2001" 
           menu-extra="Menu Two Description"> 
      <page>  
        <video title="Video 3" src="video3.mpg"/> 
        <video title="Video 4" src="video4.mpg"/>  
      </page>  
    </group> 
  </page> 
</videocd-meta>
This VCD uses the options element to set the default wait time to 15 seconds instead of the usual 30. It has two sub menus and 4 videos with video 1 having two entry points. The root menu uses a mpeg movie instead of the default menu created by VCDMeta while Menu 1 uses an png file. Menu Two uses the short cut discussed in 5.6.

6. Layout of the Videocd

VCDMeta will lay out the videocd in a manner which makes navigating the cd easy and convenient. The following example will be used though out this section to make the explanation easier.

The rules are as follows:

  1. The numbers 1-9 will select a menu choice, in addition these numbers may be used to jump from one video to the next when playing a video. For example selecting ``2'' when playing video 1.1 will jump to video 1.2. Selecting ``2'' when playing video 1.2 will jump to video 1.1. That is when playing a video selecting a number will jump to the menu choice in the most recent menu. For video's 1.1 and 1.2 this will be menu 1 and for video's 3.1 and 3.2 this will be menu 3.
  2. Selecting ``next'' from a page will go to the next page in that group if there is one, otherwise it will go to the first selection in that group. For example selecting next from page 1.2 will go to video 1.1, not video 1.3 which is the first selection for that page. selecting next from a video will go to the next menu item in that group, if there is one, otherwise it will go to the next menu item in the previous group. For example selecting next in video 1.4 will go to video 2.
  3. Selecting ``prev'' will in do the reverse of ``next'' unless at the root menu in which case ``prev'' will do nothing.
  4. The ``return'' key will generally go one level up. For example hitting the return key while video 3.2 in playing will go to page 3.1. Selecting return when at page 3.1 will go to the root page. If there are multiple pages for a group than than it will go to the previous page. For example hitting the return key while at page 1.2 will go to page 1.1. Selecting return when at the root page will do nothing.
  5. When a menu times out or a video is finished playing the next item will be played as if ``next'' was selected.
  6. The ``default'' key (often the play button) serves the same function as the ``next'' key.


7. nice-mpeg-file-names

In order to use this option VCDImager must be patched to support creating the special mpeg files. When this option is set to true then special mpeg files will be created on the CD, in the MPEG/ directory, which can be played directly on Windows and the Mac (I believe). Unfortunately these special files will not work on Linux. These files are like the *.DAT files found in the MPEGAV/ sequence but end in ``.MPG'' instead of ``.DAT'' so that they can be played directory without having to associate the .DAT files to a media player.

An HTML index file is also created in the MPEG/ directory when this option is set.


8. create-mpeg-link-files

When set to true mpeg link files will be created on the CD in the MPEGLINK/ directory. These files end in ``.MPL'' and contain exactly 2 lines. The first line is the MPEG track number, and the second line is the offset in seconds. Unlike the special MPEG files above these files can be used to play the video cd on Linux provided the the .MPL links are set up to a player capable of playing VCD on Linux. The link files, unlike the special MPEG files, also allow entry points to be played. Like the special mpeg files, an HTML index is created in the MPEGLINK/ directory when this option is set.

9. Running VCDMeta

Running VCDMeta is extremely simple. Since VCDMeta will create a large number of files it is best to create a separate directory for each videocd you wish to create and copy the input XML file into it. Once a directory has been created simply change into the directory and type ``vcdmeta [xmlfile]''. The xmlfile can be left off if your input file is named ``videocd-meta.xml''. That's all there is to it. VCDMeta will then create the vcdimager input xml file as ``videocd.xml'' in the current directory, an index file ``0VCDINDX.TXT'', and various other files needed for the displaying of the menus on the videocd.

10. Changelog

Changes from 0.10 to 0.20 (Dec 27, 2002)

11. Copyright

Copyright (C) 2002 by Kevin Atkinson under the GNU General Public License (GPL) version 2.0. You should have received a copy of the GPL along with this program if you did not you can find it at the GNU web site http://www.gnu.org/ or more specifically http://www.gnu.org/licenses/gpl.html.

The included fonts, ``Helvetica-bold-r-*.pfb'', are Copyright by URW++ Design and Development GmbH, and are also under the GPL.

About this document ...

VCDMeta Version 0.20

This document was generated using the LaTeX2HTML translator Version 2002 (1.62)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir11136iXF9V/lyx_tmpbuf0/manual.tex

The translation was initiated by Kevin Atkinson on 2002-12-27


next_inactive up previous
Kevin Atkinson 2002-12-27