BACK

Specification

A formal specification for Lib-Ray is not yet written. That's one of the goals of the present project. We do have a general design concept which is explained below.

Summary - Design Concept

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

Several elements are defined:

Hardware Medium

Although Lib-Ray should be recognizable on any mountable medium, the preferred hardware storage for 0.3-0.4 is the MMC or SDHC flash memory card.

Although the SDHC card is entirely compatible with the MMC standard, is more widely available, and can be used to carry Lib-Ray, it is explicitly a violation of the Lib-Ray standard to employ any of its non-MMC features such as DRM encryption. Lib-Ray players are not required to implement support for these elements (they should follow the freely available MMC standard), and may therefore refuse to play cards that violate this rule.

File System

The file-system on the Lib-Ray device will be Universal Disk Format (UDF). This is the same file system as used on DVD disks. For writable media like the recommended MMC/SD card, this will be the Plain build variant of UDF.

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.mkv" but other names (such as Media/episode01.mkv) 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.

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.

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

Javascript or not?

In versions 0.1-0.3, some form of Javascript was assumed to be used to set features on the video playback system from the menu system. This idea has a number of problems, including security against malicious code on release video cards, non-free software proliferation, and additional complexity (since the needed DOM features do not yet exist in most browsers).

In version 0.4, we're going to forego Javascript entirely and use special CGI URLs to communicate the necessary changes -- in other words, it will effectively be done with "server side" scripting. This should make the design simpler and address the concerns about security directly (note that just because we are avoiding dependency on Javascript does not necessarily mean that Lib-Ray disks can't use Javascript for enhancement. It only means that they must fall back to non-scripted behavior in a usable way.

Multimedia Feature File

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

  1. VP8-codec video, encoded at up to 20 megabits per second
  2. FLAC audio of principal stereo (or 5.1) soundtrack
  3. Additional Vorbis or FLAC audio tracks (e.g. for different languages or for commentary tracks)
  4. Subtitle streams in Advanced Substation Alpha (ASSA) format

Developers' Guide (Offline)

As part of the Lib-Ray project, we are writing a new developer's guide which will define Lib-Ray in detail as well as explain how to create a Lib-Ray release. Since the design is in flux at the moment, though, we don't have one available yet (and the previous guide is severely out of date, so it should not be used as a guide).