Skip to content

Latest commit

 

History

History
107 lines (71 loc) · 5.95 KB

packaging.md

File metadata and controls

107 lines (71 loc) · 5.95 KB
Raw

Readium Packaging Format (RPF)

This specification defines a file format for packaging into a single-file container the set of related resources and associated metadata that comprise a Readium Web Publication.

Editors:

  • Hadrien Gardeur
  • Laurent Le Meur (EDRLab)

Participate:

1. Introduction

A Readium Web Publication is often distributed unpackaged on the Web, but it also may be packaged for easy distribution as a single file.

A Readium Web Publication Manifest may also be included in an EPUB 3 publication and therefore directly reference media resources present in the package. This method paves the way to hybrid publications, which can e.g. be both valid EPUB 3 and Divina publications. When played in Divina compliant software, users will benefit from advanced features like transitions, guided navigation, layers, sound effects etc. which are not available in the EPUB 3 format.

2. Terminology

Codec content types
Content types that have intrinsic binary format qualities, such as video and audio media types which are already designed for optimum compression, or which provide optimized streaming capabilities.
Non-Codec content types
Content types that benefit from compression due to the nature of their internal data structure, such as file formats based on character strings (for example, HTML, CSS, etc.).
Package
Single-file container for the set of constituent resources and associated metadata that comprise a digital publication.
Root Directory
Base directory of the Package file system.

3. Packaging format

For packaging the set of constituent resources and associated metadata that comprise a digital publication, this specification uses the ZIP format as specified in ISO/IEC 21320-1:2015 and zip.

In the absence of values defined at the level of a Readium Web Publication profile:

  • The media type must be application/webpub+zip
  • The file extension must be .webpub

A publication where any resource is encrypted using a DRM must use a different media type and file extension.

4. Compression of resources

When stored in a Package, resources with Non-Codec content types should be compressed and the Deflate compression algorithm MUST be used. This practice ensures that file entries stored in the Package have a smaller size.

Resources with Codec content types should be stored without compression. In such case, compression would introduce unnecessary processing overhead at production time (especially with large resource files) and would impact audio/video playback performance at consumption time.

5. File Structure

A Package must include in its Root Directory a file named manifest.json, which must be in the format defined for Readium Web Publication Manifests.

The contents of manifest.json must not be encrypted.

A Package must also include all resources within the bounds of the digital publication, i.e. the finite set of resources obtained from the union of resources listed in the reading order and resources Link Arrays of the Readium Web Publication Manifest.

These resource files may be in any location descendant from the Root Directory, or in the Root Directory itself.

Resource files must be referenced in the manifest via path relative scheme-less url strings. The path must be relative to the Root Directory of the Package.

Example 1: Reference to a Resource file in a Manifest file. Such reference does not start with a drive letter (such as "C:") or a slash, and it is URL encoded. In this example, the file is named "armanddurand chapter01.mp3" in the Package.

{
  "readingOrder": [
    {
      "duration": 1176,
      "type": "audio/mpeg",
      "title": "01 - Chapter I",
      "bitrate": 64,
      "href": "audio/armanddurand%20chapter01.mp3"
    }
  ]
}

6. Hybrid EPUB 3 + RPF Packages

As an alternative to the creation of a pure RPF package, the manifest may also be included into an EPUB 3 publication and directly reference the media resources present in the package.

An RPF compliant application will therefore be able to process the file as an RPF package, while an EPUB 3 compliant application will process it as a standard EPUB 3 publication.

If a Readium Web Publication Manifest is included in an EPUB 3 file, the following restriction apply:

  • The EPUB 3 package document must include a link to the Readium Web Publication Manifest, where the link relation is set to alternate
  • The EPUB 3 package document must include in its manifest structure a reference to the Readium Web Publication Manifest.
    • The EPUB 3 package document must include in its manifest structure a reference to any resource (e.g. sound) used in the Readium Web Publication Manifest.

Example 2: Reference to a Manifest file in an EPUB 3 OPF structure

<metadata>
      <link rel="alternate" 
            href="manifest.json" 
            media-type="application/webpub+json" />
</metadata>
...
<manifest>
    <item href="manifest.json" media-type="application/webpub+json" id="rwpm"/>
    ...
</manifest>