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:
- Hadrien Gardeur
Participate:
- Synchronizing text with pre-recorded audio, for example in order to support Media Overlays in EPUB, DAISY publications or to distribute accessible audiobooks using the Audiobook Profile of RWPM.
- Extracting a Guided Navigation Document from an HTML/XHTML resource for a read aloud feature or a reader mode.
- Panel by panel navigation in comics/manga to facilitate reading on smaller screens.
- Providing a textual transcript and/or image descriptions for highly illustrated publications such as Divina.
Guided Navigation Documents must be identified using the following media type: application/guided-navigation+json.
| 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"]
}
]
}Each Guided Navigation Object must either contain:
- a
childrenobject containg at least one Guided Navigation Object - or one or more of the following properties:
audioref,imgrefortextref
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 |
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.
If a publication references any Guided Navigation Document using audioref:
- it must include a
durationwith the total duration for all audio resources referenced - and it should include one or more
narrator
Publications that conform to the EPUB profile and map SMIL to Guided Navigations Documents, may also include a mediaOverlay property.
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.
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:
typeuses the dedicated value for Guided Navigation Documents:application/guided-navigation+json- and the
relvalue simply indicates that the Guided Navigation Document isrelatedto the publication
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"
}
]
}
]The following media fragments have been identified as potential candidates for fragments in
audioref,imgrefandtextref:Audio: https://www.w3.org/TR/media-frags/#naming-time
Images:
- Rectangular regions: https://www.w3.org/TR/media-frags/#naming-space
- Polygonal regions: https://idpf.org/epub/renditions/region-nav/#sec-3.5.1
Text:
- Fragment ID:
#identifier- Text fragments: https://wicg.github.io/scroll-to-text-fragment/
There are a number of open issues that relate to media fragments:
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).
The following JSON Schemas are available under version control:
- Guided Navigation Document: https://github.com/readium/guided-navigation/blob/master/schema/document.schema.json
- Guided Navigation Object: https://github.com/readium/guided-navigation/blob/master/schema/object.schema.json
For the purpose of validating a Readium Guided Navigation Document, use the following JSON Schema resource:
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."
}
]
}| 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>"
}
}| 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."
}
]
}This is under discussion at:
- How should we handle references to multiple images? #9
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"
]
}
]
}| 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"]
}