VCDMeta Version 0.20
Kevin Atkinson
kevina@gnu.org
Contents
* 1. Introduction
* 2. Requirements
* 3. Installation
* 4. Status
* 5. XML Syntax
+ 5.1 videocd-meta
+ 5.2 filesystem
+ 5.3 options
+ 5.4 page
+ 5.5 video
o 5.5.1 entry
+ 5.6 group
+ 5.7 Examples
* 6. Layout of the Videocd
* 7. nice-mpeg-file-names
* 8. create-mpeg-link-files
* 9. Running VCDMeta
* 10. Changelog
+ Changes from 0.10 to 0.20 (Dec 27, 2002)
* 11. Copyright
* About this document ...
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
* 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/).
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:
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)
* filesystem
* options
* page (required)
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:
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:
A more complex VCD:
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.
* Root
+ Root Page
o Group 1
# Page 1.1
1. Video 1.1
2. Video 1.2
# Page 1.2
1. Video 1.3
2. Video 1.4
o Video 2
o Group 3
# Page 3.1
1. Video 3.1
2. Video 3.2
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)
* 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.
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.