Specification Documents for Lib-Ray

Summary - Design Concept

Lib-Ray is essentially a "multimedia website on a disk".

Several elements are defined:

Recommended File Structure

This includes three files at the top level, and three directories beneath:

  1. File "index.html" implements the "Main Disk Menu" using HTML5
  2. File "meta.cnf" provides catalog metadata for the disk to be used in retrieval systems
  3. File "cover.jpg" (or "cover.png") provides a front cover image for use in retrieval systems
  4. Folder "Menu" contains the basic on-disk menu system (it is constrained to not have external links requiring use of the internet)
  5. Folder "Media" contains the multimedia container files on the disk. It is recommended that the main feature be called "Media/feature.ogv" but other names (such as Media/episode01.ogv) might be used if the author prefers
  6. Folder "Extra" is reserved for free-form content (not just HTML and HTML there is unconstrained). Players may optionally block all access to the Extra folder and still be considered Lib-Ray compliant -- it's primary use is for viewing on a general-purpose computer
HTML5 Menu System

At minimum, the menu system must contain the "index.html" file. It must provide a "Play" button. The play button anchor is identified by the use of the attribute "accesskey='p'". This indicates that the key-combination "Alt+P" will start playback.

At least one feature page must be included, "feature.html, although again, multiple features can be distinguished by name (as in "episode01.html). Each feature page must include an "invisible link" with the attribute "accesskey='q'" -- this provides the "Stop" functionality and will return to the menu. The exact form of feature.html is provided by a template available from the downloads page.

Other recommended pages are: "Menu/audio.html" -- with a selection of available audio tracks, "Menu/subtitle.html" -- with available subtitle tracks OR you can use a single Menu/language.html menu to combine both.

All menu pages must include the "libray.js" Javascript library by reference (it should be stored in the "Menu" folder along with other menu content).

One or more scenes menus are recommend, though not required. Names like "scenes01.html" with an index for each page of scenes are recommended.

Multimedia Feature File

This is the main change in the 3rd prototype design, as I am moving to Matroska/VP8/FLAC.

A Lib-Ray disk must have at least one featured multimedia (video) file in Matroska (MKV) container format. For single-feature disks, the recommended name is "Media/feature.mkv". This should include the following tracks:

  1. VP8 codec video. There will also be a quality standard, but I have not formalized it yet.
  2. FLAC audio of principal soundtrack
  3. Additional Vorbis or FLAC audio tracks (e.g. for different languages or for commentary tracks)
  4. SRT or Kate formatted subtitle tracks (still investigating this)

I am no longer treating Chromium as the preferred player and I'm eliminating design concessions designed to accomodate it. Instead, the project will include the development of a Lib-Ray player.

Articles for "0.3" Prototype

I have been documenting my progress on the 0.3 prototype in my column at Free Software Magazine:

Download (OLD) Developers' Guide

The details of the specification are provided as a "Developer's Guide" (OUT OF DATE! This documentst the previous "0.2" prototype).

Click on the link to download the PDF Version 0.2 Developer's Guide.

Don't have a PDF reader? You can get one:

PDF Readers