Readium Logo

Digital Visual Narratives Profile

Editors:

Participate:

Example

{
  "@context": "http://readium.org/webpub-manifest/context.jsonld",
  
  "metadata": {
    "identifier": "urn:isbn:9782203001152",
    "title": "Objectif Lune",
    "author": "Hergé",
    "language": "fr",
    "publisher": "Casterman",
    "published": "1953-12-30",
    "modified": "2018-12-10T18:21:18Z",
    "numberOfPages": 62,
    "readingProgression": "ltr",
    "belongsTo": {
      "series": {
        "name": "Les Aventures de Tintin",
        "position": 16
      }
    }
  },

  "links": [
    {"rel": "self", "href": "http://example.org/manifest.json", "type": "application/divina+json"}
  ],

  "readingOrder": [
    {
      "rel": "cover",
      "href": "http://example.org/cover.jpg", 
      "type": "image/jpeg",
      "properties": { "page": "center" }
    }, 
    {
      "href": "http://example.org/page1.jpg", 
      "type": "image/jpeg",
      "properties": { "page": "left" }
    }, 
    {
      "href": "http://example.org/page2.jpg", 
      "type": "image/jpeg",
      "properties": { "page": "right" }
    }
  ]
}

1. Introduction

The goal of this document is to provide a profile dedicated to visual narratives for the Readium Web Publication Manifest.

This profile relies on:

While the Digital Visual Narrative Manifest is technically a profile of the Readium Web Publication Manifest, it has its own media type in order to maximize compatibilty with dedicated apps: application/divina+json.

See DiViNa guidelines for more details on how User Agents should implement this specification.

2. Listing Resources

A visual narrative is divided into one or more images, which are all listed in the readingOrder of the manifest.

In addition to the normal requirements of a readingOrder, all Link Objects have the following additional requirements:

In addition, all Link Objects should include width and height to indicate the dimensions of each resource.

3. Alternate Resources

In order to provide multiple variants of the same resource, Link Objects in the readingOrder may rely on the alternate key.

All Link Objects present in the alternate array:

Example 1: A resource available in JPEG and WebP

{
  "href": "http://example.org/page1.jpeg", 
  "type": "image/jpeg", 
  "alternate": [
    {
      "href": "http://example.org/page1.webp", 
      "type": "image/webp"
    }
  ]
}

Example 2: A resource available in French and Japanese

{
  "href": "http://example.org/page1.jpeg", 
  "type": "image/jpeg",
  "language": "fr"
  "alternate": [
    {
      "href": "http://example.org/page1-jp.jpeg", 
      "type": "image/jpeg",
      "language": "jp"
    }
  ]
}

Example 3: A resource available in two different resolutions

{
  "href": "http://example.org/page1.jpeg", 
  "type": "image/jpeg",
  "width": 546,
  "height": 760,
  "alternate": [
    {
      "href": "http://example.org/page1-high.jpeg", 
      "type": "image/jpeg",
      "width": 1092,
      "height": 1520
    }
  ]
}

4. Guided Navigation

In addition to having a table of contents, a visual narrative may also provide guided navigation where each reference is either:

This document introduces a new collection role to fulfill that goal:

Role Definition Compact Collection? Required?
guided Identifies a collection containing guided navigation into a publication. Yes No

To avoid duplicating content between readingOrder and guided, Link Objects referenced in guided must only contain href and title.

This current draft does not cover guided navigation over alternate versions of each image resource.

Example 4: Guided navigation with full page displayed before panels

"guided": [
  {
    "href": "http://example.org/page1.jpeg",
    "title": "Page 1"
  },
  {
    "href": "http://example.org/page1.jpeg#xywh=0,0,300,200",
    "title": "Panel 1"
  },
  {
    "href": "http://example.org/page1.jpeg#xywh=300,200,310,200",
    "title": "Panel 2"
  }
]

5. Transitions

In the reading order of a visual narrative, Link Objects may contain the following additional properties:

Key Semantics Type Values
transitionForward Describes the transition to be applied when moving FROM the previous resource TO current resource in reading order Transition Object See Transition Object
transitionBackward Describes the transition to be applied when moving FROM the current resource TO the previous resource in reading order Transition Object See Transition Object

transitionForward, transitionBackward

Keep in mind that a forward transition is placed on the TARGET resource of the transition.

The Transition Object

This specification defines the following keys for this JSON object:

Key Definition Format Required?
type Type of transition cut, dissolve, slide-in, slide-out, push, animation Yes
direction Direction of a slide-in, slide-out or push transition ltr, rtl, ttb, btt Yes if the type is slide-in, slide-out or push.
sequence Sequence of images which create an animation Array of URIs No
file Video file which creates an animation URI No
duration The duration of the transition in milliseconds Integer No

type

Value Definition
cut the new resource immediately replaces the current one; this transition does not need a duration and is only useful when continuous=true, as a way to specify an explicit cut (“page change”) between two resources.
dissolve the new resource appears above the current one, with opacity increasing from 0 to 1.
slide-in the new resource appears above the current one, and moves into the viewport to cover it.
slide-out the next resource is placed below the current one, which moves out of the viewport.
push the next resource moves into the viewport while the current one moves out of it, revealing the next one below.
animation the next resource appears after playing a sequence of images or a video.

If the transition type is animation, either a file or a sequence property must be specified.

direction

Value Definition
ltr the new image comes from the left (whether the transition is forward or backward).
rtl the new image comes from the right.
ttb the new image comes from the top .
ltr the new image comes from the bottom.

Note: Usually, if the reading progression is ltr, forward transitions will be rtl. Also, the reverse of an rtl slide-in is an ltr slide-out.

sequence

Only used when the type is animation, the value of the sequence property is an array of Link Objects pointing to bitmap images displayed before the next resource appears.

Each image in the array is a frame displayed for a slice of duration divided by the number of images of the sequence.

file

Only used when the type is animation, the value of the file property is a Link Object pointing to a video to be played before the next resource appears.

duration

Duration (in ms) can apply to any type of transition.

6. Packaging

In order to facilitate distribution, both manifest and images can also be distributed using a package based on the requirements expressed for the Readium Web Publication Manifest.

To maximize compatibility with dedicated apps, the package for this profile has its own file extension and media-type:

As an alternative, the manifest can also be added to an EPUB (as defined in the core specification) or a CBZ file at the same well-known location (manifest.json at the root of the package).

Appendix A. Compliance Levels

Level 0

Level 1

Level 2

Appendix B. Examples

Example 5: A manga is a DiViNa where images are presented sequentially from right-to-left with a discontinuity between images that are not in the same spread

{
  "metadata": {
    "title": "Manga",
    "identifier": "https://example.com/manga",
    "readingProgression": "rtl",
    "presentation": {
      "fit": "contain",
      "spread": "landscape"
    }
  },
  "readingOrder": [
    {
      "rel": "cover",
      "href": "cover.jpg", 
      "type": "image/jpeg",
      "properties": { "page": "center" }
    }, 
    {
      "href": "page1.jpg", 
      "type": "image/jpeg",
      "properties": { "page": "right" }
    }, 
    {
      "href": "page2.jpg", 
      "type": "image/jpeg",
      "properties": { "page": "left" }
    }
  ]
}

Example 6: A webtoon is a DiViNa where images are scrolled in a single continuous strip of content

{
  "metadata": {
    "title": "Webtoon",
    "identifier": "https://example.com/webtoon",
    "readingProgression": "ttb",
    "presentation": {
      "overflow": "scrolled",
      "fit": "width",
      "continuous": true
    }
  },
  "readingOrder": [
    {
      "href": "image1.jpg",
      "type": "image/jpeg"
    },
    {
      "href": "image2.jpg",
      "type": "image/jpeg"
    },
    {
      "href": "image3.jpg",
      "type": "image/jpeg"
    }
  ]
}

Example 7: This example features transitions. A slide-in btt from image1 to image2 with a backward slide-out ttb from image2 to image1; an image sequence from image2 to image3 with no backward transition; a video from image 3 to image 4 with no backward transition.

{
  "metadata": {
    "readingProgression": "ttb",
    "presentation": {
      "overflow": "scrolled",
      "continuous": true,
      "fit": "width"
    }
  },
  "readingOrder": [
    {
      "href": "./content/image1.png",
      "type": "image/png"
    },
    {
      "href": "./content/image2.png",
      "type": "image/png",
      "properties": {
        "transitionForward": {
          "type": "slide-in",
          "direction": "btt"
        },
        "transitionBackward": {
          "type": "slide-out",
          "direction": "ttb"
        }
      }
  	},
   {
     "href": "./content/image3.png",
     "type": "image/png",
     "properties": {
       "transitionForward": {
         "type": "animation",
         "sequence": [
           {
             "href": "./content/tr3-1.png",
             "type": "image/png"
            },
            {
              "href": "./content/tr3-2.png",
              "type": "image/png"
            },
            {
              "href": "./content/tr3-3.png",
              "type": "image/png"
            },
            {
              "href": "./content/tr3-4.png",
              "type": "image/png"
            },
            {
              "href": "./content/tr3-5.png",
              "type": "image/png"
            }
          ],
          "duration": 500
        }
      }
    },
    {
      "href": "./content/image4.png",
      "type": "image/png",
      "properties": {
        "transitionForward": {
          "type": "animation",
          "file": {
            "href": "./content/tr4.mp4",
            "type": "video/mp4"
          },
          "duration": 1000
        }
      }
    }
  ]
}