VCDMeta Version 0.20
Kevin Atkinson
kevina@gnu.org
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.
- Perl
- XML::Twig Perl module
For verifying the input XML file:
- xmllint (Part of Libxml, http://xmlsoft.org/, should already
be installed as it is also required for the XML front end of vcdimager)
For creating and converting images:
- Image::Magick Perl module (http://www.imagemagick.org/)
For converting images into mpeg stills:
- netpbm (http://netpbm.sourceforge.net/)
- mjpegtools (http://mjpeg.sourceforge.net/)
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/).
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.
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/.
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.
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)
- filesystem
- options
- page (required)
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>
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.
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.
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.
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.
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)
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.
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.
- Root
- Root Page
- Group 1
- Page 1.1
- Video 1.1
- Video 1.2
- Page 1.2
- Video 1.3
- Video 1.4
- Video 2
- Group 3
- Page 3.1
- Video 3.1
- Video 3.2
The rules are as follows:
- 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.
- 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.
- Selecting ``prev'' will in do the reverse of ``next'' unless
at the root menu in which case ``prev'' will do nothing.
- 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.
- When a menu times out or a video is finished playing the next item
will be played as if ``next'' was selected.
- 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.
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.
- Changed DTD. The new DTD in not compatible with the old one form VCDMeta
0.10.
- Added support for multiple pages in a group.
- Added support for nice mpeg file names and mpeg links.
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.
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
Kevin Atkinson
2002-12-27