Readium Logo

Readium Guided Navigation

Guided navigation offers an alternative reading experience through a sequence of media fragments. In some cases, multiple media fragments are meant to be presented in parallel.

This document defines a syntax for Guided Navigation Documents, serialized in JSON and meant to be referenced in a Readium Web Publication Manifest.

Editors:

Participate:

Use cases

1. Guided Navigation Documents

Guided Navigation Documents must be identified using the following media type: application/guided-navigation+json.

1.1. Top-level properties

Name Description Format Required?
links References to other resources that are related to the current Guided Navigation Document. An array of Link Objects No
guided A sequence of resources and/or media fragments into these resources, meant to be presented sequentially to the user. An array of Guided Navigation Objects Yes

Example 1: A link to a subsequent Guided Navigation Document

{
  "links": [
    {
      "rel": "next",
      "href": "guided-chapter2.json"
    }
  ],
  "guided": [
    {
      "textref": "chapter1.html",
      "role": ["chapter"]
    }
  ]
}

1.2. Guided Navigation Object

Each Guided Navigation Object must either contain:

Guided Navigations Objects should include one or more values for role.

Name Description Format
audioref References an audio resource or a fragment of it. URI
children Items that are children of the containing Guided Navigation Object. Guided Navigation Objects
imgref References an image or a fragment of it. URI
role Convey the structural semantics of a publication Array of roles
text Textual equivalent of the resources or fragment of the resources referenced by the current Guided Navigation Object. String
textref References a textual resource or a fragment of it. URI

2. Relationship to the Readium Web Publication Manifest

Guided Navigation Documents are primarily designed to be referenced from a Readium Web Publication Manifest, in order to enable use cases that such manifests cannot handle on their own.

For example, a publication using the EPUB profile could handle Media Overlays by parsing SMIL files contained in the EPUB package and exposing them as Guided Navigation Documents.

2.1. Metadata requirements

If a publication references any Guided Navigation Document using audioref:

Publications that conform to the EPUB profile and map SMIL to Guided Navigations Documents, may also include a mediaOverlay property.

2.2. Discovering a Guided Navigation Document

Users must be free to move in and out of a Guided Navigation experience at will.

To do so, publications should provide references to Guided Navigation Documents both at a publication-level and as an alternate to resources referenced in the readingOrder.

2.2.1 Publication-level

All valid Readium Web Publication Manifests must contain a links property with at least one reference to its canonical location.

In order to indicate the presence of a Guided Navigation Document, links may also include an additional Link Object where:

Subsequent Guided Navigation Documents can be linked from this initial resource using the links property, in order to navigate throughout the publication.

Example 2: A publication links to a Guided Navigation Document

"links": [
  {
    "rel": "self",
    "href": "https://example.com/manifest.json",
    "type": "application/guided-navigation+json"
  }
  {
    "rel": "related",
    "href": "https://example.com/guided.json",
    "type": "application/guided-navigation+json"
  }
]

In addition to a publication-level link, all resources in the readingOrder should also point to the Guided Navigation Document that references them using the alternate property.

If this Guided Navigation Document contains any audioref element, then the Link Object should also indicate the total duration for all audioref properties using duration.

Example 3: An image in a Divina that links to a Guided Navigation Document as an alternative

"readingOrder": [
  {
    "href": "page1.jpg",
    "type": "image/jpeg",
    "alternate": [
      {
        "href": "guided.json",
        "type": "application/guided-navigation+json"
      }
    ]
  }
]

3. Fragments

The following media fragments have been identified as potential candidates for fragments in audioref, imgref and textref:

Audio: https://www.w3.org/TR/media-frags/#naming-time

Images:

Text:

There are a number of open issues that relate to media fragments:

4. Roles

There are a number of open issues that relate to roles:

Roles are inherited from multiple specifications such as HTML, ARIA, DPUB ARIA and EPUB 3 Semantics Vocabulary, in order to convey the structural semantics of a publication.

The full list of supported roles is available at: https://readium.org/guided-navigation/roles

Roles should be used by reading applications to implement skippability (based on user preferences, some items could be skipped) and escapability (allowing users to escape from the current context, for example escaping from the content of a table to go back to the main text).

Appendix A - JSON Schema

The following JSON Schemas are available under version control:

For the purpose of validating a Readium Guided Navigation Document, use the following JSON Schema resource:

Appendix B - Examples

A few additional documents are available in order to illustrate how Guided Navigation can be leveraged for:

The following examples are also available to illustrate how other types of publication can be mapped to Guided Navigation:

Example 4: Synchronizing text with pre-recorded audio

{
  "guided": [
    {
      "textref": "chapter1.html#start",
      "role": ["chapter"],
      "children": [
        {
          "textref": "chapter1.html#par1", 
          "audioref": "chapter1.mp3#t=0,20"
        },
        {
          "textref": "chapter1.html#par2", 
          "audioref": "chapter1.mp3#t=20,28"
        }
      ]
    }
  ]
}

Example 5: Accessible audiobook using text fragments

{
  "guided": [
    {
      "audioref": "chapter1.mp3#t=0,20",
      "textref": "chapter1.html#:~:text=It%20is%20a%20truth,want%20of%20a%20wife"
    },
    { 
      "audioref": "chapter1.mp3#t=20,48",
      "textref": "chapter1.html#:~:text=However%20little%20known,of%20their%20daughters"
    }
  ]
}

Example 6: Accessible audiobook using embedded text

{
  "guided": [
    {
      "audioref": "chapter1.mp3#t=0,7",
      "text": "This is the first sentence in this audiobook."
    },
    { 
      "audioref": "chapter1.mp3#t=7,16",
      "text": "Which is followed by a second, slightly longer sentence."
    }
  ]
}

Appendix C - Potential additions

Potential object representation for text

Name Description Format
language Main language for the text, which can be locally overriden in the SSML representation. BCP-47 language tag
plain Contains a plain text representation of the text. String
ssml Contains an SSML representation of the text. SSML

Example 9: Text representation with both plain text and SSML

{
    "imgref": "page10.jpg#xywh=percent:10,10,20,20",
    "text": {
      "plain": "The SSML standard is defined by the W3C.",
      "language": "en",
      "ssml": "<speak>The <say-as interpret-as=\"characters\">SSML</say-as>standard <break time=\"1s\"/>is defined by the<sub alias=\"World Wide Web Consortium\">W3C</sub>.</speak>"
    }
}

Potential format for description

Name Description Format
description Text, audio or image description for the current Guided Navigation Object. Guided Navigation Object without children

Example 10: Audio and text description for an image

{
  "role": ["panel"],
  "imgref": "page10.jpg#xywh=percent:10,10,60,40",
  "description": {
    "text": "A cowboy is looking at the city as the sun sets into the horizon.",
    "audioref": "description.mp3t=0,5"
  },
  "children": [
    {
      "role": ["speechBubble"],
      "imgref": "page10.jpg#xywh=percent:10,10,20,20",
      "text": "This is a dialogue in a speech bubble."
    }
  ]
}

Potential format for multipleImages

This is under discussion at:

References:

Name Description Format
multipleImages Two or more references to images or regions of different images. Array of URI

Example 11: Two page spread that contains a panel across the entire spread

{
  "role": ["spread"],
  "multipleImages": [
    "page2.jpg", 
    "page3.jpg"
  ]
  "children": [
    {
      "role": ["panel"]
      "multipleImages": [
        "page2.jpg#xywh=percent:0,0,100,20",
        "page3.jpg#xywh=percent:0,0,100,20"
      ]
    }
  ]
}

Potential format for character

Name Description Format
character Identifies one or more character present in a given Guided Navigation object. Array of strings

Example 12: Characters present in the panel of a comicbook

{
  "role": ["panel"],
  "imgref": "page10.jpg#xywh=percent:10,10,60,40",
  "description": "Emily marche seule, elle semble perdue dans ses pensées. Derrière elle, deux policiers la suivent du regard et échangent à son propos.",
  "character": ["Emily", "Premier policier", "Deuxième policier"]
}
This site is open source. Improve this page.