
Presentation API
W3C Candidate Recommendation Draft 23 January 2023
Copyright © 2023 World Wide Web Consortium . W3C ® liability , trademark and permissive document license rules apply.
This specification defines an API to enable Web content to access presentation displays and use them for presenting Web content.
Status of This Document
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document was published by the Second Screen Working Group as a Candidate Recommendation Draft using the Recommendation track .
Since publication as Candidate Recommendation on 01 June 2017 , the Working Group updated the steps to construct a PresentationRequest to ignore a URL with an unsupported scheme, placed further restrictions on how receiving browsing contexts are allowed to navigate themselves, and dropped the definition of the BinaryType enum in favor of the one defined in the HTML specification. Other interfaces defined in this document did not change other than to adjust to WebIDL updates. Various clarifications and editorial updates were also made. See the list of changes for details.
No feature has been identified as being at risk .
The Second Screen Working Group will refine the test suite for the Presentation API during the Candidate Recommendation period and update the preliminary implementation report . For this specification to advance to Proposed Recommendation, two independent, interoperable implementations of each feature must be demonstrated, as detailed in the Candidate Recommendation exit criteria section.
Publication as a Candidate Recommendation does not imply endorsement by W3C and its Members. A Candidate Recommendation Draft integrates changes from the previous Candidate Recommendation that the Working Group intends to include in a subsequent Candidate Recommendation Snapshot.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
This document is governed by the 2 November 2021 W3C Process Document .
1. Introduction
This section is non-normative.
The Presentation API aims to make presentation displays such as projectors, attached monitors, and network-connected TVs available to the Web. It takes into account displays that are attached using wired (HDMI, DVI, or similar) and wireless technologies (Miracast, Chromecast, DLNA, AirPlay, or similar).
Devices with limited screen size lack the ability to show Web content to a larger audience: a group of colleagues in a conference room, or friends and family at home, for example. Web content shown on a larger presentation display has greater perceived quality, legibility, and impact.
At its core, the Presentation API enables a controller page to show a presentation page on a presentation display and exchange messages with it. How the presentation page is transmitted to the display and how messages are exchanged between it and the controller page are left to the implementation; this allows the use of a wide variety of display technologies.
For example, if the presentation display is connected by HDMI or Miracast, which only allow audio and video to be transmitted, the user agent (UA) hosting the controller will also render the presentation . It then uses the operating system to send the resulting graphical and audio output to the presentation display. We refer to this situation as the 1-UA mode implementation of the Presentation API. The only requirements are that the user agent is able to send graphics and audio from rendering the presentation to the presentation display, and exchange messages internally between the controller and presentation pages.
If the presentation display is able to render HTML natively and communicate with the controller via a network, the user agent hosting the controller does not need to render the presentation . Instead, the user agent acts as a proxy that requests the presentation display to load and render the presentation page itself. Message exchange is done over a network connection between the user agent and the presentation display. We refer to this situation as the 2-UA mode implementation of the Presentation API.
The Presentation API is intended to be used with user agents that attach to presentation displays in 1-UA mode , 2-UA mode , and possibly other means not listed above. To improve interoperability between user agents and presentation displays, standardization of network communication between browsers and displays is being considered in the Second Screen Community Group .
2. Use cases and requirements
Use cases and requirements are captured in a separate Presentation API Use Cases and Requirements document.
3. Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY , MUST , MUST NOT , OPTIONAL , SHOULD , and SHOULD NOT in this document are to be interpreted as described in BCP 14 [ RFC2119 ] [ RFC8174 ] when, and only when, they appear in all capitals, as shown here.
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the key word (" MUST ", " SHOULD ", " MAY ", etc.) used in introducing the algorithm.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
3.1 Conformance classes
This specification describes the conformance criteria for two classes of user agents .
Web browsers that conform to the specifications of a controlling user agent must be able to start and control presentations by providing a controlling browsing context as described in this specification. This context implements the Presentation , PresentationAvailability , PresentationConnection , PresentationConnectionAvailableEvent , PresentationConnectionCloseEvent , and PresentationRequest interfaces.
Web browsers that conform to the specifications of a receiving user agent must be able to render presentations by providing a receiving browsing context as described in this specification. This context implements the Presentation , PresentationConnection , PresentationConnectionAvailableEvent , PresentationConnectionCloseEvent , PresentationConnectionList , and PresentationReceiver interfaces.
One user agent may act both as a controlling user agent and as a receiving user agent , if it provides both browsing contexts and implements all of their required interfaces. This can happen when the same user agent is able to host the controlling browsing context and the receiving browsing context for a presentation, as in the 1-UA mode implementation of the API.
Conformance requirements phrased against a user agent apply either to a controlling user agent , a receiving user agent or to both classes, depending on the context.
4. Terminology
The term JavaScript realm is used as defined in ECMAScript [ ECMASCRIPT ].
The term current realm is used as defined in ECMAScript [ ECMASCRIPT ].
The terms resolved and rejected in the context of Promise objects are used as defined in [ ECMASCRIPT ].
The header Accept-Language is used as defined in HTTP/1.1 [ rfc7231 ].
HTTP authentication is used as defined in HTTP/1.1: Authentication [ rfc7235 ].
The term cookie store is used as defined in RFC 6265 [ COOKIES ].
The term UUID is used as defined in RFC 4122 [ rfc4122 ].
The term DIAL is used as defined in DIAL [ DIAL ].
The term reload a document refers to steps run when the reload () method gets called in [ HTML ].
The term local storage area refers to the storage areas exposed by the localStorage attribute, and the term session storage area refers to the storage areas exposed by the sessionStorage attribute in [ HTML ].
This specification references terms exported by other specifications, see B.2 Terms defined by reference . It also references the following internal concepts from other specifications:
- parse a url , defined in HTML [ HTML ]
- creating a new browsing context , defined in HTML [ HTML ]
- session history , defined in HTML [ HTML ]
- allowed to navigate , defined in HTML [ HTML ]
- navigating to a fragment identifier , defined in HTML [ HTML ]
- unload a document , defined in HTML [ HTML ]
- database , defined in Indexed Database API [ INDEXEDDB ]
5. Examples
This section shows example codes that highlight the usage of main features of the Presentation API. In these examples, controller.html implements the controller and presentation.html implements the presentation. Both pages are served from the domain https://example.org ( https://example.org/controller.html and https://example.org/presentation.html ). These examples assume that the controlling page is managing one presentation at a time. Please refer to the comments in the code examples for further details.
5.1 Monitoring availability of presentation displays
This code renders a button that is visible when there is at least one compatible presentation display that can present https://example.com/presentation.html or https://example.net/alternate.html .
Monitoring of display availability is done by first creating a PresentationRequest with the URLs you want to present, then calling getAvailability to obtain a PresentationAvailability object whose change event will fire when presentation availability changes state.
5.2 Starting a new presentation
When the user clicks presentBtn , this code requests presentation of one of the URLs in the PresentationRequest . When start is called, the browser typically shows a dialog that allows the user to select one of the compatible displays that are available. The first URL in the PresentationRequest that is compatible with the chosen display will be presented on that display.
The start method resolves with a PresentationConnection object that is used to track the state of the presentation, and exchange messages with the presentation page once it's loaded on the display.
5.3 Reconnecting to an existing presentation
The presentation continues to run even after the original page that started the presentation closes its PresentationConnection , navigates, or is closed. Another page can use the id on the PresentationConnection to reconnect to an existing presentation and resume control of it. This is only guaranteed to work from the same browser that started the presentation.
5.4 Starting a presentation by the controlling user agent
Some browsers have a way for users to start a presentation without interacting directly with the controlling page. Controlling pages can opt into this behavior by setting the defaultRequest property on navigator.presentation , and listening for a connectionavailable event that is fired when a presentation is started this way. The PresentationConnection passed with the event behaves the same as if the page had called start .
5.5 Monitoring the connection state and exchanging data
Once a presentation has started, the returned PresentationConnection is used to monitor its state and exchange messages with it. Typically the user will be given the choice to disconnect from or terminate the presentation from the controlling page.
Since the the controlling page may connect to and disconnect from multiple presentations during its lifetime, it's helpful to keep track of the current PresentationConnection and its state. Messages can only be sent and received on connections in a connected state.
5.6 Listening for incoming presentation connections
This code runs on the presented page ( https://example.org/presentation.html ). Presentations may be connected to from multiple controlling pages, so it's important that the presented page listen for incoming connections on the connectionList object.
5.7 Passing locale information with a message
5.8 creating a second presentation from the same controlling page.
It's possible for a controlling page to start and control two independent presentations on two different presentation displays. This code shows how a second presentation can be added to the first one in the examples above.
6.1 Common idioms
A presentation display refers to a graphical and/or audio output device available to the user agent via an implementation specific connection technology.
A presentation connection is an object relating a controlling browsing context to its receiving browsing context and enables two-way-messaging between them. Each presentation connection has a presentation connection state , a unique presentation identifier to distinguish it from other presentations , and a presentation URL that is a URL used to create or reconnect to the presentation . A valid presentation identifier consists of alphanumeric ASCII characters only and is at least 16 characters long.
Some presentation displays may only be able to display a subset of Web content because of functional, security or hardware limitations. Examples are set-top boxes, smart TVs, or networked speakers capable of rendering only audio. We say that such a display is an available presentation display for a presentation URL if the controlling user agent can reasonably guarantee that presentation of the URL on that display will succeed.
A controlling browsing context (or controller for short) is a browsing context that has connected to a presentation by calling start or reconnect , or received a presentation connection via a connectionavailable event. In algorithms for PresentationRequest , the controlling browsing context is the browsing context whose JavaScript realm was used to construct the PresentationRequest .
The receiving browsing context (or presentation for short) is the browsing context responsible for rendering to a presentation display . A receiving browsing context can reside in the same user agent as the controlling browsing context or a different one. A receiving browsing context is created by following the steps to create a receiving browsing context .
In a procedure, the destination browsing context is the receiving browsing context when the procedure is initiated at the controlling browsing context , or the controlling browsing context if it is initiated at the receiving browsing context .
The set of controlled presentations , initially empty, contains the presentation connections created by the controlling browsing contexts for the controlling user agent (or a specific user profile within that user agent). The set of controlled presentations is represented by a list of PresentationConnection objects that represent the underlying presentation connections . Several PresentationConnection objects may share the same presentation URL and presentation identifier in that set, but there can be only one PresentationConnection with a specific presentation URL and presentation identifier for a given controlling browsing context .
The set of presentation controllers , initially empty, contains the presentation connections created by a receiving browsing context for the receiving user agent . The set of presentation controllers is represented by a list of PresentationConnection objects that represent the underlying presentation connections . All presentation connections in this set share the same presentation URL and presentation identifier .
In a receiving browsing context , the presentation controllers monitor , initially set to null , exposes the current set of presentation controllers to the receiving application. The presentation controllers monitor is represented by a PresentationConnectionList .
In a receiving browsing context , the presentation controllers promise , which is initially set to null , provides the presentation controllers monitor once the initial presentation connection is established. The presentation controllers promise is represented by a Promise that resolves with the presentation controllers monitor .
In a controlling browsing context , the default presentation request , which is initially set to null , represents the request to use when the user wishes to initiate a presentation connection from the browser chrome.
The task source for the tasks mentioned in this specification is the presentation task source .
Unless otherwise specified, the JavaScript realm for script objects constructed by algorithm steps is the current realm .
6.2 Interface Presentation
The presentation attribute is used to retrieve an instance of the Presentation interface. It MUST return the Presentation instance.
6.2.1 Controlling user agent
Controlling user agents MUST implement the following partial interface:
The defaultRequest attribute MUST return the default presentation request if any, null otherwise. On setting, the default presentation request MUST be set to the new value.
The controlling user agent SHOULD initiate presentation using the default presentation request only when the user has expressed an intention to do so via a user gesture, for example by clicking a button in the browser chrome.
To initiate presentation using the default presentation request , the controlling user agent MUST follow the steps to start a presentation from a default presentation request .
Support for initiating a presentation using the default presentation request is OPTIONAL .
6.2.2 Receiving user agent
Receiving user agents MUST implement the following partial interface:
The receiver attribute MUST return the PresentationReceiver instance associated with the receiving browsing context and created by the receiving user agent when the receiving browsing context is created . In any other browsing context (including child navigables of the receiving browsing context ) it MUST return null .
Web developers can use navigator.presentation.receiver to detect when a document is loaded as a presentation.
6.3 Interface PresentationRequest
A PresentationRequest object is associated with a request to initiate or reconnect to a presentation made by a controlling browsing context . The PresentationRequest object MUST be implemented in a controlling browsing context provided by a controlling user agent .
When a PresentationRequest is constructed, the given urls MUST be used as the list of presentation request URLs which are each a possible presentation URL for the PresentationRequest instance.
6.3.1 Constructing a PresentationRequest
When the PresentationRequest constructor is called, the controlling user agent MUST run these steps:
- If the document object's active sandboxing flag set has the sandboxed presentation browsing context flag set, then throw a SecurityError and abort these steps.
- If urls is an empty sequence, then throw a NotSupportedError and abort all remaining steps.
- If a single url was provided, let urls be a one item array containing url .
- Let presentationUrls be an empty list of URLs.
- Let A be an absolute URL that is the result of parsing U relative to the API base URL specified by the current settings object .
- If the parse a URL algorithm failed, then throw a SyntaxError exception and abort all remaining steps.
- If A 's scheme is supported by the controlling user agent , add A to presentationUrls .
- If presentationUrls is an empty list, then throw a NotSupportedError and abort all remaining steps.
- If any member of presentationUrls is not a potentially trustworthy URL , then throw a SecurityError and abort these steps.
- Construct a new PresentationRequest object with presentationUrls as its presentation request URLs and return it.
6.3.2 Selecting a presentation display
When the start method is called, the user agent MUST run the following steps to select a presentation display .
- If the document's active window does not have transient activation , return a Promise rejected with an InvalidAccessError exception and abort these steps.
- Let topContext be the top-level browsing context of the controlling browsing context .
- If there is already an unsettled Promise from a previous call to start in topContext or any browsing context in the descendant navigables of topContext , return a new Promise rejected with an OperationError exception and abort all remaining steps.
- Let P be a new Promise .
- Return P , but continue running these steps in parallel .
- If the user agent is not monitoring the list of available presentation displays , run the steps to monitor the list of available presentation displays in parallel .
- Let presentationUrls be the presentation request URLs of presentationRequest .
- Request user permission for the use of a presentation display and selection of one presentation display.
- The list of available presentation displays is empty and will remain so before the request for user permission is completed.
- No member in the list of available presentation displays is an available presentation display for any member of presentationUrls .
- Reject P with a NotFoundError exception.
- Abort all remaining steps.
- If the user denies permission to use a display, reject P with an NotAllowedError exception, and abort all remaining steps.
- Otherwise, the user grants permission to use a display; let D be that display.
- Run the steps to start a presentation connection with presentationRequest , D , and P .
6.3.3 Starting a presentation from a default presentation request
When the user expresses an intent to start presentation of a document on a presentation display using the browser chrome (via a dedicated button, user gesture, or other signal), that user agent MUST run the following steps to start a presentation from a default presentation request . If no default presentation request is set on the document, these steps MUST not be run.
- If there is no presentation request URL for presentationRequest for which D is an available presentation display , then abort these steps.
- Run the steps to start a presentation connection with presentationRequest and D .
6.3.4 Starting a presentation connection
When the user agent is to start a presentation connection , it MUST run the following steps:
- Let I be a new valid presentation identifier unique among all presentation identifiers for known presentation connections in the set of controlled presentations . To avoid fingerprinting, implementations SHOULD set the presentation identifier to a UUID generated by following forms 4.4 or 4.5 of [ rfc4122 ].
- Create a new PresentationConnection S .
- Set the presentation identifier of S to I .
- Set the presentation URL for S to the first presentationUrl in presentationUrls for which there exists an entry (presentationUrl, D) in the list of available presentation displays .
- Set the presentation connection state of S to connecting .
- Add S to the set of controlled presentations .
- If P is provided, resolve P with S .
- Queue a task to fire an event named connectionavailable , that uses the PresentationConnectionAvailableEvent interface, with the connection attribute initialized to S , at presentationRequest . The event must not bubble and must not be cancelable.
- Let U be the user agent connected to D.
- If the next step fails, abort all remaining steps and close the presentation connection S with error as closeReason , and a human readable message describing the failure as closeMessage .
- Using an implementation specific mechanism, tell U to create a receiving browsing context with D , presentationUrl , and I as parameters.
- Establish a presentation connection with S .
6.3.5 Reconnecting to a presentation
When the reconnect method is called, the user agent MUST run the following steps to reconnect to a presentation:
- Return P , but continue running these steps in parallel.
- Its controlling browsing context is the current browsing context
- Its presentation connection state is not terminated
- Its presentation URL is equal to one of the presentation request URLs of presentationRequest
- Its presentation identifier is equal to presentationId
- Let existingConnection be that PresentationConnection .
- Resolve P with existingConnection .
- If the presentation connection state of existingConnection is connecting or connected , then abort all remaining steps.
- Set the presentation connection state of existingConnection to connecting .
- Establish a presentation connection with existingConnection .
- Its controlling browsing context is not the current browsing context
- Create a new PresentationConnection newConnection .
- Set the presentation identifier of newConnection to presentationId .
- Set the presentation URL of newConnection to the presentation URL of existingConnection .
- Set the presentation connection state of newConnection to connecting .
- Add newConnection to the set of controlled presentations .
- Resolve P with newConnection .
- Queue a task to fire an event named connectionavailable , that uses the PresentationConnectionAvailableEvent interface, with the connection attribute initialized to newConnection , at presentationRequest . The event must not bubble and must not be cancelable.
- Establish a presentation connection with newConnection .
6.3.6 Event Handlers
The following are the event handlers (and their corresponding event handler event types) that must be supported, as event handler IDL attributes, by objects implementing the PresentationRequest interface:
6.4 Interface PresentationAvailability
A PresentationAvailability object exposes the presentation display availability for a presentation request. The presentation display availability for a PresentationRequest stores whether there is currently any available presentation display for at least one of the presentation request URLs of the request.
The presentation display availability for a presentation request is eligible for garbage collection when no ECMASCript code can observe the PresentationAvailability object.
If the controlling user agent can monitor the list of available presentation displays in the background (without a pending request to start ), the PresentationAvailability object MUST be implemented in a controlling browsing context .
The value attribute MUST return the last value it was set to. The value is initialized and updated by the monitor the list of available presentation displays algorithm.
The onchange attribute is an event handler whose corresponding event handler event type is change .
6.4.1 The set of presentation availability objects
The user agent MUST keep track of the set of presentation availability objects created by the getAvailability method. The set of presentation availability objects is represented as a set of tuples ( A , availabilityUrls ) , initially empty, where:
- A is a live PresentationAvailability object.
- availabilityUrls is the list of presentation request URLs for the PresentationRequest when getAvailability was called on it to create A .
6.4.2 The list of available presentation displays
The user agent MUST keep a list of available presentation displays . The list of available presentation displays is represented by a list of tuples (availabilityUrl, display) . An entry in this list means that display is currently an available presentation display for availabilityUrl . This list of presentation displays may be used for starting new presentations, and is populated based on an implementation specific discovery mechanism. It is set to the most recent result of the algorithm to monitor the list of available presentation displays .
While the set of presentation availability objects is not empty, the user agent MAY monitor the list of available presentation displays continuously, so that pages can use the value property of a PresentationAvailability object to offer presentation only when there are available displays. However, the user agent may not support continuous availability monitoring in the background; for example, because of platform or power consumption restrictions. In this case the Promise returned by getAvailability is rejected , and the algorithm to monitor the list of available presentation displays will only run as part of the select a presentation display algorithm.
When the set of presentation availability objects is empty (that is, there are no availabilityUrls being monitored), user agents SHOULD NOT monitor the list of available presentation displays to satisfy the power saving non-functional requirement . To further save power, the user agent MAY also keep track of whether a page holding a PresentationAvailability object is in the foreground. Using this information, implementation specific discovery of presentation displays can be resumed or suspended.
6.4.3 Getting the presentation displays availability information
When the getAvailability method is called, the user agent MUST run the following steps:
- If there is an unsettled Promise from a previous call to getAvailability on presentationRequest , return that Promise and abort these steps.
- Otherwise, let P be a new Promise constructed in the JavaScript realm of presentationRequest .
- Reject P with a NotSupportedError exception.
- Abort all the remaining steps.
- Resolve P with the request's presentation display availability .
- Set the presentation display availability for presentationRequest to a newly created PresentationAvailability object constructed in the JavaScript realm of presentationRequest , and let A be that object.
- Create a tuple ( A , presentationUrls ) and add it to the set of presentation availability objects .
- Run the algorithm to monitor the list of available presentation displays . Note The monitoring algorithm must be run at least one more time after the previous step to pick up the tuple that was added to the set of presentation availability objects .
- Resolve P with A .
6.4.4 Monitoring the list of available presentation displays
If the set of presentation availability objects is non-empty, or there is a pending request to select a presentation display , the user agent MUST monitor the list of available presentation displays by running the following steps:
- Let availabilitySet be a shallow copy of the set of presentation availability objects .
- Let A be a newly created PresentationAvailability object.
- Create a tuple ( A , presentationUrls ) where presentationUrls is the PresentationRequest 's presentation request URLs and add it to availabilitySet .
- Let newDisplays be an empty list.
- If the user agent is unable to retrieve presentation displays (e.g., because the user has disabled this capability), then skip the following step.
- Retrieve presentation displays (using an implementation specific mechanism) and set newDisplays to this list.
- Set the list of available presentation displays to the empty list.
- Set previousAvailability to the value of A 's value property.
- Let newAvailability be false .
- Insert a tuple (availabilityUrl, display) into the list of available presentation displays , if no identical tuple already exists.
- Set newAvailability to true .
- If A 's value property has not yet been initialized, then set A 's value property to newAvailability and skip the following step.
- Set A 's value property to newAvailability .
- Fire an event named change at A .
When a presentation display availability object is eligible for garbage collection, the user agent SHOULD run the following steps:
- Let A be the newly deceased PresentationAvailability object
- Find and remove any entry ( A , availabilityUrl ) in the set of presentation availability objects .
- If the set of presentation availability objects is now empty and there is no pending request to select a presentation display , cancel any pending task to monitor the list of available presentation displays for power saving purposes, and set the list of available presentation displays to the empty list.
6.4.5 Interface PresentationConnectionAvailableEvent
A controlling user agent fires an event named connectionavailable on a PresentationRequest when a connection associated with the object is created. It is fired at the PresentationRequest instance, using the PresentationConnectionAvailableEvent interface, with the connection attribute set to the PresentationConnection object that was created. The event is fired for each connection that is created for the controller , either by the controller calling start or reconnect , or by the controlling user agent creating a connection on the controller's behalf via defaultRequest .
A receiving user agent fires an event named connectionavailable on a PresentationReceiver when an incoming connection is created. It is fired at the presentation controllers monitor , using the PresentationConnectionAvailableEvent interface, with the connection attribute set to the PresentationConnection object that was created. The event is fired for all connections that are created when monitoring incoming presentation connections .
The connection attribute MUST return the value it was set to when the PresentationConnection object was created.
When the PresentationConnectionAvailableEvent constructor is called, the user agent MUST construct a new PresentationConnectionAvailableEvent object with its connection attribute set to the connection member of the PresentationConnectionAvailableEventInit object passed to the constructor.
6.5 Interface PresentationConnection
Each presentation connection is represented by a PresentationConnection object. Both the controlling user agent and receiving user agent MUST implement PresentationConnection .
The id attribute specifies the presentation connection 's presentation identifier .
The url attribute specifies the presentation connection 's presentation URL .
The state attribute represents the presentation connection 's current state. It can take one of the values of PresentationConnectionState depending on the connection state:
- connecting means that the user agent is attempting to establish a presentation connection with the destination browsing context . This is the initial state when a PresentationConnection object is created.
- connected means that the presentation connection is established and communication is possible.
- closed means that the presentation connection has been closed, or could not be opened. It may be re-opened through a call to reconnect . No communication is possible.
- terminated means that the receiving browsing context has been terminated. Any presentation connection to that presentation is also terminated and cannot be re-opened. No communication is possible.
When the close method is called on a PresentationConnection S , the user agent MUST start closing the presentation connection S with closed as closeReason and an empty message as closeMessage .
When the terminate method is called on a PresentationConnection S in a controlling browsing context , the user agent MUST run the algorithm to terminate a presentation in a controlling browsing context using S .
When the terminate method is called on a PresentationConnection S in a receiving browsing context , the user agent MUST run the algorithm to terminate a presentation in a receiving browsing context using S .
The binaryType attribute can take one of the values of BinaryType . When a PresentationConnection object is created, its binaryType attribute MUST be set to the string " arraybuffer ". On getting, it MUST return the last value it was set to. On setting, the user agent MUST set the attribute to the new value.
When the send method is called on a PresentationConnection S , the user agent MUST run the algorithm to send a message through S .
When a PresentationConnection object S is discarded (because the document owning it is navigating or is closed) while the presentation connection state of S is connecting or connected , the user agent MUST start closing the presentation connection S with wentaway as closeReason and an empty closeMessage .
If the user agent receives a signal from the destination browsing context that a PresentationConnection S is to be closed, it MUST close the presentation connection S with closed or wentaway as closeReason and an empty closeMessage .
6.5.1 Establishing a presentation connection
When the user agent is to establish a presentation connection using a presentation connection , it MUST run the following steps:
- If the presentation connection state of presentationConnection is not connecting , then abort all remaining steps.
- Request connection of presentationConnection to the receiving browsing context . The presentation identifier of presentationConnection MUST be sent with this request.
- Set the presentation connection state of presentationConnection to connected .
- Fire an event named connect at presentationConnection .
- If the connection cannot be completed, close the presentation connection S with error as closeReason , and a human readable message describing the failure as closeMessage .
6.5.2 Sending a message through PresentationConnection
Let presentation message data be the payload data to be transmitted between two browsing contexts. Let presentation message type be the type of that data, one of text or binary .
When the user agent is to send a message through a presentation connection , it MUST run the following steps:
- If the state property of presentationConnection is not connected , throw an InvalidStateError exception.
- If the closing procedure of presentationConnection has started, then abort these steps.
- Let presentation message type messageType be binary if messageOrData is of type ArrayBuffer , ArrayBufferView , or Blob . Let messageType be text if messageOrData is of type DOMString .
- Using an implementation specific mechanism, transmit the contents of messageOrData as the presentation message data and messageType as the presentation message type to the destination browsing context .
- If the previous step encounters an unrecoverable error, then abruptly close the presentation connection presentationConnection with error as closeReason , and a closeMessage describing the error encountered.
To assist applications in recovery from an error sending a message through a presentation connection , the user agent should include details of which attempt failed in closeMessage , along with a human readable string explaining the failure reason. Example renditions of closeMessage :
- Unable to send text message (network_error): "hello" for DOMString messages, where "hello" is the first 256 characters of the failed message.
- Unable to send binary message (invalid_message) for ArrayBuffer , ArrayBufferView and Blob messages.
6.5.3 Receiving a message through PresentationConnection
When the user agent has received a transmission from the remote side consisting of presentation message data and presentation message type , it MUST run the following steps to receive a message through a PresentationConnection :
- If the state property of presentationConnection is not connected , abort these steps.
- Let event be the result of creating an event using the MessageEvent interface, with the event type message , which does not bubble and is not cancelable.
- If messageType is text , then initialize event 's data attribute to messageData with type DOMString .
- If messageType is binary , and binaryType attribute is set to " blob ", then initialize event 's data attribute to a new Blob object with messageData as its raw data.
- If messageType is binary , and binaryType attribute is set to " arraybuffer ", then initialize event 's data attribute to a new ArrayBuffer object whose contents are messageData .
- Queue a task to fire event at presentationConnection .
If the user agent encounters an unrecoverable error while receiving a message through presentationConnection , it MUST abruptly close the presentation connection presentationConnection with error as closeReason . It SHOULD use a human readable description of the error encountered as closeMessage .
6.5.4 Interface PresentationConnectionCloseEvent
A PresentationConnectionCloseEvent is fired when a presentation connection enters a closed state. The reason attribute provides the reason why the connection was closed. It can take one of the values of PresentationConnectionCloseReason :
- error means that the mechanism for connecting or communicating with a presentation entered an unrecoverable error.
- closed means that either the controlling browsing context or the receiving browsing context that were connected by the PresentationConnection called close() .
- wentaway means that the browser closed the connection, for example, because the browsing context that owned the connection navigated or was discarded.
When the reason attribute is error , the user agent SHOULD set the message attribute to a human readable description of how the communication channel encountered an error.
When the PresentationConnectionCloseEvent constructor is called, the user agent MUST construct a new PresentationConnectionCloseEvent object, with its reason attribute set to the reason member of the PresentationConnectionCloseEventInit object passed to the constructor, and its message attribute set to the message member of this PresentationConnectionCloseEventInit object if set, to an empty string otherwise.
6.5.5 Closing a PresentationConnection
When the user agent is to start closing a presentation connection , it MUST do the following:
- If the presentation connection state of presentationConnection is not connecting or connected then abort the remaining steps.
- Set the presentation connection state of presentationConnection to closed .
- Start to signal to the destination browsing context the intention to close the corresponding PresentationConnection , passing the closeReason to that context. The user agent does not need to wait for acknowledgement that the corresponding PresentationConnection was actually closed before proceeding to the next step.
- If closeReason is not wentaway , then locally run the steps to close the presentation connection with presentationConnection , closeReason , and closeMessage .
When the user agent is to close a presentation connection , it MUST do the following:
- If there is a pending close the presentation connection task for presentationConnection , or a close the presentation connection task has already run for presentationConnection , then abort the remaining steps.
- If the presentation connection state of presentationConnection is not connecting , connected , or closed , then abort the remaining steps.
- If the presentation connection state of presentationConnection is not closed , set it to closed .
- Remove presentationConnection from the set of presentation controllers .
- Populate the presentation controllers monitor with the set of presentation controllers .
- Fire an event named close , that uses the PresentationConnectionCloseEvent interface, with the reason attribute initialized to closeReason and the message attribute initialized to closeMessage , at presentationConnection . The event must not bubble and must not be cancelable.
6.5.6 Terminating a presentation in a controlling browsing context
When a controlling user agent is to terminate a presentation in a controlling browsing context using connection , it MUST run the following steps:
- If the presentation connection state of connection is not connected or connecting , then abort these steps.
- Set the presentation connection state of known connection to terminated .
- Fire an event named terminate at known connection .
- Send a termination request for the presentation to its receiving user agent using an implementation specific mechanism.
6.5.7 Terminating a presentation in a receiving browsing context
When any of the following occur, the receiving user agent MUST terminate a presentation in a receiving browsing context :
- The receiving user agent is to unload a document corresponding to the receiving browsing context , e.g. in response to a request to navigate that context to a new resource.
This could happen by an explicit user action, or as a policy of the user agent. For example, the receiving user agent could be configured to terminate presentations whose PresentationConnection objects are all closed for 30 minutes.
- A controlling user agent sends a termination request to the receiving user agent for that presentation.
When a receiving user agent is to terminate a presentation in a receiving browsing context , it MUST run the following steps:
- Let P be the presentation to be terminated, let allControllers be the set of presentation controllers that were created for P , and connectedControllers an empty list.
- If the presentation connection state of connection is connected , then add connection to connectedControllers .
- Set the presentation connection state of connection to terminated .
- If there is a receiving browsing context for P , and it has a document for P that is not unloaded, unload a document corresponding to that browsing context , remove that browsing context from the user interface and discard it.
Only one termination confirmation needs to be sent per controlling user agent .
6.5.8 Handling a termination confirmation in a controlling user agent
When a receiving user agent is to send a termination confirmation for a presentation P , and that confirmation was received by a controlling user agent , the controlling user agent MUST run the following steps:
- If the presentation connection state of connection is not connected or connecting , then abort the following steps.
- Fire an event named terminate at connection .
6.5.9 Event Handlers
The following are the event handlers (and their corresponding event handler event types) that must be supported, as event handler IDL attributes, by objects implementing the PresentationConnection interface:
6.6 Interface PresentationReceiver
The PresentationReceiver interface allows a receiving browsing context to access the controlling browsing contexts and communicate with them. The PresentationReceiver interface MUST be implemented in a receiving browsing context provided by a receiving user agent .
On getting, the connectionList attribute MUST return the result of running the following steps:
- If the presentation controllers promise is not null , return the presentation controllers promise and abort all remaining steps.
- Otherwise, let the presentation controllers promise be a new Promise constructed in the JavaScript realm of this PresentationReceiver object.
- Return the presentation controllers promise .
- If the presentation controllers monitor is not null , resolve the presentation controllers promise with the presentation controllers monitor .
6.6.1 Creating a receiving browsing context
When the user agent is to create a receiving browsing context , it MUST run the following steps:
- Create a new top-level browsing context C , set to display content on D .
- Set the session history of C to be the empty list.
- Set the sandboxed modals flag and the sandboxed auxiliary navigation browsing context flag on C .
- If the receiving user agent implements [ PERMISSIONS ], set the permission state of all permission descriptor types for C to "denied" .
- Create a new empty cookie store for C .
- Create a new empty store for C to hold HTTP authentication states.
- Create a new empty storage for session storage areas and local storage areas for C .
- If the receiving user agent implements [ INDEXEDDB ], create a new empty storage for IndexedDB databases for C .
- If the receiving user agent implements [ SERVICE-WORKERS ], create a new empty list of registered service worker registrations and a new empty set of Cache objects for C .
- Navigate C to presentationUrl .
- Start monitoring incoming presentation connections for C with presentationId and presentationUrl .
All child navigables created by the presented document, i.e. that have the receiving browsing context as their top-level browsing context , MUST also have restrictions 2-4 above. In addition, they MUST have the sandboxed top-level navigation without user activation browsing context flag set. All of these browsing contexts MUST also share the same browsing state (storage) for features 5-10 listed above.
When the top-level browsing context attempts to navigate to a new resource and runs the steps to navigate , it MUST follow step 1 to determine if it is allowed to navigate . In addition, it MUST NOT be allowed to navigate itself to a new resource, except by navigating to a fragment identifier or by reloading its document .
This allows the user to grant permission based on the origin of the presentation URL shown when selecting a presentation display .
If the top-level-browsing context was not allowed to navigate , it SHOULD NOT offer to open the resource in a new top-level browsing context , but otherwise SHOULD be consistent with the steps to navigate .
Window clients and worker clients associated with the receiving browsing context and its descendant navigables must not be exposed to service workers associated with each other.
When the receiving browsing context is terminated, any service workers associated with it and the browsing contexts in its descendant navigables MUST be unregistered and terminated. Any browsing state associated with the receiving browsing context and the browsing contexts in its descendant navigables , including session history , the cookie store , any HTTP authentication state, any databases , the session storage areas , the local storage areas , the list of registered service worker registrations and the Cache objects MUST be discarded and not used for any other browsing context .
This algorithm is intended to create a well defined environment to allow interoperable behavior for 1-UA and 2-UA presentations, and to minimize the amount of state remaining on a presentation display used for a 2-UA presentation.
The receiving user agent SHOULD fetch resources in a receiving browsing context with an HTTP Accept-Language header that reflects the language preferences of the controlling user agent (i.e., with the same Accept-Language that the controlling user agent would have sent). This will help the receiving user agent render the presentation with fonts and locale-specific attributes that reflect the user's preferences.
Given the operating context of the presentation display , some Web APIs will not work by design (for example, by requiring user input) or will be obsolete (for example, by attempting window management); the receiving user agent should be aware of this. Furthermore, any modal user interface will need to be handled carefully. The sandboxed modals flag is set on the receiving browsing context to prevent most of these operations.
As noted in Conformance , a user agent that is both a controlling user agent and receiving user agent may allow a receiving browsing context to create additional presentations (thus becoming a controlling browsing context as well). Web developers can use navigator.presentation.receiver to detect when a document is loaded as a receiving browsing context.
6.7 Interface PresentationConnectionList
The connections attribute MUST return the non-terminated set of presentation connections in the set of presentation controllers .
6.7.1 Monitoring incoming presentation connections
When the receiving user agent is to start monitoring incoming presentation connections in a receiving browsing context from controlling browsing contexts , it MUST listen to and accept incoming connection requests from a controlling browsing context using an implementation specific mechanism. When a new connection request is received from a controlling browsing context , the receiving user agent MUST run the following steps:
- If presentationId and I are not equal, refuse the connection and abort all remaining steps.
- Set the presentation URL of S to presentationUrl .
- Establish the connection between the controlling and receiving browsing contexts using an implementation specific mechanism.
- If connection establishment completes successfully, set the presentation connection state of S to connected . Otherwise, set the presentation connection state of S to closed and abort all remaining steps.
- Add S to the set of presentation controllers .
- Let the presentation controllers monitor be a new PresentationConnectionList constructed in the JavaScript realm of the PresentationReceiver object of the receiving browsing context .
- If the presentation controllers promise is not null , resolve the presentation controllers promise with the presentation controllers monitor .
- Queue a task to fire an event named connectionavailable , that uses the PresentationConnectionAvailableEvent interface, with the connection attribute initialized to S , at the presentation controllers monitor . The event must not bubble and must not be cancelable.
6.7.2 Event Handlers
The following are the event handlers (and their corresponding event handler event types) that must be supported, as event handler IDL attributes, by objects implementing the PresentationConnectionList interface:
7. Security and privacy considerations
7.1 personally identifiable information.
The change event fired on the PresentationAvailability object reveals one bit of information about the presence or absence of a presentation display , often discovered through the browser's local area network. This could be used in conjunction with other information for fingerprinting the user. However, this information is also dependent on the user's local network context, so the risk is minimized.
The API enables monitoring the list of available presentation displays . How the user agent determines the compatibility and availability of a presentation display with a given URL is an implementation detail. If a controlling user agent matches a presentation request URL to a DIAL application to determine its availability, this feature can be used to probe information about which DIAL applications the user has installed on the presentation display without user consent.
7.2 Cross-origin access
A presentation is allowed to be accessed across origins; the presentation URL and presentation identifier used to create the presentation are the only information needed to reconnect to a presentation from any origin in the controlling user agent. In other words, a presentation is not tied to a particular opening origin.
This design allows controlling contexts from different origins to connect to a shared presentation resource. The security of the presentation identifier prevents arbitrary origins from connecting to an existing presentation.
This specification also allows a receiving user agent to publish information about its set of controlled presentations , and a controlling user agent to reconnect to presentations started from other devices. This is possible when the controlling browsing context obtains the presentation URL and presentation identifier of a running presentation from the user, local storage, or a server, and then connects to the presentation via reconnect .
This specification makes no guarantee as to the identity of any party connecting to a presentation. Once connected, the presentation may wish to further verify the identity of the connecting party through application-specific means. For example, the presentation could challenge the controller to provide a token via send that the presentation uses to verify identity and authorization.
7.3 User interface guidelines
When the user is asked permission to use a presentation display during the steps to select a presentation display , the controlling user agent should make it clear what origin is requesting presentation and what origin will be presented.
Display of the origin requesting presentation will help the user understand what content is making the request, especially when the request is initiated from a child navigable . For example, embedded content may try to convince the user to click to trigger a request to start an unwanted presentation.
The sandboxed top-level navigation without user activation browsing context flag is set on the receiving browsing context to enforce that the top-level origin of the presentation remains the same during the lifetime of the presentation.
When a user starts a presentation , the user will begin with exclusive control of the presentation. However, the Presentation API allows additional devices (likely belonging to distinct users) to connect and thereby control the presentation as well. When a second device connects to a presentation, it is recommended that all connected controlling user agents notify their users via the browser chrome that the original user has lost exclusive access, and there are now multiple controllers for the presentation.
In addition, it may be the case that the receiving user agent is capable of receiving user input, as well as acting as a presentation display . In this case, the receiving user agent should notify its user via browser chrome when a receiving browsing context is under the control of a remote party (i.e., it has one or more connected controllers).
7.4 Device Access
The presentation API abstracts away what "local" means for displays, meaning that it exposes network-accessible displays as though they were directly attached to the user's device. The Presentation API requires user permission for a page to access any display to mitigate issues that could arise, such as showing unwanted content on a display viewable by others.
7.5 Temporary identifiers and browser state
The presentation URL and presentation identifier can be used to connect to a presentation from another browsing context. They can be intercepted if an attacker can inject content into the controlling page.
7.6 Private browsing mode and clearing of browsing data
The content displayed on the presentation is different from the controller. In particular, if the user is logged in in both contexts, then logs out of the controlling browsing context , they will not be automatically logged out from the receiving browsing context . Applications that use authentication should pay extra care when communicating between devices.
The set of presentations known to the user agent should be cleared when the user requests to "clear browsing data."
When in private browsing mode ("incognito"), the initial set of controlled presentations in that browsing session must be empty. Any presentation connections added to it must be discarded when the session terminates.
7.7 Messaging between presentation connections
This spec will not mandate communication protocols between the controlling browsing context and the receiving browsing context , but it should set some guarantees of message confidentiality and authenticity between corresponding presentation connections .
A. IDL Index
B.1 terms defined by this specification.
- 1-UA mode §1.
- 2-UA mode §1.
- Accept-Language §4.
- allowed to navigate §4.
- available presentation display §6.1
- binaryType attribute for PresentationConnection §6.5
- change §6.4
- close method for PresentationConnection §6.5
- close a presentation connection §6.5.5
- enum value for PresentationConnectionState §6.5
- enum value for PresentationConnectionCloseReason §6.5.4
- connect §6.5.9
- "connected" enum value for PresentationConnectionState §6.5
- "connecting" enum value for PresentationConnectionState §6.5
- attribute for PresentationConnectionAvailableEvent §6.4.5
- member for PresentationConnectionAvailableEventInit §6.4.5
- connectionavailable §6.3.6
- connectionList attribute for PresentationReceiver §6.6
- connections attribute for PresentationConnectionList §6.7
- for PresentationRequest §6.3
- for PresentationConnectionAvailableEvent §6.4.5
- for PresentationConnectionCloseEvent §6.5.4
- controlling browsing context §6.1
- Controlling user agent §3.1
- cookie store §4.
- create a receiving browsing context §6.6.1
- creating a new browsing context §4.
- current realm §4.
- database §4.
- default presentation request §6.1
- defaultRequest attribute for Presentation §6.2.1
- destination browsing context §6.1
- "error" enum value for PresentationConnectionCloseReason §6.5.4
- establish a presentation connection §6.5.1
- getAvailability method for PresentationRequest §6.4.3
- HTTP authentication §4.
- id attribute for PresentationConnection §6.5
- JavaScript realm §4.
- list of available presentation displays §6.4.2
- local storage area §4.
- attribute for PresentationConnectionCloseEvent §6.5.4
- member for PresentationConnectionCloseEventInit §6.5.4
- monitor the list of available presentation displays §6.4.4
- monitoring incoming presentation connections §6.7.1
- navigating to a fragment identifier §4.
- onchange attribute for PresentationAvailability §6.4
- onclose attribute for PresentationConnection §6.5.9
- onconnect attribute for PresentationConnection §6.5.9
- attribute for PresentationRequest §6.3.6
- attribute for PresentationConnectionList §6.7.2
- onmessage attribute for PresentationConnection §6.5.9
- onterminate attribute for PresentationConnection §6.5.9
- parse a url §4.
- presentation attribute for Navigator §6.2
- Presentation interface §6.2
- presentation connection §6.1
- presentation connection state §6.1
- presentation controllers monitor §6.1
- presentation controllers promise §6.1
- presentation display §6.1
- presentation display availability §6.4
- presentation identifier §6.1
- presentation message data §6.5.2
- presentation message type §6.5.2
- presentation request URLs §6.3
- presentation URL §6.1
- PresentationAvailability interface §6.4
- PresentationConnection interface §6.5
- PresentationConnectionAvailableEvent interface §6.4.5
- PresentationConnectionAvailableEventInit dictionary §6.4.5
- PresentationConnectionCloseEvent interface §6.5.4
- PresentationConnectionCloseEventInit dictionary §6.5.4
- PresentationConnectionCloseReason enum §6.5.4
- PresentationConnectionList interface §6.7
- PresentationConnectionState enum §6.5
- PresentationReceiver interface §6.6
- PresentationRequest interface §6.3
- receive a message §6.5.3
- receiver attribute for Presentation §6.2.2
- receiving browsing context §6.1
- Receiving user agent §3.1
- reconnect method for PresentationRequest §6.3.5
- rejected §4.
- reload a document §4.
- resolved §4.
- select a presentation display §6.3.2
- send method for PresentationConnection §6.5
- send a message §6.5.2
- Send a termination request §6.5.6
- session history §4.
- session storage area §4.
- set of controlled presentations §6.1
- set of presentation availability objects §6.4.1
- set of presentation controllers §6.1
- start method for PresentationRequest §6.3.2
- start a presentation connection §6.3.4
- start a presentation from a default presentation request §6.3.3
- start closing a presentation connection §6.5.5
- state attribute for PresentationConnection §6.5
- terminate method for PresentationConnection §6.5
- terminate a presentation in a controlling browsing context §6.5.6
- terminate a presentation in a receiving browsing context §6.5.7
- "terminated" enum value for PresentationConnectionState §6.5
- unload a document §4.
- url attribute for PresentationConnection §6.5
- user agents §3.1
- valid presentation identifier §6.1
- value attribute for PresentationAvailability §6.4
- "wentaway" enum value for PresentationConnectionCloseReason §6.5.4
B.2 Terms defined by reference
- creating an event
- Event interface
- EventTarget interface
- fire an event
- Blob interface
- active sandboxing flag set (for Document )
- active window (for navigable )
- browsing context
- child navigable
- current settings object
- descendant navigables (for Document )
- event handler
- event handler event type
- EventHandler
- in parallel
- localStorage attribute (for WindowLocalStorage )
- MessageEvent interface
- Navigator interface
- Queue a task
- reload() (for Location )
- sandboxed auxiliary navigation browsing context flag
- sandboxed modals flag
- sandboxed presentation browsing context flag
- sandboxed top-level navigation without user activation browsing context flag
- sessionStorage attribute (for WindowSessionStorage )
- task source
- top-level browsing context
- transient activation
- permission descriptor types (for powerful feature)
- permission state
- potentially trustworthy URL
- Cache interface
- service worker registrations
- service workers
- window client (for service worker client)
- worker client (for service worker client)
- ArrayBuffer interface
- ArrayBufferView
- boolean type
- DOMString interface
- [Exposed] extended attribute
- FrozenArray interface
- InvalidAccessError exception
- InvalidStateError exception
- NotAllowedError exception
- NotFoundError exception
- NotSupportedError exception
- OperationError exception
- Promise interface
- [SameObject] extended attribute
- [SecureContext] extended attribute
- SecurityError exception
- SyntaxError exception
- throw (for exception )
- undefined type
- USVString interface
- RTCDataChannel interface
- BinaryType enum
C. Acknowledgments
Thanks to Addison Phillips, Anne Van Kesteren, Anssi Kostiainen, Anton Vayvod, Chris Needham, Christine Runnegar, Daniel Davis, Domenic Denicola, Erik Wilde, François Daoust, 闵洪波 (Hongbo Min), Hongki CHA, Hubert Sablonnière, Hyojin Song, Hyun June Kim, Jean-Claude Dufourd, Joanmarie Diggs, Jonas Sicking, Louay Bassbouss, Mark Watson, Martin Dürst, Matt Hammond, Mike West, Mounir Lamouri, Nick Doty, Oleg Beletski, Philip Jägenstedt, Richard Ishida, Shih-Chiang Chien, Takeshi Kanai, Tobie Langel, Tomoyuki Shimizu, Travis Leithead, and Wayne Carr for help with editing, reviews and feedback to this draft.
AirPlay , HDMI , Chromecast , DLNA and Miracast are registered trademarks of Apple Inc., HDMI Licensing LLC., Google Inc., the Digital Living Network Alliance, and the Wi-Fi Alliance, respectively. They are only cited as background information and their use is not required to implement the specification.
D. Candidate Recommendation exit criteria
For this specification to be advanced to Proposed Recommendation, there must be, for each of the conformance classes it defines ( controlling user agent and receiving user agent ), at least two independent, interoperable implementations of each feature. Each feature may be implemented by a different set of products, there is no requirement that all features be implemented by a single product. Additionally, implementations of the controlling user agent conformance class must include at least one implementation of the 1-UA mode , and one implementation of the 2-UA mode . 2-UA mode implementations may only support non http/https presentation URLs. Implementations of the receiving user agent conformance class may not include implementations of the 2-UA mode .
The API was recently restricted to secure contexts. Deprecation of the API in non secure contexts in early implementations takes time. The group may request transition to Proposed Recommendation with implementations that still expose the API in non secure contexts, provided there exists a timeline to restrict these implementations in the future.
For the purposes of these criteria, we define the following terms:
- implements one of the conformance classes of the specification.
- is available to the general public. The implementation may be a shipping product or other publicly available version (i.e., beta version, preview release, or "nightly build"). Non-shipping product releases must have implemented the feature(s) for a period of at least one month in order to demonstrate stability.
- is not experimental (i.e. a version specifically designed to pass the test suite and not intended for normal usage going forward).
E. Change log
This section lists changes made to the spec since it was first published as Candidate Recommendation in July 2016, with links to related issues on the group's issue tracker.
E.1 Changes since 01 June 2017
- Added a note about receiving browsing contexts starting presentations ( #487 )
- Removed the definition of the BinaryType enum ( #473 )
- Updated WebIDL to use constructor operations ( #469 )
- Clarified how receiving browsing contexts are allowed to navigate ( #461 )
- Added explanatory text to the sample code ( #460 )
- Added sample code that starts a second presentation from the same controller ( #453 )
- Updated the steps to construct a PresentationRequest to ignore a URL with an unsupported scheme ( #447 )
- Clarified restrictions on navigation in receiving browsing contexts ( #434 )
- Updated WebIDL to use [Exposed=Window] ( #438 )
- Various editorial updates ( #429 , #431 , #432 , #433 , #441 , #442 , #443 , #454 , #465 , #482 , #483 , #486 )
E.2 Changes since 14 July 2016
- Fixed document license ( #428 )
- Updated termination algorithm to also discard the receiving browsing context and allow termination in a connecting state ( #421 , #423 )
- Dropped sandboxing section, now integrated in HTML ( #437 in the Web Platform Working Group issue tracker)
- Relaxed exit criteria to match known implementations plans ( #406 )
- The sandboxed top-level navigation browsing context flag and the sandboxed modals flag are now set on the receiving browsing context to prevent top-level navigation and the ability to spawn new browsing contexts ( #414 )
- Moved sandboxing flag checks to PresentationRequest constructor ( #379 , #398 )
- Updated normative references to target stable specifications ( #295 , #396 )
- Made display selection algorithm reject in ancestor and descendant browsing context ( #394 )
- Renamed PresentationConnectionClosedReason to PresentationConnectionCloseReason ( #393 )
- Fixed getAvailability and monitoring algorithms ( #335 , #381 , #382 , #383 , #387 , #388 , #392 )
- Assigned correct JavaScript realm to re-used objects ( #391 )
- API now restricted to secure contexts ( #380 )
- Set the state of receiving presentation connections to terminated before unload ( #374 )
- Defined environment for nested contexts of the receiving browsing context ( #367 )
- Removed [SameObject] from Presentation.receiver and PresentationReceiver.connectionList ( #365 , #407 )
- Replaced DOMString with USVString for PresentationRequest URLs ( #361 )
- Added a presentation task source for events ( #360 )
- Changed normative language around UUID generation ( #346 )
- Added failure reason to close message ( #344 )
- Added error handling to establish a presentation connection algorithm ( #343 )
- Made navigator.presentation mandatory ( #341 )
- Used current settings object in steps that require a settings object ( #336 )
- Updated security check step to handle multiple URLs case ( #329 )
- Made PresentationConnection.id mandatory ( #325 )
- Renamed PresentationConnectionClosedEvent to PresentationConnectionCloseEvent ( #324 )
- Added an implementation note for advertising and rendering a user friendly display name ( #315 )
- Added note for presentation detection ( #303 )
- Various editorial updates ( #334 , #337 , #339 , #340 , #342 , #345 , #359 , #363 , #366 , #397 )
F. References
F.1 normative references, f.2 informative references.
Referenced in:
- § 1. Introduction
- § 3.1 Conformance classes
- § 6.6.1 Creating a receiving browsing context
- § D. Candidate Recommendation exit criteria
- § 6.6.1 Creating a receiving browsing context (2)
- § D. Candidate Recommendation exit criteria (2) (3)
- § 6.3.2 Selecting a presentation display (2)
- § 6.3.4 Starting a presentation connection
- § 6.3.5 Reconnecting to a presentation
- § 6.4.1 The set of presentation availability objects
- § 6.4.2 The list of available presentation displays (2) (3) (4)
- § 6.4.4 Monitoring the list of available presentation displays (2) (3)
- § 6.4.5 Interface PresentationConnectionAvailableEvent
- § 6.5 Interface PresentationConnection (2) (3) (4) (5) (6)
- § 6.5.1 Establishing a presentation connection
- § 6.5.2 Sending a message through PresentationConnection
- § 6.5.3 Receiving a message through PresentationConnection (2)
- § 6.5.4 Interface PresentationConnectionCloseEvent
- § 6.5.5 Closing a PresentationConnection (2)
- § 3.1 Conformance classes (2) (3)
- § 6.1 Common idioms (2)
- § 6.2.1 Controlling user agent (2) (3) (4)
- § 6.3 Interface PresentationRequest
- § 6.3.1 Constructing a PresentationRequest (2)
- § 6.3.3 Starting a presentation from a default presentation request
- § 6.4 Interface PresentationAvailability
- § 6.4.4 Monitoring the list of available presentation displays
- § 6.4.5 Interface PresentationConnectionAvailableEvent (2)
- § 6.5 Interface PresentationConnection
- § 6.5.6 Terminating a presentation in a controlling browsing context (2)
- § 6.5.7 Terminating a presentation in a receiving browsing context (2) (3)
- § 6.5.8 Handling a termination confirmation in a controlling user agent (2)
- § 7.1 Personally identifiable information
- § 7.2 Cross-origin access
- § 7.3 User interface guidelines (2)
- § D. Candidate Recommendation exit criteria (2)
- § 6.1 Common idioms
- § 6.2.2 Receiving user agent (2)
- § 6.5.6 Terminating a presentation in a controlling browsing context
- § 6.5.7 Terminating a presentation in a receiving browsing context (2) (3) (4) (5) (6)
- § 6.5.8 Handling a termination confirmation in a controlling user agent
- § 6.6 Interface PresentationReceiver
- § 6.6.1 Creating a receiving browsing context (2) (3) (4) (5) (6) (7)
- § 6.7.1 Monitoring incoming presentation connections (2)
- § 6.4.3 Getting the presentation displays availability information (2)
- § 6.7.1 Monitoring incoming presentation connections
- § 6.3.5 Reconnecting to a presentation (2)
- § 6.3.2 Selecting a presentation display
- § 6.4.2 The list of available presentation displays
- § 6.4.3 Getting the presentation displays availability information
- § 7.1 Personally identifiable information (2)
- § 6.3.1 Constructing a PresentationRequest
- § 6.5.7 Terminating a presentation in a receiving browsing context (2)
- § 1. Introduction (2) (3) (4) (5) (6)
- § 5.1 Monitoring availability of presentation displays
- § 6.3.3 Starting a presentation from a default presentation request (2)
- § 6.4.2 The list of available presentation displays (2)
- § 6.4.4 Monitoring the list of available presentation displays (2) (3) (4)
- § 6.6.1 Creating a receiving browsing context (2) (3)
- § 7.1 Personally identifiable information (2) (3)
- § 6.1 Common idioms (2) (3) (4) (5) (6) (7) (8) (9)
- § 6.3.4 Starting a presentation connection (2)
- § 6.5 Interface PresentationConnection (2) (3) (4) (5) (6) (7)
- § 6.5.2 Sending a message through PresentationConnection (2) (3) (4)
- § 6.5.3 Receiving a message through PresentationConnection
- § 6.7 Interface PresentationConnectionList
- § 7.6 Private browsing mode and clearing of browsing data
- § 7.7 Messaging between presentation connections
- § 6.3.5 Reconnecting to a presentation (2) (3) (4) (5)
- § 6.5.1 Establishing a presentation connection (2)
- § 6.5.5 Closing a PresentationConnection (2) (3) (4)
- § 6.5.6 Terminating a presentation in a controlling browsing context (2) (3)
- § 6.1 Common idioms (2) (3)
- § 6.3.4 Starting a presentation connection (2) (3)
- § 6.3.5 Reconnecting to a presentation (2) (3) (4)
- § 6.7.1 Monitoring incoming presentation connections (2) (3)
- § 7.2 Cross-origin access (2)
- § 7.5 Temporary identifiers and browser state
- § 6.1 Common idioms (2) (3) (4)
- § 1. Introduction (2) (3)
- § 3.1 Conformance classes (2)
- § 6.1 Common idioms (2) (3) (4) (5) (6) (7) (8)
- § 6.3 Interface PresentationRequest (2)
- § 6.7.1 Monitoring incoming presentation connections (2) (3) (4)
- § 6.1 Common idioms (2) (3) (4) (5) (6) (7) (8) (9) (10) (11)
- § 6.2.2 Receiving user agent (2) (3)
- § 6.5 Interface PresentationConnection (2) (3)
- § 6.5.5 Closing a PresentationConnection
- § 6.6 Interface PresentationReceiver (2)
- § 6.5 Interface PresentationConnection (2)
- § 6.5.7 Terminating a presentation in a receiving browsing context
- § 6.3.5 Reconnecting to a presentation (2) (3)
- § 6.7.1 Monitoring incoming presentation connections (2) (3) (4) (5) (6)
- § 6.6 Interface PresentationReceiver (2) (3) (4) (5)
- § 6.2.1 Controlling user agent (2) (3) (4) (5)
- § 6.2 Interface Presentation (2) (3) (4)
- § 6.2.1 Controlling user agent
- § 6.2.2 Receiving user agent
- § A. IDL Index (2) (3) (4)
- § 6.2 Interface Presentation
- § A. IDL Index
- § 5.4 Starting a presentation by the controlling user agent
- § 6.2.1 Controlling user agent (2)
- § 5.2 Starting a new presentation (2)
- § 6.3 Interface PresentationRequest (2) (3) (4) (5)
- § 6.3.1 Constructing a PresentationRequest (2) (3) (4)
- § 6.3.6 Event Handlers
- § A. IDL Index (2)
- Not referenced in this document.
- § 7.3 User interface guidelines
- § 6.4 Interface PresentationAvailability (2) (3) (4)
- § 6.4.4 Monitoring the list of available presentation displays (2)
- § 6.4 Interface PresentationAvailability (2)
- § 6.4.3 Getting the presentation displays availability information (2) (3)
- § 6.4.1 The set of presentation availability objects (2)
- § 6.4.5 Interface PresentationConnectionAvailableEvent (2) (3) (4) (5)
- § 6.4.5 Interface PresentationConnectionAvailableEvent (2) (3) (4)
- § 5.2 Starting a new presentation
- § 5.3 Reconnecting to an existing presentation (2)
- § 5.5 Monitoring the connection state and exchanging data (2)
- § 6.3.5 Reconnecting to a presentation (2) (3) (4) (5) (6) (7)
- § 6.5 Interface PresentationConnection (2) (3) (4) (5) (6) (7) (8) (9) (10) (11)
- § 6.5.5 Closing a PresentationConnection (2) (3)
- § 6.5.9 Event Handlers
- § A. IDL Index (2) (3) (4) (5) (6)
- § 5.3 Reconnecting to an existing presentation
- § 5.5 Monitoring the connection state and exchanging data
- § 6.5 Interface PresentationConnection (2) (3) (4)
- § 6.5.2 Sending a message through PresentationConnection (2)
- § 6.5.4 Interface PresentationConnectionCloseEvent (2) (3) (4)
- § 6.5.4 Interface PresentationConnectionCloseEvent (2) (3)
- § A. IDL Index (2) (3)
- § 6.5.4 Interface PresentationConnectionCloseEvent (2)
- § 6.6 Interface PresentationReceiver (2) (3) (4)
- § 5.6 Listening for incoming presentation connections
- § 6.7.2 Event Handlers
- § 6.6.1 Creating a receiving browsing context (2) (3) (4)
- § A. IDL Index (2) (3) (4) (5) (6) (7)
- § 4. Terminology
- § A. IDL Index (2) (3) (4) (5)
- § A. IDL Index (2) (3) (4) (5) (6) (7) (8)
- § 6.3 Interface PresentationRequest (2) (3)
- § 6.3.2 Selecting a presentation display (2) (3) (4) (5)
- § 6.4.3 Getting the presentation displays availability information (2) (3) (4)
- § 6.2 Interface Presentation (2)
- § A. IDL Index (2) (3) (4) (5) (6) (7) (8) (9)

The Chromium Projects
Media router & web presentation api.
This document is obsolete and will be removed soon. The new version is here .
The media router is a component in Chrome responsible for matching clients that wish to render content outside the browser ( media sources ) with devices and endpoints capable of rendering that content ( media sinks ). When a media source is linked with a m edia sink (in general, requiring user permission), a media route is created that allows two-way messaging between the client and the sink. The media route allows the client to negotiate a peer-to-peer media streaming session with the media sink via messaging (e.g., via WebRTC or Cast Streaming ), aka "mirroring." The media route can also be used to control remotely rendered media without an associated peer-to-peer media streaming session, aka "flinging". The media route can be terminated at user or client request, which denies access to the media sink from the application.
The Web Presentation API allows a Web application to request display of Web content on a secondary (wired, or wireless) screen. The content may be rendered locally and streamed to the display or rendered remotely. The Web application controls the content by two-way messaging.
Note that the non-Blink parts of the media router will be implemented only in desktop Chrome and ChromeOS. Presentation API functionality will be implemented in Chrome for Android using analogous platform components such as the Android Media Route Provider framework .
Also note that a separate design is in progress for offscreen rendering, capture, and streaming of WebContents (required for full Presentation API support).
The objectives of this project:
- Allow use of media sinks from a multitude of clients, including: Web applications via the Presentation API ; Chrome apps; the browser itself; and the Chrome OS system shell.
- Support mirroring locally rendered content to external screens, including on-screen and off-screen tabs, Chrome apps windows, and the system desktop.
- Support "flinging" HTML5 documents to remote devices capable of rendering them.
- Support the Cast Chrome Sender SDK on desktop and Android without any user installed extensions.
- Allow new types of media sinks to be added to Chrome by implementing additional Media Route Providers.
The following are non-goals but may be objectives for future work:
- Multicast of local content to multiple sinks at once.
- Support for third party media route providers (in Javascript or NaCl) or run-time installation of media route providers.
- Support for sinks that are not primarily intended to render media.
The media router consists of four distinct components:
- The Chrome Media Router is a browser service exposed in-process via C++ API and is exposed to other processes via a set of two Mojo interfaces: the Presentation interface and the Media Router API interface. Its job is to field requests from clients for media sink availability, media route construction/destriction, and media route control via messaging. It also controls the Media Router Dialog and delegates many functions to the Media Router component extension.
- The Media Router extension is an external component extension responsible for direct interaction with media sinks. The component extension will initially support use of Cast and DIAL devices with more types of sinks to be added over time. The component extension interacts with the Chrome Media Router via the Media Router API Mojo service, and uses some chrome.* platform APIs, such as chrome.dial, chrome.cast.channel, and chrome.mdns to implement network level interaction with Cast and DIAL devices.
- Users interact with the Chrome Media Router through the Media Router Dialog. This WebUI component allows users to choose the destination media sink for new media routes and view and stop active media routes. It may be pulled up by the user clicking the Cast icon in the browser toolbar, or at the request of a Web application via the Presentation API.
- The Presentation Mojo interface acts as a bridge between the Chrome Media Router and the Blink implementation of the Presentation API ( launch bug ).
Architecture
The following diagram illustrates the architecture of the components described above.
Chrome Media Router
The Chrome Media Router is a browser-resident service that serves as a media-protocol-agnostic platform for parties interested in media routing. It provides its clients with a set of APIs for media routing related queries and operations, including:
- Register for notifications when a sink is available that can render a media source. (Media sources are represented as URIs and can represent local media or remotely hosted content.)
- Request routing of media for that source, which will show the user the media router dialog to select a compatible sink. If the user selects a sink, the media route is returned to the application to allow it to control media playback.
- Accept media control actions from the Media Router Dialog for an active media route and forwarding them to the associated route provider.
- Send and receive arbitrary (string) messages between the application the media sink.
- Terminate media routes, and notify the client and media route provider when that happens.
The Chrome Media Router, itself, does not directly interact with media sinks. Instead it delegates these requests and responses to a media route provider in the component extension. The Chrome Media Router will contain bookkeeping of established routes, pending route requests, and other related resources, so it does not have to request this information from the route provider each time.
The following pseudocode describes how a client of the Chrome Media Router (through its C++ API) would use it to initiate and control a media sharing session.
Media Router API Example
The Media Router interacts with the component extension via a Mojo service, the Media Router API, that exposes functionality whose implementation is delegated to the extension.
Media Router API Mojo Interface
Media router component extension.
The component extension manages discovery of and network interaction with individual media sinks. For the purposes of this discussion a sink is a LAN-connected device that speaks the Cast or DIAL protocol, but in theory it could be any other type of endpoint that supports media rendering and two-way messaging. The extension consists of three types of components:
- Media Route Providers: Each provider is a Javascript bundle that knows how to find and communicate with a specific type of media sink. It communicates with the media sink using HTTP/XHR or via device-specific network protocols (e.g., Cast Channel and Cast Streaming).
- Media Route Provider Manager: This is responsible for dispatching requests from the Chrome Media Router to individual providers. It also registers providers on startup.
- Mirroring Service: If a media source is requested that represents the tab or desktop contents, this service acts on the behalf of the application to initiate the mirroring session. This is handled internally to the component extension and is not exposed to the rest of the browser, it appears to be just another media route.
A component extension is used rather than implementing functionality directly into the browser since remote display functionality is implemented by first and third parties using a mix of open source and proprietary code, and must be released on a schedule independently of Chrome (i.e. tied to specific hardware release dates). We only plan to open source the DIAL media route provider.
The component extension is written in JavaScript using the Closure library and will be available via two public channels; the default, “stable” extension will be installed as an external component without the user needing to visit the Web Store. Users may choose to install a pre-release “beta” extension via the Web Store, which disables the stable version.
Initially Media Route Providers will be implemented for Cast and DIAL devices with others to follow. Over time media route providers that do not rely on proprietary protocols will be unbundled and included in the Chromium repository, once script packaging and deployment issues are resolved. As an external component, the extension is installed on the initial run of the browser. It is built around an event page so it registers itself with the Media Router, registers itself with discovery APIs to be notified of display availability, and then suspends. The component extension will only be active when there are applications with pending sink availability requests or media routes, or when there is active network traffic between the extension and a media sink.
There are several modules to the extension that are loaded on-demand. The main event page bundles are 238kb. Updates are independent of Chrome.
Tab/Desktop Mirroring
Tab and desktop mirroring will request routing of a media source with URN like urn:google:tab:3 representing tab contents. When the component extension receives a request to route this source, the media route provider manager will query route providers to enumerate sinks that can render streamed tab contents. Once a sink is selected by the user, the mirroring service will create the appropriate MediaStream using the chrome.tabCapture extension API. The MediaStream will then be passed to a Cast Streaming or WebRTC session depending on the preferred protocol of the selected sink. When the media route is terminated, the associated streaming session and media capture are also terminated. A similar approach will be used for desktop mirroring but using chrome.desktopCapture instead.
Presentation API
Media routing of Web content will primarily be done through the Presentation API. Some media sinks (e.g. Cast) can render a subset of Web content natively, or render an equivalent app experience (e.g., via DIAL). For generic Web documents, we plan on rendering it in an offscreen WebContents and then using the Tab Mirroring approach outlined above. The design of the offscreen rendering capability will be added later to this document.
The Presentation API implementation in Blink will live in content/ and will operate on the frame level. It will delegate the calls to the embedder's Media Router implementation (Android Media Router / Chrome Media Router for Android / Chrome, respectively) via a common PresentationServiceDelegate interface. A draft Mojo interface follows (not yet complete):
PresentationService Mojo interface
Here is how the presentation API will roughly map to Chrome Media Router API:
Media Router Dialog
End user control of media routing is done through the Media Router Dialog. The media router dialog is a constrained, tab modal dialog implemented using WebUI. It auto-resizes to fit the currently rendered contents and appears in the top center of the browser. The dialog supports a number of views, including a screen selector, screen status, error/warning messages, and informational messages. To avoid excess whitespace, the dialog appropriately resizes to the current view.
The media router dialog is activated by clicking on the Cast icon, which is always available to the user. The Cast icon implements the action icon interface and appears on either the toolbar action menu (normally) or in the omnibox if there is an available Casting experience (a detected media sink).
[<img alt="image".
src="/developers/design-documents/media-router/media_router_overflow.jpg">](/developers/design-documents/media-router/media_router_overflow.jpg)
Clicking on the Cast icon brings up a menu of available media sinks that are compatible with the current content. For Web documents not using the Presentation API, these will include sinks that can render tab or desktop capture. For Web documents, it will include media sinks compatible with the URL requested to be presented through the Presentation API (once we are able to declare this URL through the API and proactively filter to compatible displays).
src="/developers/design-documents/media-router/media_router_screen_selector.jpg">](/developers/design-documents/media-router/media_router_screen_selector.jpg)
Media Route providers may customize the appearance of the active media
activity and inject custom controls into the WebUI (subject to UX guidelines). We are prototyping this approach using <extensionview>.
src="/developers/design-documents/media-router/media_router_universal_remote.jpg">](/developers/design-documents/media-router/media_router_universal_remote.jpg)
The Media Router Dialog Controller keeps track of whether or not the initiator tab is currently open. When the tab is closed or navigated away to another URL, the media router dialog is closed.
The html resources are built using custom polymer elements . data is passed between the webui and backend by calling the following:, webui: chrome.send(functionname);, backend: web_ui()->calljavascriptfunction(function_name, arg, ...);.
src="/developers/design-documents/media-router/media_router_ui_diagram.jpg">](/developers/design-documents/media-router/media_router_ui_diagram.jpg)
The WebUI and controller classes are located in the proposed location:
Chrome/browser/ui/webui/media_router, the dialog resources, which include html, css, js, and image files, are located in the proposed location:, chrome/browser/resources/media_router, we will use the <extensionview> html tag to embed the custom media controller ux. this will allow the component extension to flexibly customize and control the ux instead of having the functionality implemented directly into the browser. extensionview allows us to embed a page from the component extension into the media router webui. we will use the load api to take in the full media controller url..
The extension will utilize chrome.runtime.* functionality to message between the controller embedded in the ExtensionView and the extension itself.
Offscreen Rendering
The entire project should be security reviewed from a holistic and architectural perspective. Specific security-related aspects:
- The Chrome Media Router will be designed to have a minimal processing of the URIs and messages passed through it (perhaps only checking for syntactic validity).
- The Media Router Dialog will allow the MRPs to inject custom content into it, so for example, the inline controls for a game can differ from those for a movie. This content will be rendered out-of-process in an <extensionview> to prevent any escalation of privileges from compromised content.
- The individual platform APIs used by the component extension MRPs (chrome.dial, chrome.mdns, chrome.cast.channel, chrome.cast.streaming) have been security reviewed previously.
Team members
- Mark Foltz < [email protected] >, TL
- Jennifer Apacible < [email protected] >, WebUI
- Derek Cheng < [email protected] >, Media Router
- Haibin Lu < [email protected] >, Component extension
- Kevin Marshall < [email protected] >, Mojo integration
- Anton Vayvod < [email protected] >, Presentation API, Chrome for Android implementation
- Yuri Wittala < [email protected] >, Offscreen rendering
Code location
The patches to implement the Media Router have been developed in an internal repository. They will be upstreamed into mainline Chromium with the primary code location of
chrome/browser/media/router
for the media router, and other components living in appropriate locations according to their type.
Present web pages to secondary attached displays
Published on Thursday, April 5, 2018 • Updated on Thursday, April 25, 2019

Dives into Chromium source code
- Present a page
- Communicate with the page
- Samples and demos
- One more thing
- What's next
Chrome 66 allows web pages to use a secondary attached display through the Presentation API and to control its contents through the Presentation Receiver API .

# Background
Until now, web developers could build experiences where a user would see local content in Chrome that is different from the content they’d see on a remote display while still being able to control that experience locally. Examples include managing a playback queue on youtube.com while videos play on the TV, or seeing a slide reel with speaker notes on a laptop while the fullscreen presentation is shown in a Hangout session.
There are scenarios though where users may simply want to present content onto a second, attached display. For example, imagine a user in a conference room outfitted with a projector to which they are connected via an HDMI cable. Rather than mirroring the presentation onto a remote endpoint, the user really wants to present the slides full-screen on the projector , leaving the laptop screen available for speaker notes and slide control. While the site author could support this in a very rudimentary way (e.g. popping up a new window, which the user has to then manually drag to the secondary display and maximize to fullscreen), it is cumbersome and provides an inconsistent experience between local and remote presentation.
This change is about enabling secondary, attached displays to be used as endpoints for presentations in the same way as remote endpoints.

# Present a page
Let me walk you through how to use the Presentation API to present a web page on your secondary attached display. The end result is available at https://googlechrome.github.io/samples/presentation-api/ .
First, we’ll create a new PresentationRequest object that will contain the URL we want to present on the secondary attached display.
Showing a presentation display prompt requires a user gesture such as a click on a button. So let’s call presentationRequest.start() on a button click and wait for the promise to resolve once the user has selected a presentation display (.e.g. a secondary attached display in our use case).
The list presented to the user may also include remote endpoints such as Chromecast devices if you’re connected to a network advertising them. Note that mirrored displays are not in the list. See http://crbug.com/840466 .

When promise resolves, the web page at the PresentationRequest object URL is presented to the chosen display. Et voilà!
We can now go further and monitor "close" and "terminate" events as shown below. Note that it is possible to reconnect to a "closed" presentationConnection with presentationRequest.reconnect(presentationId) where presentationId is the ID of the previous presentationRequest object.
# Communicate with the page
Now you're thinking, that’s nice but how do I pass messages between my controller page (the one we’ve just created) and the receiver page (the one we’ve passed to the PresentationRequest object)?
First, let’s retrieve existing connections on the receiver page with navigator.presentation.receiver.connectionList and listen to incoming connections as shown below.
A connection receiving a message fires a "message" event you can listen for. The message can be a string, a Blob, an ArrayBuffer, or an ArrayBufferView. Sending it is as simple as calling connection.send(message) from the controller page or the receiver page.
Play with the sample at https://googlechrome.github.io/samples/presentation-api/ to get a sense of how it works. I’m sure you’ll enjoy this as much as I do.
# Samples and demos
Check out the official Chrome sample we've used for this article.
I recommend the interactive Photowall demo as well. This web app allows multiple controllers to collaboratively present a photo slideshow on a presentation display. Code is available at https://github.com/GoogleChromeLabs/presentation-api-samples .

# One more thing
Chrome has a "Cast" browser menu users can invoke at any time while visiting a website. If you want to control the default presentation for this menu, then assign navigator.presentation.defaultRequest to a custom presentationRequest object created earlier.
To inspect the receiver page and debug it, go to the internal chrome://inspect page, select “Other”, and click the “inspect” link next to the currently presented URL.

You may also want to check out the internal chrome://media-router-internals page for diving into the internal discovery/availability processes.
# What's next
As of Chrome 66, ChromeOS, Linux, and Windows platforms are supported. Mac support will come later .
# Resources
- Chrome Feature Status: https://www.chromestatus.com/features#presentation%20api
- Implementation Bugs: https://crbug.com/?q=component:Blink>PresentationAPI
- Presentation API Spec: https://w3c.github.io/presentation-api/
- Spec Issues: https://github.com/w3c/presentation-api/issues
Updated on Thursday, April 25, 2019 • Improve article
The HTML Presentation Framework
Created by Hakim El Hattab and contributors

Hello There
reveal.js enables you to create beautiful interactive slide decks using HTML. This presentation will show you examples of what it can do.
Vertical Slides
Slides can be nested inside of each other.
Use the Space key to navigate through all slides.

Basement Level 1
Nested slides are useful for adding additional detail underneath a high level horizontal slide.
Basement Level 2
That's it, time to go back up.

Not a coder? Not a problem. There's a fully-featured visual editor for authoring these, try it out at https://slides.com .
Pretty Code
Code syntax highlighting courtesy of highlight.js .
Even Prettier Animations
Point of view.
Press ESC to enter the slide overview.
Hold down the alt key ( ctrl in Linux) and click on any element to zoom towards it using zoom.js . Click again to zoom back out.
(NOTE: Use ctrl + click in Linux.)
Auto-Animate
Automatically animate matching elements across slides with Auto-Animate .
Touch Optimized
Presentations look great on touch devices, like mobile phones and tablets. Simply swipe through your slides.
Add the r-fit-text class to auto-size text
Hit the next arrow...
... to step through ...
... a fragmented slide.
Fragment Styles
There's different types of fragments, like:
fade-right, up, down, left
fade-in-then-out
fade-in-then-semi-out
Highlight red blue green
Transition Styles
You can select from different transitions, like: None - Fade - Slide - Convex - Concave - Zoom
Slide Backgrounds
Set data-background="#dddddd" on a slide to change the background color. All CSS color formats are supported.
Image Backgrounds
Tiled backgrounds, video backgrounds, ... and gifs, background transitions.
Different background transitions are available via the backgroundTransition option. This one's called "zoom".
You can override background transitions per-slide.
Iframe Backgrounds
Since reveal.js runs on the web, you can easily embed other web content. Try interacting with the page in the background.
Marvelous List
- No order here
Fantastic Ordered List
- One is smaller than...
- Two is smaller than...
Tabular Tables
Clever quotes.
These guys come in two forms, inline: The nice thing about standards is that there are so many to choose from and block:
“For years there has been a theory that millions of monkeys typing at random on millions of typewriters would reproduce the entire works of Shakespeare. The Internet has proven this theory to be untrue.”
Intergalactic Interconnections
You can link between slides internally, like this .
Speaker View
There's a speaker view . It includes a timer, preview of the upcoming slide as well as your speaker notes.
Press the S key to try it out.
Export to PDF
Presentations can be exported to PDF , here's an example:
Global State
Set data-state="something" on a slide and "something" will be added as a class to the document element when the slide is open. This lets you apply broader style changes, like switching the page background.
State Events
Additionally custom events can be triggered on a per slide basis by binding to the data-state name.
Take a Moment
Press B or . on your keyboard to pause the presentation. This is helpful when you're on stage and want to take distracting slides off the screen.
- Right-to-left support
- Extensive JavaScript API
- Auto-progression
- Parallax backgrounds
- Custom keyboard bindings
- Try the online editor - Source code & documentation
Create Stunning Presentations on the Web
reveal.js is an open source HTML presentation framework. It's a tool that enables anyone with a web browser to create fully-featured and beautiful presentations for free.
Presentations made with reveal.js are built on open web technologies. That means anything you can do on the web, you can do in your presentation. Change styles with CSS, include an external web page using an <iframe> or add your own custom behavior using our JavaScript API .
The framework comes with a broad range of features including nested slides , Markdown support , Auto-Animate , PDF export , speaker notes , LaTeX support and syntax highlighted code .
Ready to Get Started?
It only takes a minute to get set up. Learn how to create your first presentation in the installation instructions !
Online Editor
If you want the benefits of reveal.js without having to write HTML or Markdown try https://slides.com . It's a fully-featured visual editor and platform for reveal.js, by the same creator.
Supporting reveal.js
This project was started and is maintained by @hakimel with the help of many contributions from the community . The best way to support the project is to become a paying member of Slides.com —the reveal.js presentation platform that Hakim is building.

Slides.com — the reveal.js presentation editor.
Become a reveal.js pro in the official video course.
Presentation API 3.0
Status of this document.
This Version: 3.0.0
Latest Stable Version: 3.0.0
Previous Version: 2.1.1
Michael Appleby , Yale University
Tom Crane , Digirati
Robert Sanderson , J. Paul Getty Trust
Jon Stroop , Princeton University Library
Simeon Warner , Cornell University
Copyright © 2012-2023 Editors and contributors. Published by the IIIF Consortium under the CC-BY license, see disclaimer .
1. Introduction
Access to digital representations of objects is a fundamental requirement for many research activities, for the transmission of cultural knowledge, and for the daily pursuits of every web citizen. Ancient scrolls, paintings, letters, books, newspapers, films, operas, albums, field recordings, and computer generated animations are compound objects: they can have many parts, and complex structures. These resources may also bear the written or spoken word, and this linguistic content is often as important as the visual or audible representation.
Collections of both digitized physical objects and much born-digital content benefit from a standardized description of their structure, layout, and presentation mode. This document specifies this standardized description of the collection or compound object, using a JSON format. Many different rich and dynamic user experiences can be implemented, presenting content from across collections and institutions.
A compound object may comprise a series of pages, surfaces, or extents of time; for example the single view of a painting, the two sides of a photograph, four cardinal views of a statue, the many pages of an edition of a newspaper or book, or the duration of an act of an opera. This specification addresses how to provide an order for these views or extents, the references to the resources needed to present them, and the descriptive information needed to allow the user to understand what is being seen or heard.
The principles of Linked Data and the Architecture of the Web are adopted in order to provide a distributed and interoperable framework. The Shared Canvas data model and JSON-LD are leveraged to create an easy-to-implement, JSON -based format.
Please send feedback to [email protected]
1.1. Objectives and Scope
The objective of the IIIF (pronounced “Triple-Eye-Eff”) Presentation API is to provide the information necessary to allow a rich, online viewing environment for compound digital objects to be presented to a human user, often in conjunction with the IIIF Image API . This is the sole purpose of the API and therefore descriptive information is given in a way that is intended for humans to read, but not semantically available to machines. In particular, it explicitly does not aim to provide metadata that would allow a search engine to index digital objects.
Implementations of this specification will be able to:
- display to the user digitized images, video, audio, and other content types associated with a particular physical or born-digital object;
- allow the user to navigate between multiple views or time extents of the object, either sequentially or hierarchically;
- display descriptive information about the object, view or navigation structure to provide context to the user;
- and provide a shared environment in which both publishers and users can annotate the object and its content with additional information.
The following are not in scope:
- Provision of metadata for harvesting and discovery is not directly supported. Properties to reference further descriptive resources are available, and their use is encouraged.
- Search within the object, which is described by the IIIF Content Search API .
This document is accompanied by the Presentation API Cookbook , which demonstrates motivating use cases for IIIF and contains examples showing how the objectives may be achieved.
1.2. Terminology
This specification uses the following terms:
- embedded : When a resource (A) is embedded within an embedding resource (B), the complete JSON representation of resource A is present within the JSON representation of resource B, and dereferencing the URI of resource A will not result in additional information. Example: Canvas A is embedded in Manifest B.
- referenced : When a resource (A) is referenced from a referencing resource (B), an incomplete JSON representation of resource A is present within the JSON representation of resource B, and dereferencing the URI of resource A will result in additional information. Example: Manifest A is referenced from Collection B.
- HTTP (S) : The HTTP or HTTPS URI scheme and internet protocol.
The terms array , JSON object , number , string , and boolean in this document are to be interpreted as defined by the Javascript Object Notation ( JSON ) specification.
The key words must , must not , required , shall , shall not , should , should not , recommended , may , and optional in this document are to be interpreted as described in RFC 2119 .
2. Resource Type Overview
The objectives described above require a model in which one can characterize the compound object (via the Manifest resource) and the individual views of the object ( Canvas resources). Each view may reference images, audio, video and other content resources to allow it to be rendered appropriately. A compound object may also have sections; for example, a book may have chapters of several pages, or a play might be divided into acts and scenes ( Range resources) and there may be groups of such objects ( Collection resources). These resource types, along with their properties, make up the IIIF Presentation API .
This section provides an overview of the resource types (or classes) that are used in the specification. They are each presented in more detail in Section 5 .
2.1. Defined Types
This specification defines the following resource types:

An ordered list of Manifests, and/or further Collections. Collections allow Manifests and child Collections to be grouped in a hierarchical structure for presentation, which can be for generating navigation, showing dynamic results from a search, or providing fixed sets of related resources for any other purpose.
A description of the structure and properties of the compound object. It carries information needed for the client to present the content to the user, such as a title and other descriptive information about the object or the intellectual work that it conveys. Each Manifest usually describes how to present a single compound object such as a book, a statue or a music album.
A virtual container that represents a particular view of the object and has content resources associated with it or with parts of it. The Canvas provides a frame of reference for the layout of the content, both spatially and temporally. The concept of a Canvas is borrowed from standards like PDF and HTML , or applications like Photoshop and PowerPoint, where an initially blank display surface has images, video, text and other content “painted” on to it by Annotations, collected in Annotation Pages.
An ordered list of Canvases, and/or further Ranges. Ranges allow Canvases, or parts thereof, to be grouped together in some way. This could be for content-based reasons, such as might be described in a table of contents or the set of scenes in a play. Equally, physical features might be important such as page gatherings in an early book, or when recorded music is split across different physical carriers such as two CDs.
2.2. Additional Types
This specification makes use of types defined in the Web Annotation Data Model specification, in particular the following:
Annotation Page
An ordered list of Annotations that is typically associated with a Canvas but may be referenced from other types of resource as well. Annotation Pages collect and order lists of Annotations, which in turn provide commentary about a resource or content that is part of a Canvas.
Annotations associate content resources with Canvases. The same mechanism is used for the visible and/or audible resources as is used for transcriptions, commentary, tags and other content. This provides a single, unified method for aligning information, and provides a standards-based framework for distinguishing parts of resources and parts of Canvases. As Annotations can be added later, it promotes a distributed system in which publishers can align their content with the descriptions created by others. Annotation related functionality may also rely on further classes such as SpecificResource, Choice or Selectors.
Web resources such as images, audio, video, or text which are associated with a Canvas via an Annotation, or provide a representation of any resource.
Annotation Collection
An ordered list of Annotation Pages. Annotation Collections allow higher level groupings of Annotations to be recorded. For example, all of the English translation Annotations of a medieval French document could be kept separate from the transcription or an edition in modern French, or the director’s commentary on a film can be separated from the script.
3. Resource Properties
Most of the properties defined by this specification may be associated with any of the resource types described above, and may have more than one value. Properties relate to the resource with which they are associated, so the label property on a Manifest is the human readable label of the Manifest, whereas the same label property on a Canvas is the human readable label for that particular view.
The requirements for which classes have which properties are summarized in Appendix A .
Other properties are allowed, either via local extensions or those endorsed by the IIIF community. If a client discovers properties that it does not understand, then it must ignore them. See the Linked Data Context and Extensions section for more information about extensions.
This section also defines processing requirements for clients for each of the combinations of class and property. These requirements are for general purpose client implementations that are intended to be used to render the entire resource to the user, and not necessarily for consuming applications with specialized use or individual component implementations that might be used to construct a client. The inclusion of these requirements gives publishers a baseline expectation for how they can expect implementations advertised as compliant with this specification to behave when processing their content.
3.1. Descriptive Properties
These properties describe or represent the resource they are associated with, and are typically rendered to the user.
A human readable label, name or title. The label property is intended to be displayed as a short, textual surrogate for the resource if a human needs to make a distinction between it and similar resources, for example between objects, pages, or options for a choice of images to display. The label property can be fully internationalized, and each language can have multiple values. This pattern is described in more detail in the languages section.
The value of the property must be a JSON object, as described in the languages section.
- A Collection must have the label property with at least one entry. Clients must render label on a Collection.
- A Manifest must have the label property with at least one entry. Clients must render label on a Manifest.
- A Canvas should have the label property with at least one entry. Clients must render label on a Canvas, and should generate a label for Canvases that do not have them.
- A content resource may have the label property with at least one entry. If there is a Choice of content resource for the same Canvas, then they should each have at least the label property with at least one entry. Clients may render label on content resources, and should render them when part of a Choice.
- A Range should have the label property with at least one entry. Clients must render label on a Range.
- An Annotation Collection should have the label property with at least one entry. Clients should render label on an Annotation Collection.
- Other types of resource may have the label property with at least one entry. Clients may render label on other types of resource.
An ordered list of descriptions to be displayed to the user when they interact with the resource, given as pairs of human readable label and value entries. The content of these entries is intended for presentation only; descriptive semantics should not be inferred. An entry might be used to convey information about the creation of the object, a physical description, ownership information, or other purposes.
The value of the metadata property must be an array of JSON objects, where each item in the array has both label and value properties. The values of both label and value must be JSON objects, as described in the languages section.
- A Collection should have the metadata property with at least one item. Clients must render metadata on a Collection.
- A Manifest should have the metadata property with at least one item. Clients must render metadata on a Manifest.
- A Canvas may have the metadata property with at least one item. Clients should render metadata on a Canvas.
- Other types of resource may have the metadata property with at least one item. Clients may render metadata on other types of resource.
Clients should display the entries in the order provided. Clients should expect to encounter long texts in the value property, and render them appropriately, such as with an expand button, or in a tabbed interface.
A short textual summary intended to be conveyed to the user when the metadata entries for the resource are not being displayed. This could be used as a brief description for item level search results, for small-screen environments, or as an alternative user interface when the metadata property is not currently being rendered. The summary property follows the same pattern as the label property described above.
- A Collection should have the summary property with at least one entry. Clients should render summary on a Collection.
- A Manifest should have the summary property with at least one entry. Clients should render summary on a Manifest.
- A Canvas may have the summary property with at least one entry. Clients should render summary on a Canvas.
- Other types of resource may have the summary property with at least one entry. Clients may render summary on other types of resource.
requiredStatement
Text that must be displayed when the resource is displayed or used. For example, the requiredStatement property could be used to present copyright or ownership statements, an acknowledgement of the owning and/or publishing institution, or any other text that the publishing organization deems critical to display to the user. Given the wide variation of potential client user interfaces, it will not always be possible to display this statement to the user in the client’s initial state. If initially hidden, clients must make the method of revealing it as obvious as possible.
The value of the property must be a JSON object, that has the label and value properties, in the same way as a metadata property entry. The values of both label and value must be JSON objects, as described in the languages section.
- Any resource type may have the requiredStatement property. Clients must render requiredStatement on every resource type.
A string that identifies a license or rights statement that applies to the content of the resource, such as the JSON of a Manifest or the pixels of an image. The value must be drawn from the set of Creative Commons license URIs, the RightsStatements.org rights statement URIs, or those added via the extension mechanism. The inclusion of this property is informative, and for example could be used to display an icon representing the rights assertions.
If displaying rights information directly to the user is the desired interaction, or a publisher-defined label is needed, then it is recommended to include the information using the requiredStatement property or in the metadata property.
The value must be a string. If the value is drawn from Creative Commons or RightsStatements.org, then the string must be a URI defined by that specification.
- Any resource type may have the rights property. Clients may render rights on any resource type.
Machine actionable URIs and links for users The machine actionable URIs for both Creative Commons licenses and RightsStatements.org right statements are http URIs. In both cases, human readable descriptions are available from equivalent https URIs. Clients may wish to rewrite links presented to users to use these equivalent https URIs.
An organization or person that contributed to providing the content of the resource. Clients can then display this information to the user to acknowledge the provider’s contributions. This differs from the requiredStatement property, in that the data is structured, allowing the client to do more than just present text but instead have richer information about the people and organizations to use in different interfaces.
The organization or person is represented as an Agent resource.
- Agents must have the id property, and its value must be a string. The string must be a URI that identifies the agent.
- Agents must have the type property, and its value must be the string “Agent”.
- Agents must have the label property, and its value must be a JSON object as described in the languages section.
- Agents should have the homepage property, and its value must be an array of JSON objects as described in the homepage section.
- Agents should have the logo property, and its value must be an array of JSON objects as described in the logo section.
- Agents may have the seeAlso property, and its value must be an array of JSON object as described in the seeAlso section.
The value must be an array of JSON objects, where each item in the array conforms to the structure of an Agent, as described above.
- A Collection should have the provider property with at least one item. Clients must render provider on a Collection.
- A Manifest should have the provider property with at least one item. Clients must render provider on a Manifest.
- Other types of resource may have the provider property with at least one item. Clients should render provider on other types of resource.
A content resource, such as a small image or short audio clip, that represents the resource that has the thumbnail property. A resource may have multiple thumbnail resources that have the same or different type and format .
The value must be an array of JSON objects, each of which must have the id and type properties, and should have the format property. Images and videos should have the width and height properties, and time-based media should have the duration property. It is recommended that a IIIF Image API service be available for images to enable manipulations such as resizing.
- A Collection should have the thumbnail property with at least one item. Clients should render thumbnail on a Collection.
- A Manifest should have the thumbnail property with at least one item. Clients should render thumbnail on a Manifest.
- A Canvas may have the thumbnail property with at least one item. A Canvas should have the thumbnail property if there are multiple resources that make up the view. Clients should render thumbnail on a Canvas.
- A content resource may have the thumbnail property with at least one item. Content resources should have the thumbnail property with at least one item if it is an option in a Choice of resources. Clients should render thumbnail on a content resource.
- Other types of resource may have the thumbnail property with at least one item. Clients may render thumbnail on other types of resource.
A date that clients may use for navigation purposes when presenting the resource to the user in a date-based user interface, such as a calendar or timeline. More descriptive date ranges, intended for display directly to the user, should be included in the metadata property for human consumption. If the resource contains Canvases that have the duration property, the datetime given corresponds to the navigation datetime of the start of the resource. For example, a Range that includes a Canvas that represents a set of video content recording a historical event, the navDate is the datetime of the first moment of the recorded event.
The value must be an XSD dateTime literal . The value must have a timezone, and should be given in UTC with the Z timezone indicator, but may instead be given as an offset of the form +hh:mm .
- A Collection may have the navDate property. Clients may render navDate on a Collection.
- A Manifest may have the navDate property. Clients may render navDate on a Manifest.
- A Range may have the navDate property. Clients may render navDate on a Range.
- A Canvas may have the navDate property. Clients may render navDate on a Canvas.
- Other types of resource must not have the navDate property. Clients should ignore navDate on other types of resource.
placeholderCanvas
A single Canvas that provides additional content for use before the main content of the resource that has the placeholderCanvas property is rendered, or as an advertisement or stand-in for that content. Examples include images, text and sound standing in for video content before the user initiates playback; or a film poster to attract user attention. The content provided by placeholderCanvas differs from a thumbnail: a client might use thumbnail to summarize and navigate multiple resources, then show content from placeholderCanvas as part of the initial presentation of a single resource. A placeholder Canvas is likely to have different dimensions to those of the Canvas(es) of the resource that has the placeholderCanvas property.
Clients may display the content of a linked placeholder Canvas when presenting the resource. When more than one such Canvas is available, for example if placeholderCanvas is provided for the currently selected Range and the current Manifest, the client should pick the one most specific to the content. Publishers should not assume that the placeholder Canvas will be processed by all clients. Clients should take care to avoid conflicts between time-based media in the rendered placeholder Canvas and the content of the resource that has the placeholderCanvas property.
The value must be a JSON object with the id and type properties, and may have other properties of Canvases. The value of type must be the string Canvas . The object must not have the placeholderCanvas property, nor the accompanyingCanvas property.
- A Collection may have the placeholderCanvas property. Clients may render placeholderCanvas on a Collection.
- A Manifest may have the placeholderCanvas property. Clients may render placeholderCanvas on a Manifest.
- A Canvas may have the placeholderCanvas property. Clients may render placeholderCanvas on a Canvas.
- A Range may have the placeholderCanvas property. Clients may render placeholderCanvas on a Range.
- Other types of resource must not have the placeholderCanvas property. Clients should ignore placeholderCanvas on other types of resource.
accompanyingCanvas
A single Canvas that provides additional content for use while rendering the resource that has the accompanyingCanvas property. Examples include an image to show while a duration-only Canvas is playing audio; or background audio to play while a user is navigating an image-only Manifest.
Clients may display the content of an accompanying Canvas when presenting the resource. As with placeholderCanvas above, when more than one accompanying Canvas is available, the client should pick the one most specific to the content. Publishers should not assume that the accompanying Canvas will be processed by all clients. Clients should take care to avoid conflicts between time-based media in the accompanying Canvas and the content of the resource that has the accompanyingCanvas property.
- A Collection may have the accompanyingCanvas property. Clients may render accompanyingCanvas on a Collection.
- A Manifest may have the accompanyingCanvas property. Clients may render accompanyingCanvas on a Manifest.
- A Canvas may have the accompanyingCanvas property. Clients may render accompanyingCanvas on a Canvas.
- A Range may have the accompanyingCanvas property. Clients may render accompanyingCanvas on a Range.
- Other types of resource must not have the accompanyingCanvas property. Clients should ignore accompanyingCanvas on other types of resource.
3.2. Technical Properties
These properties describe technical features of the resources, and are typically processed by the client to understand how to render the resource.
The URI that identifies the resource. If the resource is only available embedded within another resource (see the terminology section for an explanation of “embedded”), such as a Range within a Manifest, then the URI may be the URI of the embedding resource with a unique fragment on the end. This is not true for Canvases, which must have their own URI without a fragment.
The value must be a string, and the value must be an HTTP (S) URI for resources defined in this specification. If the resource is retrievable via HTTP (S), then the URI must be the URI at which it is published. External resources, such as profiles, may have non- HTTP (S) URIs defined by other communities.
The existence of an HTTP (S) URI in the id property does not mean that the URI will always be dereferencable. If the resource with the id property is embedded , it may also be dereferenceable. If the resource is referenced (again, see the terminology section for an explanation of “referenced”), it must be dereferenceable. The definitions of the Resources give further guidance.
- All resource types must have the id property. Clients may render id on any resource type, and should render id on Collections, Manifests and Canvases.
The type or class of the resource. For classes defined for this specification, the value of type will be described in the sections below describing each individual class.
For content resources, the value of type is drawn from other specifications. Recommendations for common content types such as image, text or audio are given in the table below.
The JSON objects that appear in the value of the service property will have many different classes, and can be used to distinguish the sort of service, with specific properties defined in a registered context document .
The value must be a string.
- All resource types must have the type property. Clients must process, and may render, type on any resource type.
The specific media type (often called a MIME type) for a content resource, for example image/jpeg . This is important for distinguishing different formats of the same overall type of resource, such as distinguishing text in XML from plain text.
Note that this is different to the formats property in the Image API , which gives the extension to use within that API . It would be inappropriate to use in this case, as format can be used with any content resource, not just images.
The value must be a string, and it should be the value of the Content-Type header returned when the resource is dereferenced.
- A content resource should have the format property. Clients may render the format of any content resource.
- Other types of resource must not have the format property. Clients should ignore format on other types of resource.
The language or languages used in the content of this external resource. This property is already available from the Web Annotation model for content resources that are the body or target of an Annotation, however it may also be used for resources referenced from homepage , rendering , and partOf .
The value must be an array of strings. Each item in the array must be a valid language code, as described in the languages section .
- An external resource should have the language property with at least one item. Clients should process the language of external resources.
- Other types of resource must not have the language property. Clients should ignore language on other types of resource.
A schema or named set of functionality available from the resource. The profile can further clarify the type and/or format of an external resource or service, allowing clients to customize their handling of the resource that has the profile property.
The value must be a string, either taken from the profiles registry or a URI.
- Resources referenced by the seeAlso or service properties should have the profile property. Clients should process the profile of a service or external resource.
- Other types of resource may have the profile property. Clients may process the profile of other types of resource.
The height of the Canvas or external content resource. For content resources, the value is in pixels. For Canvases, the value does not have a unit. In combination with the width, it conveys an aspect ratio for the space in which content resources are located.
The value must be a positive integer.
- A Canvas may have the height property. If it has a height , it must also have a width . Clients must process height on a Canvas.
- Content resources should have the height property, with the value given in pixels, if appropriate to the resource type. Clients should process height on content resources.
- Other types of resource must not have the height property. Clients should ignore height on other types of resource.
The width of the Canvas or external content resource. For content resources, the value is in pixels. For Canvases, the value does not have a unit. In combination with the height, it conveys an aspect ratio for the space in which content resources are located.
- A Canvas may have the width property. If it has a width , it must also have a height . Clients must process width on a Canvas.
- Content resources should have the width property, with the value given in pixels, if appropriate to the resource type. Clients should process width on content resources.
- Other types of resource must not have the width property. Clients should ignore width on other types of resource.
The duration of the Canvas or external content resource, given in seconds.
The value must be a positive floating point number.
- A Canvas may have the duration property. Clients must process duration on a Canvas.
- Content resources should have the duration property, if appropriate to the resource type. Clients should process duration on content resources.
- Other types of resource must not have a duration . Clients should ignore duration on other types of resource.
viewingDirection
The direction in which a set of Canvases should be displayed to the user. This specification defines four direction values in the table below. Others may be defined externally as an extension .
- A Collection may have the viewingDirection property. Clients should process viewingDirection on a Collection.
- A Manifest may have the viewingDirection property. Clients should process viewingDirection on a Manifest.
- A Range may have the viewingDirection property. Clients may process viewingDirection on a Range.
- Other types of resource must not have the viewingDirection property. Clients should ignore viewingDirection on other types of resource.
A set of user experience features that the publisher of the content would prefer the client to use when presenting the resource. This specification defines the values in the table below. Others may be defined externally as an extension .
In order to determine the behaviors that are governing a particular resource, there are four inheritance rules from resources that reference the current resource:
- Collections inherit behaviors from their referencing Collection.
- Manifests DO NOT inherit behaviors from any referencing Collections.
- Canvases inherit behaviors from their referencing Manifest, but DO NOT inherit behaviors from any referencing Ranges, as there might be several with different behaviors.
- Ranges inherit behaviors from any referencing Range and referencing Manifest.
Clients should interpret behaviors on a Range only when that Range is selected or is in some other way the context for the user’s current interaction with the resources. A Range with the behavior value continuous , in a Manifest with the behavior value paged , would mean that the Manifest’s Canvases should be rendered in a paged fashion, unless the range is selected to be viewed, and its included Canvases would be rendered in that context only as being virtually stitched together. This might occur, for example, when a physical scroll is cut into pages and bound into a codex with other pages, and the publisher would like to provide the user the experience of the scroll in its original form.
The descriptions of the behavior values have a set of which other values they are disjoint with, meaning that the same resource must not have both of two or more from that set. In order to determine which is in effect, the client should follow the inheritance rules above, taking the value from the closest resource. The user interface effects of the possible permutations of non-disjoint behavior values are client dependent, and implementers are advised to look for relevant recipes in the IIIF cookbook .
Future Clarification Anticipated Further clarifications about the implications of interactions between behavior values should be expected in subsequent minor releases.
The value must be an array of strings.
- Any resource type may have the behavior property with at least one item. Clients should process behavior on any resource type.
A mode associated with an Annotation that is to be applied to the rendering of any time-based media, or otherwise could be considered to have a duration, used as a body resource of that Annotation. Note that the association of timeMode with the Annotation means that different resources in the body cannot have different values. This specification defines the values specified in the table below. Others may be defined externally as an extension .
- An Annotation may have the timeMode property. Clients should process timeMode on an Annotation.
3.3. Linking Properties
These properties are references or links between resources, and split into external references where the linked object is outside of the IIIF space, and internal references where the linked object is a IIIF resource. Clients typically create a link to the resource that is able to be activated by the user, or interact directly with the linked resource to improve the user’s experience.
3.3.1. External Links
A web page that is about the object represented by the resource that has the homepage property. The web page is usually published by the organization responsible for the object, and might be generated by a content management system or other cataloging system. The resource must be able to be displayed directly to the user. Resources that are related, but not home pages, must instead be added into the metadata property, with an appropriate label or value to describe the relationship.
The value of this property must be an array of JSON objects, each of which must have the id , type , and label properties, should have a format property, and may have the language property.
- Any resource type may have the homepage property. Clients should render homepage on a Collection, Manifest or Canvas, and may render homepage on other types of resource.
Model Alignment Please note that this specification has stricter requirements about the JSON pattern used for the homepage property than the Web Annotation Data Model . The IIIF requirements are compatible, but the home page of an Agent found might have only a URI, or might be a JSON object with other properties. See the section on collisions between contexts for more information.
A small image resource that represents the Agent resource it is associated with. The logo must be clearly rendered when the resource is displayed or used, without cropping, rotating or otherwise distorting the image. It is recommended that a IIIF Image API service be available for this image for other manipulations such as resizing.
When more than one logo is present, the client should pick only one of them, based on the information in the logo properties. For example, the client could select a logo of appropriate aspect ratio based on the height and width properties of the available logos. The client may decide on the logo by inspecting properties defined as extensions .
The value of this property must be an array of JSON objects, each of which must have id and type properties, and should have format . The value of type must be “Image”.
- Agent resources should have the logo property. Clients must render logo on Agent resources.
A resource that is an alternative, non- IIIF representation of the resource that has the rendering property. Such representations typically cannot be painted onto a single Canvas, as they either include too many views, have incompatible dimensions, or are compound resources requiring additional rendering functionality. The rendering resource must be able to be displayed directly to a human user, although the presentation may be outside of the IIIF client. The resource must not have a splash page or other interstitial resource that mediates access to it. If access control is required, then the IIIF Authentication API is recommended . Examples include a rendering of a book as a PDF or EPUB, a slide deck with images of a building, or a 3D model of a statue.
The value must be an array of JSON objects. Each item must have the id , type and label properties, and should have a format property.
- Any resource type may have the rendering property with at least one item. Clients should render rendering on a Collection, Manifest or Canvas, and may render rendering on other types of resource.
A service that the client might interact with directly and gain additional information or functionality for using the resource that has the service property, such as from an Image to the base URI of an associated IIIF Image API service. The service resource should have additional information associated with it in order to allow the client to determine how to make appropriate use of it. Please see the Service Registry document for the details of currently known service types.
The value must be an array of JSON objects. Each object will have properties depending on the service’s definition, but must have either the id or @id and type or @type properties. Each object should have a profile property.
- Any resource type may have the service property with at least one item. Clients may process service on any resource type, and should process the IIIF Image API service.
For cross-version consistency, this specification defines the following values for the type or @type property for backwards compatibility with other IIIF APIs. Future versions of these APIs will define their own types. These type values are necessary extensions for compatibility of the older versions.
Implementations should be prepared to recognize the @id and @type property names used by older specifications, as well as id and type . Note that the @context key should not be present within the service , but instead included at the beginning of the document. The example below includes both version 2 and version 3 IIIF Image API services.
A list of one or more service definitions on the top-most resource of the document, that are typically shared by more than one subsequent resource. This allows for these shared services to be collected together in a single place, rather than either having their information duplicated potentially many times throughout the document, or requiring a consuming client to traverse the entire document structure to find the information. The resource that the service applies to must still have the service property, as described above, where the service resources have at least the id and type or @id and @type properties. This allows the client to know that the service applies to that resource. Usage of the services property is at the discretion of the publishing system.
A client encountering a service property where the definition consists only of an id and type should then check the services property on the top-most resource for an expanded definition. If the service is not present in the services list, and the client requires more information in order to use the service, then it should dereference the id (or @id ) of the service in order to retrieve a service description.
The value must be an array of JSON objects. Each object must a service resource, as described above.
- A Collection may have the services property, if it is the topmost Collection in a response document. Clients should process services on a Collection.
- A Manifest may have the services property. Clients should process services on a Manifest.
A machine-readable resource such as an XML or RDF description that is related to the current resource that has the seeAlso property. Properties of the resource should be given to help the client select between multiple descriptions (if provided), and to make appropriate use of the document. If the relationship between the resource and the document needs to be more specific, then the document should include that relationship rather than the IIIF resource. Other IIIF resources are also valid targets for seeAlso , for example to link to a Manifest that describes a related object. The URI of the document must identify a single representation of the data in a particular format. For example, if the same data exists in JSON and XML , then separate resources should be added for each representation, with distinct id and format properties.
The value must be an array of JSON objects. Each item must have the id and type properties, and should have the label , format and profile properties.
- Any resource type may have the seeAlso property with at least one item. Clients may process seeAlso on any resource type.
3.3.2. Internal Links
A containing resource that includes the resource that has the partOf property. When a client encounters the partOf property, it might retrieve the referenced containing resource, if it is not embedded in the current representation, in order to contribute to the processing of the contained resource. For example, the partOf property on a Canvas can be used to reference an external Manifest in order to enable the discovery of further relevant information. Similarly, a Manifest can reference a containing Collection using partOf to aid in navigation.
The value must be an array of JSON objects. Each item must have the id and type properties, and should have the label property.
- Any resource type may have the partOf property with at least one item Clients may render partOf on any resource type.
A Canvas, or part of a Canvas, which the client should show on initialization for the resource that has the start property. The reference to part of a Canvas is handled in the same way that Ranges reference parts of Canvases. This property allows the client to begin with the first Canvas that contains interesting content rather than requiring the user to manually navigate to find it.
The value must be a JSON object, which must have the id and type properties. The object must be either a Canvas (as in the first example below), or a Specific Resource with a Selector and a source property where the value is a Canvas (as in the second example below).
- A Manifest may have the start property. Clients should process start on a Manifest.
- A Range may have the start property. Clients should process start on a Range.
- Other types of resource must not have the start property. Clients should ignore start on other types of resource.
supplementary
A link from this Range to an Annotation Collection that includes the supplementing Annotations of content resources for the Range. Clients might use this to present additional content to the user from a different Canvas when interacting with the Range, or to jump to the next part of the Range within the same Canvas. For example, the Range might represent a newspaper article that spans non-sequential pages, and then uses the supplementary property to reference an Annotation Collection that consists of the Annotations that record the text, split into Annotation Pages per newspaper page. Alternatively, the Range might represent the parts of a manuscript that have been transcribed or translated, when there are other parts that have yet to be worked on. The Annotation Collection would be the Annotations that transcribe or translate, respectively.
The value must be a JSON object, which must have the id and type properties, and the type must be AnnotationCollection .
- A Range may have the supplementary property. Clients may process supplementary on a Range.
- Other types of resource must not have the supplementary property. Clients should ignore supplementary on other types of resource.
3.4. Structural Properties
These properties define the structure of the object being represented in IIIF by allowing the inclusion of child resources within parents, such as a Canvas within a Manifest, or a Manifest within a Collection. The majority of cases use items , however there are two special cases for different sorts of structures.
Much of the functionality of the IIIF Presentation API is simply recording the order in which child resources occur within a parent resource, such as Collections or Manifests within a parent Collection, or Canvases within a Manifest. All of these situations are covered with a single property, items .
The value must be an array of JSON objects. Each item must have the id and type properties. The items will be resources of different types, as described below.
- A Collection must have the items property. Each item must be either a Collection or a Manifest. Clients must process items on a Collection.
- A Manifest must have the items property with at least one item. Each item must be a Canvas. Clients must process items on a Manifest.
- A Canvas should have the items property with at least one item. Each item must be an Annotation Page. Clients must process items on a Canvas.
- An Annotation Page should have the items property with at least one item. Each item must be an Annotation. Clients must process items on an Annotation Page.
- A Range must have the items property with at least one item. Each item must be a Range, a Canvas or a Specific Resource where the source is a Canvas. Clients should process items on a Range.
- Other types of resource must not have the items property. Clients should ignore items on other types of resource.
The structure of an object represented as a Manifest can be described using a hierarchy of Ranges. Ranges can be used to describe the “table of contents” of the object or other structures that the user can interact with beyond the order given by the items property of the Manifest. The hierarchy is built by nesting the child Range resources in the items array of the higher level Range. The top level Ranges of these hierarchies are given in the structures property.
The value must be an array of JSON objects. Each item must have the id and type properties, and the type must be Range .
- A Manifest may have the structures property. Clients should process structures on a Manifest. The first hierarchy should be presented to the user by default, and further hierarchies should be able to be selected as alternative structures by the user.
- Other types of resource must not have the structures property. Clients should ignore structures on other types of resource.
annotations
An ordered list of Annotation Pages that contain commentary or other Annotations about this resource, separate from the Annotations that are used to paint content on to a Canvas. The motivation of the Annotations must not be painting , and the target of the Annotations must include this resource or part of it.
The value must be an array of JSON objects. Each item must have at least the id and type properties.
- A Collection may have the annotations property with at least one item. Clients should process annotations on a Collection.
- A Manifest may have the annotations property with at least one item. Clients should process annotations on a Manifest,.
- A Canvas may have the annotations property with at least one item. Clients should process annotations on a Canvas.
- A Range may have the annotations property with at least one item. Clients should process annotations on a Range.
- A content resource may have the annotations property with at least one item. Clients should process annotations on a content resource.
- Other types of resource must not have the annotations property. Clients should ignore annotations on other types of resource.
3.5. Values
Values for motivation.
This specification defines two values for the Web Annotation property of motivation , or purpose when used on a Specific Resource or Textual Body.
While any resource may be the target of an Annotation, this specification defines only motivations for Annotations that target Canvases. These motivations allow clients to determine how the Annotation should be rendered, by distinguishing between Annotations that provide the content of the Canvas, from ones with externally defined motivations which are typically comments about the Canvas.
Additional motivations may be added to the Annotation to further clarify the intent, drawn from extensions or other sources. Clients must ignore motivation values that they do not understand. Other motivation values given in the Web Annotation specification should be used where appropriate, and examples are given in the Presentation API Cookbook .
4. JSON-LD Considerations
This section describes features applicable to all of the Presentation API content. For the most part, these are features of the JSON-LD specification that have particular uses within the API .
4.1. Case Sensitivity
Terms in JSON-LD are case sensitive . The cases of properties and enumerated values in IIIF Presentation API responses must match those used in this specification. For example to specify that a resource is a Manifest, the property must be given as type and not Type or tYpE , and the value must be given as Manifest and not manifest or manIfEsT .
4.2. Resource Representations
Resource descriptions should be embedded within the JSON description of parent resources, and may also be available via separate requests from the HTTP (S) URI given in the resource’s id property. Links to resources must be given as a JSON object with the id and type properties and should have format or profile to give a hint as to what sort of resource is being referred to.
4.3. Properties with Multiple Values
Any of the properties in the API that can have multiple values must always be given as an array of values, even if there is only a single item in that array.
4.4. Language of Property Values
Language may be associated with strings that are intended to be displayed to the user for the label and summary properties, plus the label and value properties of the metadata and requiredStatement objects.
The values of these properties must be JSON objects, with the keys being the BCP 47 language code for the language, or if the language is either not known or the string does not have a language, then the key must be the string none . The associated values must be arrays of strings, where each item is the content in the given language.
Note that BCP 47 allows the script of the text to be included after a hyphen, such as ar-latn , and clients should be aware of this possibility.
In the case where multiple values are supplied, clients must use the following algorithm to determine which values to display to the user.
- If all of the values are associated with the none key, the client must display all of those values.
- If any of the values have a language associated with them, the client must display all of the values associated with the language that best matches the language preference.
- If all of the values have a language associated with them, and none match the language preference, the client must select a language and display all of the values associated with that language.
- If some of the values have a language associated with them, but none match the language preference, the client must display all of the values that do not have a language associated with them.
Note that this does not apply to embedded textual bodies in Annotations, which use the Web Annotation pattern of value and language as separate properties.
4.5. HTML Markup in Property Values
Minimal HTML markup may be included for processing in the summary property and the value property in the metadata and requiredStatement objects. It must not be used in label or other properties. This is included to allow content publishers to add links and simple formatting instructions to blocks of text. The content must be well-formed XML and therefore must be wrapped in an element such as p or span . There must not be whitespace on either side of the HTML string, and thus the first character in the string must be a ‘<’ character and the last character must be ‘>’, allowing a consuming application to test whether the value is HTML or plain text using these. To avoid a non- HTML string matching this, it is recommended that an additional whitespace character be added to the end of the value in situations where plain text happens to start and end this way.
In order to avoid HTML or script injection attacks, clients must remove:
- Tags such as script , style , object , form , input and similar.
- All attributes other than href on the a tag, src and alt on the img tag.
- All href attributes that start with the strings other than “http:”, “https:”, and “mailto:”.
- CData sections.
- XML Comments.
- Processing instructions.
Clients should allow only a , b , br , i , img , p , small , span , sub and sup tags. Clients may choose to remove any and all tags, therefore it should not be assumed that the formatting will always be rendered. Note that publishers may include arbitrary HTML content for processing using customized or experimental applications, and the requirements for clients assume an untrusted or unknown publisher.
4.6. Linked Data Context and Extensions
The top level resource in the response must have the @context property, and it should appear as the very first key/value pair of the JSON representation. This tells Linked Data processors how to interpret the document. The IIIF Presentation API context, below, must occur once per response in the top-most resource, and thus must not appear within embedded resources. For example, when embedding a Canvas within a Manifest, the Canvas will not have the @context property.
The value of the @context property must be either the URI http://iiif.io/api/presentation/3/context.json or a JSON array with the URI http://iiif.io/api/presentation/3/context.json as the last item. Further contexts, such as those for local or registered extensions , must be added at the beginning of the array.
Any additional properties beyond those defined in this specification or the Web Annotation Data Model should be mapped to RDF predicates using further context documents. These extensions should be added to the top level @context property, and must be added before the above context. The JSON-LD 1.1 functionality of predicate specific context definitions, known as scoped contexts , must be used to minimize cross-extension collisions. Extensions intended for community use should be registered in the extensions registry , but registration is not mandatory.
The JSON representation must not include the @graph key at the top level. This key might be created when serializing directly from RDF data using the JSON-LD 1.0 compaction algorithm. Instead, JSON-LD framing and/or custom code should be used to ensure the structure of the document is as defined by this specification.
4.7. Term Collisions between Contexts
There are some common terms used in more than one JSON-LD context document. Every attempt has been made to minimize these collisions, but some are inevitable. In order to know which specification is in effect at any given point, the class of the resource that has the property is the primary governing factor. Thus properties on Annotation based resources use the context from the Web Annotation Data Model , whereas properties on classes defined by this specification use the IIIF Presentation API context’s definition.
There is one property that is in direct conflict - the label property is defined by both and is available for every resource. The use of label in IIIF follows modern best practices for internationalization by allowing the language to be associated with the value using the language map construction described above . The Web Annotation Data Model uses it only for Annotation Collections , and mandates the format is a string. For this property, the API overrides the definition from the Annotation model to ensure that labels can consistently be represented in multiple languages.
The following properties are defined by both, and the IIIF representation is more specific than the Web Annotation Data Model but are not in conflict, or are never used on the same resource:
- homepage : In IIIF the home page of a resource is represented as a JSON object, whereas in the Web Annotation Data Model it can also be a string.
- type : In IIIF the type is singular, whereas in the Web Annotation Data Model there can be more than one type.
- format : In IIIF the format of a resource is also singular, whereas in the Web Annotation Data Model there can be more than one format.
- language : In IIIF the language property always takes an array, whereas in the Web Annotation Data Model it can be a single string.
- start : The start property is used on a Manifest to refer to the start Canvas or part of a Canvas and thus is a JSON object, whereas in the Web Annotation Data Model it is used on a TextPositionSelector to give the start offset into the textual content and is thus an integer.
The rights , partOf , and items properties are defined by both in the same way.
4.8. Keyword Mappings
The JSON-LD keywords @id , @type and @none are mapped to id , type and none by the Presentation API linked data context . Thus in content conforming to this version of the Presentation API , the only JSON key beginning with @ will be @context . However, the content may include data conforming to older specifications or external specifications that use keywords beginning with @ . Clients should expect to encounter both syntaxes.
5. Resource Structure
This section provides detailed description of the resource types used in this specification. Section 2 provides an overview of the resource types and figures illustrating allowed relationships between them, and Appendix A provides summary tables of the property requirements.
5.1. Collection
Collections are used to list the Manifests available for viewing. Collections may include both other Collections and Manifests, in order to form a tree-structured hierarchy. Collections might align with the curated management of cultural heritage resources in sets, also called “collections”, but may have absolutely no such similarity.
The intended usage of Collections is to allow clients to:
- Load a pre-defined set of Manifests at initialization time.
- Receive a set of Manifests, such as search results, for rendering.
- Visualize lists or hierarchies of related Manifests.
- Provide navigation through a list or hierarchy of available Manifests.
Collections may be embedded inline within other Collections, such as when the Collection is used primarily to subdivide a larger one into more manageable pieces, however Manifests must not be embedded within Collections. An embedded Collection should also have its own URI from which the JSON description is available.
Manifests or Collections may be referenced from more than one Collection. For example, an institution might define four Collections: one for modern works, one for historical works, one for newspapers and one for books. The Manifest for a modern newspaper would then appear in both the modern Collection and the newspaper Collection. Alternatively, the institution may choose to have two separate newspaper Collections, and reference each as a sub-Collection of modern and historical.
Collections with an empty items property are allowed but discouraged. For example, if the user performs a search that matches no Manifests, then the server may return a Collection response with no Manifests.
Collections or Manifests referenced in the items property must have the id , type and label properties. They should have the thumbnail property.
An example Collection document:
Note that while the Collection may reference Collections or Manifests from previous versions of the API , the information included in this document must follow the current version requirements, not the requirements of the target document. This is in contrast to the requirements of service , as there is no way to distinguish a version 2 Manifest from a version 3 Manifest by its type .
5.2. Manifest
The Manifest resource typically represents a single object and any intellectual work or works embodied within that object. In particular it includes descriptive, rights and linking information for the object. The Manifest embeds the Canvases that should be rendered as views of the object and contains sufficient information for the client to initialize itself and begin to display something quickly to the user.
The identifier in id must be able to be dereferenced to retrieve the JSON description of the Manifest, and thus must use the HTTP (S) URI scheme.
The Manifest must have an items property, which is an array of JSON-LD objects. Each object is a Canvas, with requirements as described in the next section. The Manifest may also have a structures property listing one or more Ranges which describe additional structure of the content, such as might be rendered as a table of contents. The Manifest may have an annotations property, which includes Annotation Page resources where the Annotations have the Manifest as their target . These will typically be comment style Annotations, and must not have painting as their motivation .
5.3. Canvas
The Canvas represents an individual page or view and acts as a central point for assembling the different content resources that make up the display. Canvases must be identified by a URI and it must be an HTTP (S) URI. The URI of the canvas must not contain a fragment (a # followed by further characters), as this would make it impossible to refer to a segment of the Canvas’s area using the media fragment syntax of #xywh= for spatial regions, and/or #t= for temporal segments. Canvases may be able to be dereferenced separately from the Manifest via their URIs as well as being embedded .
Every Canvas should have a label to display. If one is not provided, the client should automatically generate one for use based on the Canvas’s position within the items property.
Content resources are associated with the Canvas via Web Annotations. Content that is to be rendered as part of the Canvas must be associated by an Annotation that has the motivation value painting . These Annotations are recorded in the items of one or more Annotation Pages, referred to in the items array of the Canvas. Annotations that do not have the motivation value painting must not be in pages referenced in items , but instead in the annotations property. Referenced, external Annotation Pages must have the id and type properties.
Content that is derived from the Canvas, such as a manual or automatic (OCR) transcription of text in an image or the words spoken in an audio representation, must be associated by an Annotation that has the motivation value supplementing . Annotations may have any other motivation values as well. Thus, content of any type may be associated with the Canvas via an Annotation that has the motivation value painting , meaning the content is part of the Canvas; an Annotation that has the motivation value supplementing , meaning the content is from the Canvas but not necessarily part of it; or an Annotation with another motivation meaning that it is somehow about the Canvas.
A Canvas must have a rectangular aspect ratio (described with the height and width properties) and/or a duration to provide an extent in time. These dimensions allow resources to be associated with specific regions of the Canvas, within the space and/or time extents provided. Content must not be associated with space or time outside of the Canvas’s dimensions, such as at coordinates below 0,0, greater than the height or width, before 0 seconds, or after the duration. Content resources that have dimensions which are not defined for the Canvas must not be associated with that Canvas by an Annotation that has the motivation value painting . For example, it is valid to use an Annotation that has the motivation value painting to associate an Image (which has only height and width) with a Canvas that has all three dimensions, but it is an error to associate a Video resource (which has height, width and duration) with a Canvas that does not have all three dimensions. Such a resource should instead be referenced using the rendering property, or by Annotations that have a motivation value other than painting in the annotations property.
Parts of Canvases may be described using a Specific Resource with a Selector, following the patterns defined in the Web Annotation data model. The use of the FragmentSelector class is recommended by that specification, as it allows for refinement by other Selectors and for consistency with use cases that cannot be represented using a URI fragment directly. Parts of Canvases can be referenced from Ranges, as the body or target of Annotations, or in the start property.
Parts of Canvases may also be identified by appending a fragment to the Canvas’s URI, and these parts are still considered to be Canvases: their type value is the string Canvas . Rectangular spatial parts of Canvases may also be described by appending an xywh= fragment to the end of the Canvas’s URI. Similarly, temporal parts of Canvases may be described by appending a t= fragment to the end of the Canvas’s URI. Spatial and temporal fragments may be combined, using an & character between them, and the temporal dimension should come first. It is an error to select a region using a dimension that is not defined by the Canvas, such as a temporal region of a Canvas that only has height and width dimensions.
Canvases may be treated as content resources for the purposes of annotating on to other Canvases. For example, a Canvas (Canvas A) with a video resource and Annotations representing subtitles or captions may be annotated on to another Canvas (Canvas B). This pattern maintains the correct spatial and temporal alignment of Canvas A’s content relative to Canvas B’s dimensions.
Renderers must scale content into the space represented by the Canvas, and should follow any timeMode value provided for time-based media. If the Canvas represents a view of a physical object, the spatial dimensions of the Canvas should be the same scale as that physical object, and content should represent only the object.
Ranges are used to represent structure within an object beyond the default order of the Canvases in the items property of the Manifest, such as newspaper sections or articles, chapters within a book, or movements within a piece of music. Ranges can include Canvases, parts of Canvases, or other Ranges, creating a tree structure like a table of contents.
The intent of adding a Range to the Manifest is to allow the client to display a linear or hierarchical navigation interface to enable the user to quickly move through the object’s content. Clients should present only Ranges that have the label property and do not have a behavior value no-nav to the user. Clients should not render Canvas labels as part of the navigation, and a Range that wraps the Canvas must be created if this is the desired presentation.
If there is no Range that has the behavior value sequence , and the Manifest does not have the behavior value unordered , then the client should treat the order of the Canvases in the Manifest’s items array as the default order. If there is one Range that has the behavior value sequence , then the client must instead use this Range for the ordering. If there is more than one Range that has the behavior value sequence , for example a second Range to represent an alternative ordering of the pages of a manuscript, the first Range should be used as the default and the others should be able to be selected. Ranges that have the behavior value sequence must be directly within the structures property of the Manifest, and must not be embedded or referenced within other Ranges. These Ranges may have limited hierarchical nesting, but clients are not expected to traverse very deep structures in determining the default order. If this Range includes parts of Canvases, then these parts are the content to render by default and would generate separate entries in a navigation display. This allows for the Canvas to include content outside of the default view, such as a color bar or ruler.
Ranges must have URIs and they should be HTTP (S) URIs. Top level Ranges are embedded or externally referenced within the Manifest in a structures property. These top level Ranges then embed or reference other Ranges, Canvases or parts of Canvases in the items property. Each entry in the items property must be a JSON object, and it must have the id and type properties. If a top level Range needs to be dereferenced by the client, then it must not have the items property, such that clients are able to recognize that it should be retrieved in order to be processed.
All of the Canvases or parts that should be considered as being part of a Range must be included within the Range’s items property, or a descendant Range’s items .
The Canvases and parts of Canvases need not be contiguous or in the same order as in the Manifest’s items property or any other Range. Examples include newspaper articles that are continued in different sections, a chapter that starts half way through a page, or time segments of a single canvas that represent different sections of a piece of music.
Ranges may link to an Annotation Collection that has the content of the Range using the supplementary property. The referenced Annotation Collection will contain Annotations that target areas of Canvases within the Range and link content resources to those Canvases.
5.5. Annotation Page
Association of Images and other content with their respective Canvases is done via Annotations. Traditionally Annotations are used for associating commentary with the resource the Annotation’s text or body is about, the Web Annotation model allows any resource to be associated with any other resource, or parts thereof, and it is reused for both commentary and painting resources on the Canvas. Other resources beyond images might include the full text of the object, musical notations, musical performances, diagram transcriptions, commentary Annotations, tags, video, data and more.
These Annotations are collected together in Annotation Page resources, which are included in the items property from the Canvas. Each Annotation Page can be embedded in its entirety, if the Annotations should be processed as soon as possible when the user navigates to that Canvas, or a reference to an external page. This reference must include id and type , must not include items and may include other properties, such as behavior . All of the Annotations in the Annotation Page should have the Canvas as their target . Clients should process the Annotation Pages and their items in the order given in the Canvas. Publishers may choose to expedite the processing of embedded Annotation Pages by ordering them before external pages, which will need to be dereferenced by the client.
An Annotation Page must have an HTTP (S) URI given in id , and may have any of the other properties defined in this specification or the Web Annotation specification. The Annotations are listed in the items property of the Annotation Page.
Incompatibility Warning The definition of label in the Web Annotation specification does not produce JSON conformant with the structure defined in this specification for languages. Given the absolute requirement for internationalized labels and the strong desire for consistently handling properties, the label property on Annotation model classes does not conform to the string requirement of the Web Annotation Data Model. This issue has been filed with the W3C and will hopefully be addressed in a future version of the standard.
5.6. Annotation
Annotations follow the Web Annotation data model. The description provided here is a summary plus any IIIF specific requirements. The W3C standard is the official documentation.
Annotations must have their own HTTP (S) URIs, conveyed in the id property. The JSON-LD description of the Annotation should be returned if the URI is dereferenced, according to the Web Annotation Protocol .
When Annotations are used to associate content resources with a Canvas, the content resource is linked in the body of the Annotation. The URI of the Canvas must be repeated in the target property of the Annotation, or the source property of a Specific Resource used in the target property.
Note that the Web Annotation data model defines different patterns for the value property, when used within an Annotation. The value of a Textual Body or a Fragment Selector, for example, are strings rather than JSON objects with languages and values. Care must be taken to use the correct string form in these cases.
Additional features of the Web Annotation data model may also be used, such as selecting a segment of the Canvas or content resource, or embedding the comment or transcription within the Annotation. The use of these advanced features sometimes results in situations where the target is not a content resource, but instead a SpecificResource, a Choice, or other non-content object. Implementations should check the type of the resource and not assume that it is always content to be rendered.
The IIIF community has defined additional Selector classes for use with SpecificResources, especially for cases when it is not possible to use the official FragmentSelector. See the additional documentation for details.
5.7. Content Resources
Content resources are external web resources that are referenced from within the Manifest or Collection. This includes images, video, audio, data, web pages or any other format.
As described in the Canvas section, the content associated with a Canvas (and therefore the content of a Manifest) is provided by the body property of Annotations with the painting motivation. Content resources can also be referenced from thumbnail , homepage , logo , rendering , and seeAlso properties.
Content resources must have an id property, with the value being the URI at which the resource can be obtained.
The type of the content resource must be included, and should be taken from the table listed under the definition of type . The format of the resource should be included and, if so, should be the media type that is returned when the resource is dereferenced. The profile of the resource, if it has one, should also be included. Content resources in appropriate formats may also have the language , height , width , and duration properties. Content resources may also have descriptive and linking properties, as defined in section 3 .
If the content resource is an Image, and a IIIF Image service is available for it, then the id property of the content resource may be a complete URI to any particular representation supported by the Image Service, such as https://example.org/image1/full/1000,/0/default.jpg , but must not be just the URI of the IIIF Image service. Its type value must be the string Image . Its media type may be listed in format , and its height and width may be given as integer values for height and width respectively. The Image should have the service referenced from it using the service property.
If there is a need to distinguish between content resources, then the resource should have the label property.
A Canvas may be treated as a content resource for the purposes of annotating it on to other Canvases. In this situation, the Canvas may be embedded within the Annotation, or require dereferencing to obtain its description.
5.8. Annotation Collection
Annotation Collections represent groupings of Annotation Pages that should be managed as a single whole, regardless of which Canvas or resource they target. This allows, for example, all of the Annotations that make up a particular translation of the text of a book to be collected together. A client might then present a user interface that allows all of the Annotations in an Annotation Collection to be displayed or hidden according to the user’s preference.
Annotation Collections must have a URI, and it should be an HTTP (S) URI. They should have a label and may have any of the other descriptive, linking or rights properties.
For Annotation Collections with many Annotations, there will be many pages. The Annotation Collection refers to the first and last page, and then the pages refer to the previous and next pages in the ordered list. Each page is part of the Annotation Collection.
6. HTTP Requests and Responses
This section describes the recommended request and response interactions for the API . The REST and simple HATEOAS approach is followed where an interaction will retrieve a description of the resource, and additional calls may be made by following links obtained from within the description. All of the requests use the HTTP GET method; creation and update of resources is not covered by this specification. It is recommended that implementations also support HTTP HEAD requests.
6.1. URI Recommendations
While any HTTP (S) URI is technically acceptable for any of the resources in the API , there are several best practices for designing the URIs for the resources.
- The URI should use the HTTPS scheme, not HTTP .
- The URI should not include query parameters or fragments.
- Once published, they should be as persistent and unchanging as possible.
- Special characters must be encoded.
6.2. Requests
Clients are only expected to follow links to Presentation API resources. Unlike IIIF Image API requests, or other parameterized services, the URIs for Presentation API resources cannot be assumed to follow any particular pattern.
6.3. Responses
The format for all responses is JSON , as described above. It is good practice for all resources with an HTTP (S) URI to provide their description when the URI is dereferenced. If a resource is referenced within a response, rather than being embedded , then it must be able to be dereferenced.
If the server receives a request with an Accept header, it should respond following the rules of content negotiation . Note that content types provided in the Accept header of the request may include parameters, for example profile or charset .
If the request does not include an Accept header, the HTTP Content-Type header of the response should have the value application/ld+json ( JSON-LD ) with the profile parameter given as the context document: http://iiif.io/api/presentation/3/context.json .
If the Content-Type header application/ld+json cannot be generated due to server configuration details, then the Content-Type header should instead be application/json (regular JSON ), without a profile parameter.
The HTTP server must follow the CORS requirements to enable browser-based clients to retrieve the descriptions. If the server receives a request with one of the content types above in the Accept header, it should respond with that content type following the rules of content negotiation . Recipes for enabling CORS and conditional Content-Type headers are provided in the Apache HTTP Server Implementation Notes .
Responses should be compressed by the server as there are significant performance gains to be made for very repetitive data structures.
7. Authentication
It may be necessary to restrict access to the descriptions made available via the Presentation API . As the primary means of interaction with the descriptions is by web browsers using XmlHttpRequests across domains, there are some considerations regarding the most appropriate methods for authenticating users and authorizing their access. The approach taken is described in the Authentication specification, and requires requesting a token to add to the requests to identify the user. This token might also be used for other requests defined by other APIs.
It is possible to include Image API service descriptions within the Manifest, and within those it is also possible to include links to the Authentication API ’s services that are needed to interact with the image content. The first time an Authentication API service is included within a Manifest, it must be the complete description. Subsequent references should be just the URI of the service, and clients are expected to look up the details from the full description by matching the URI. Clients must anticipate situations where the Authentication service description in the Manifest is out of date: the source of truth is the Image Information document, or other system that references the Authentication API services.
A. Summary of Property Requirements
Descriptive and Rights Properties
*A Canvas that is the value of a placeholderCanvas or accompanyingCanvas property may not have either of those properties itself.
Technical Properties
*If a Canvas has either of height and width , it must have the other, as described in the definitions of those properties.
Linking Properties
Structural Properties
Behavior Values
* hidden is allowed on Annotation Collections, Annotation Pages, Annotations, Specific Resources and Choices, as these are the classes that result in rendering content to the user.
B. Example Manifest Response
C. versioning.
Starting with version 2.0, this specification follows Semantic Versioning . See the note Versioning of APIs for details regarding how this is implemented.
D. Acknowledgements
Many thanks to the members of the IIIF community for their continuous engagement, innovative ideas, and feedback.
Many of the changes in this version are due to the work of the IIIF AV Technical Specification Group , chaired by Jason Ronallo (North Carolina State University), Jon Dunn (Indiana University) and Tom Crane (Digirati). The IIIF Community thanks them for their leadership, and the members of the group for their tireless work.
E. Change Log

IMAGES
VIDEO
COMMENTS
You’ve probably heard the term “annual percentage yield” used a lot when it comes to credit cards, loans and mortgages. Banks or investment companies use the annual percentage yield, or APY, to calculate how much your investment will earn i...
The specific gravity table published by the American Petroleum Institute (API) is a tool for determining the relative density of various types of oil. While it has no units of measurement, an oil’s rating is expressed as API degrees. The sc...
Popular web browsers include Internet Explorer, Chrome, Firefox, Opera, Safari, Netscape, Camino and K-Meleon. There are nearly 80 different web browsers according to Web Developers Notes.
The Presentation API lets a user agent (such as a Web browser) effectively display web content through large presentation devices such as
In controlling browsing context, the Presentation interface provides a mechanism to override the browser default behavior of launching
The Presentation API aims to make presentation displays such as projectors, attached monitors, and network-connected TVs available to the Web.
This sample illustrates the use of Presentation API, which gives the ability to access external presentation-type displays and use them for presenting Web
Gives ability to access external presentation-type displays and use them for presenting web content. Demos and samples.
The Web Presentation API allows a Web application to request display of Web content on a secondary (wired, or wireless) screen. The content may be rendered
Chrome 66 allows web pages to use a secondary attached display through the Presentation API and to control its contents through the
to add support to Freeciv-web for displaying the game on TV using the attached Chromecast, controlled by an Android phone. When I tried the "Presentation API
reveal.js is an open source HTML presentation framework. It's a tool that enables anyone with a web browser to create fully-featured and beautiful presentations
Web resources such as images, audio, video, or text which are associated with a Canvas via an Annotation, or provide a representation of any resource.
Adobe Connect is a cloud-based web conferencing solution designed to help businesses, public agencies, and educational institutions organize meetings and