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.