Copyright © 2013 the contributors to this specification.
++ Copyright © 2014 the Contributors to the + Presentation API Specification, published by the Second Screen + Presentation Community Group under the + W3C Community Contributor License Agreement (CLA). + A human-readable summary is available. +
This specification defines an API to enable web content to access external + presentation-type displays and use them for presenting web content.
+This specification was published by +the Second Screen Presentation +Community Group. It is not a W3C Standard nor is it on the W3C Standards +Track. Please note that under the +W3C Community +Contributor License Agreement (CLA) there is a limited opt-out and other +conditions apply. Learn more about W3C +Community and Business Groups.
-Copyright © 2013 the contributors to this specification.
- -This specification aims to make secondary displays such as a projector or a connected TV available to the web and -takes into account displays that are attached using wired (HDMI, DVI or similar) and wireless technologies (MiraCast, DLNA, -AirPlay or similar).
- -Devices with limited screen size lack the ability to show content -to a larger audience, for example a group of colleagues in a -conference room, or friends and family at home. Showing content on an -external large display helps to improve the perceived quality and -impact of the presented content.
- -It is the intention of this specification that the user agent prepares a rendering for the secondary display in a way - that is adapted to the secondary display's capabilities. The DOM state and the rendering shown on the primary and - secondary display are maintained and perfomend by the same user agent. There is no secondary user agent involved - that would run remotely on the secondary display.
- -The user agent creates two browsing contexts, one on the primary display, one on the selected presentation - display. It is responsible for sending the rendered output to the secondary display. For wirelessly connected - displays this may mean that the user agent prepares a video stream from the rendering output that is sent over the - network to the wireless display.
- -The trend in user agent implementations has been to avoid opening -multiple separate windows and containing window management to tabs, -which helps the user to organize multiple pages. However, the -following example use cases fall outside the regular -management of multiple windows for web pages.
- -A user is preparing a set of slides for a talk. Using a web based -service, she is editing her slides and speaker notes on the primary -screen, while the secondary larger screen shows a preview of the -current slide. When the slides are done, her mobile phone allows her -to access them from an online service while on the go. Coming -to the conference, using wireless display technology, she would like -to present her slides on the stage screen from her mobile phone. The -phone's touch screen helps her to navigate slides and presents a slide -preview, while the projector shows her slides to -the audience.
- -Using an online video or image sharing service, a user would like to show memorable moments to her friends. Using a -device with a small screen, it is impossible to show the content to a large group of people. Connecting an external TV -screen or projector to her device - with a cable or wirelessly - the online sharing service now makes use of the -connected display, allowing a wider audience to enjoy the content.
- -Splitting the gaming experience into a near screen controller and a -large screen visual experience, new gaming experiences can be -created. Accessing the local display on the small screen device and an -external larger display allows for richer web-based gaming -experiences.
- -Running in a compliant user agent, code for playing a video on the presentation display could look like the following:
+ + + ++ Copyright + © 2014 the Contributors to the Presentation API Specification, + published by the Second Screen Presentation + Community Group under the W3C Community + Final Specification Agreement (CLA). +
++ This specification defines an API to enable web content to access + external presentation-type displays and use them for presenting web + content. +
++ This specification was published by the Second Screen Presentation + Community Group. It is not a W3C Standard nor is it on the W3C + Standards Track. Please note that under the W3C Community Final + Specification Agreement (FSA) other conditions apply. Learn more + about W3C Community and Business + Groups. +
++ This report documents the use cases, requirements, examples and + interfaces needed to enable web pages to display web content on secondary + screens. It is an evolved version of the initial + Presentation API that represents the result of discussions within the + Second Screen Presentation Community Group so far. API semantics still + need to be specified. The report may serve as starting point for a + possible Working Group chartered to work on the same topic. +
++ This specification aims to make secondary displays such as a projector or + a connected TV available to the web and 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 content to a + larger audience, for example a group of colleagues in a conference room, + or friends and family at home. Showing content on an external large + display helps to improve the perceived quality and impact of the + presented content. +
++ A user is preparing a set of slides for a talk. Using a web based + service, she is editing her slides and speaker notes on the primary + screen, while the secondary larger screen shows a preview of the current + slide. When the slides are done, her mobile phone allows her to access + them from an online service while on the go. Coming to the conference, + using wireless display technology, she would like to present her slides + on the stage screen from her mobile phone. The phone's touch screen helps + her to navigate slides and presents a slide preview, while the projector + shows her slides to the audience. +
++ Requirements: R1, R3, R4, R5, R7 +
++ Using an online video or image sharing service, a user would like to show + memorable moments to her friends. Using a device with a small screen, it + is impossible to show the content to a large group of people. Connecting + an external TV screen or projector to her device - with a cable or + wirelessly - the online sharing service now makes use of the connected + display, allowing a wider audience to enjoy the content. +
++ The web page shows UI elements that allow the user to trigger displaying + content on the secondary display (e.g a "send to second screen" ) only if + there is at least one secondary screen available. +
++ Requirements: R1, R3, R4, R5, R7 +
++ Splitting the gaming experience into a near screen controller and a large + screen visual experience, new gaming experiences can be created. + Accessing the local display on the small screen device and an external + larger display allows for richer web-based gaming experiences. +
++ Requirements: R1, R3, R4, R5, R7 +
++ Requirements: R1, R3, R4, R5, R6, R7 +
++ Multi-Screen enumeration and named identification removed, after + discussion on the mailing list, cmp. + http://lists.w3.org/Archives/Public/public-webscreens/2014Feb/0021.html : +
++ All diagrams, examples, and notes in this specification are + non-normative, as are all sections explicitly marked non-normative. + Everything else in this specification is normative. +
++ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in RFC + 2119. For readability, these words do not appear in all uppercase letters + in this specification. RFC2119 +
++ 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 end result is equivalent. (In + particular, the algorithms defined in this specification are intended to + be easy to follow, and not intended to be performant.) +
++ The term presentation display + refers to an external screen connected to the device that the user agent + runs on. +
++ The terms event handlers and + event + handler event types are defined in HTML5. +
++ This document provides interface definitions using the + WEBIDL standard. +
+
+ Running in a compliant user agent, code for presenting a page
+ example.html on the presentation display looks as follows:
+
+/* controller.html */ --/* player.html */ +<button disabled>Show</button> -<video> <script> -var v = document.querySelector('video'); - -window.onmessage = function (event) { - v.src = event.data; - v.play(); +var presentation = navigator.presentation, + showButton = document.querySelector('button'); + +presentation.onavailablechange = function(e) { + showButton.disabled = !e.available; + showButton.onclick = show; }; -</script> -- --/* controller.html */ - -<script> -function playVideo() { - if (!navigator.presentation.displayAvailable) - return; - var p = navigator.presentation.requestShow('player.html'); - p.then(function (display) { display.postMessage('http://example.org/video.mp4', '/'); }, - function (error) { console.log('Request to show failed: ' + error.msg); } - ); + +function show() { + var session = presentation.requestSession('http://example.org/'); + + session.onstatechange = function() { + switch (session.state) { + case 'connected': + session.postMessage(/*...*/); + session.onmessage = function() { /*...*/ }; + break; + case 'disconnected': + console.log('Disconnected.'); + break; + } + }; } - -playVideo(); - </script>- -In this example of a video player scenario similar to the video sharing use case - presented above, the opener browsing context loads a document into the presentation browsing context which has a - video element in it and communicates with it through
- -postMessage. The document of the presentation - browsing context receives the commands and for example sets thesrcattribute of the video and starts - playing it.The example uses
- -postMessagefor communication between opener and auxiliary browsing context in order to -encourage the use of asynchronous, potentially cross-origin communication between the two contexts. Direct access to -properties of thedocumentobject in the auxiliary browsing context is an alternative option in case the -documents are loaded from the same origin.-<script> - -/* Monitoring availability */ -navigator.presentation.ondisplayavailablechange = function() { - /* For example: Enable/Disable UI to show content on presentation display here. */ - var availability = navigator.presentation.displayAvailable ? "available" : "unavailable"; - console.log("Presentation display is now " + availability + "."); -} - -</script> ++ The availability monitoring for secondary screens begins when the page + adds an event listener for the
+availablechangeevent on the +navigator.presentationobject. If there are already + available screens when the page adds the first event listener for the + event, the UA synthesizes a single availablechange event to signal the + availability. ++ Do we want to fire an event immediately after the page registers for it? + What's a best practice method for asynchronous notifications of ths kind? + See below in the Open Questions section. +
++ The "Show" button's state (initially disabled) informs the user of the + availability of secondary screen(s), and the button's state is updated if + the availability changes. (The rationale of putting the actual boolean + information into a property of the event
+e.availableis to + allow the implementation to optimize power consumption for network + discovery of remote wireless screens. If this information was provided in + a globally accessible flag, the network discovery could never be + suspended for keeping the flag up to date.) ++ Once the user clicks the "Show" button, the
+show()function + is called. ++ By calling
+navigator.presentation.requestSession(url), the + script on the page tries to launch or resume a presentation on a + secondary screen. Based on theurlargument, the UA looks + for existing sessions and available screens, and presents a screen picker + user interface to the user. Out of the list of existing sessions or + available screens the user selects one item. If an existing session was + selected, the session is resumed by establishing a communication channel. + If a new screen was selected, the UA connects to the selected screen, + brings up a new window on the selected screen, starts to show the content + denoted by the url argument, and the UA establishes a communication + channel with this window. ++ When the
+navigator.presentation.requestSession(url)function + is called, the UA immediately returns asessionobject to + the script which represents a handle to the current presentation session, + used for communication and state handling. ++ If the user has selected a screen, the content is shown and a + communication channel was established, the state of the session object + changes from
+"disconnected"to"connected", + which signals the presentation session is up and running, and the opener + page can communicate with the presentation page. For communication with + the presentation page, the session object'spostMessage()is + used to send, and theonmessageevent handler to receive + messages. ++ If the user cancels the screen selection and never selects a screen, no + state transition happens and the
+sessionobject remains in + the"disconnected"state. ++ Open Questions +
++ Do we need to insert into the description an additional permission prompt + to grant the page access to the "one ore more screens are available" + Information? +
++ If there are already connected screens when the page subscribes to the +
+onavailablechangeevent, we can handle this in two ways: We + can synthesize one initial event to notify the page about available + screens as soon as the first event handler is installed (as described). + Or we can add another message like +navigator.presentation.getAvailable(function(available) { } + );to notify the page about available screens using this one-time + asynchronous getter. Which way should we go? ++ Do we need an additional state like resumed in order to identify resumed + session? It seems that this could be handled on the page level. The + opener page could ask the presentation page whether it is +
+"new"or"resumed". ++ Usage on Remote Screen +
For addressing the requirement of communication between originating + page and presentation page/screen, we can now use the same +sessionobject on the remote side. ++navigator.presentation.onpresent = function(e) { + // Communicate with opener page. + e.session.postMessage(/*...*/); + e.session.onmessage = function() {/*...*/}; + + e.session.onstatechange = function() { + switch (this.state) { + case "disconnected": + // Handle disconnection from opener page. + } + }; +};++ When the content denoted by the url argument in the +
+requestSession()example above is loaded, the page on the + presentation screen receives aPresentEvent, with a +sessionproperty representing the session. This session is a + similar object as in the first example. Here, its initial state is +"connected", which means we can use it to communicate with + the opener page usingpostMessage()and +onmessage. ++ We can also monitor the connection state by listening for +
+statechangeevents. When the state changes to +"disconnected"the page is made aware of the fact that + communication with the opener page was lost, but it can continue to + display the current content. The communication can be re-established when + a new present event fires on thenavigator.presentation+ object. ++ Interfaces +
++ The interfaces described herein address the requirements outlined in the + Use Cases section, and specifically, also + consider the Media Flinging + to Multiple Screens use case unaddressed by the previous version of the Presentation API. This + section describes the interfaces to the extend discussed in the Second + Screen Presentation Community Group. Readers are encouraged to consult + the Example section together with this section for + a more complete understanding of the technical parts of this + specification. +
++
+NavigatorPresentation++interface NavigatorPresentation : EventTarget { + PresentationSession requestSession(DOMString url); + attribute EventHandler onavailablechange; + attribute EventHandler onpresent; +}; -This example demonstrates the auxiliary use case of monitoring for available secondary displays in order to keep the - UI consistent. The
- -displayavailablechangeevent informs about displays appearing or disappearing and - allows the client of the API to update page content accordingly.Conformance
-All diagrams, examples, and notes in this specification are -non-normative, as are all sections explicitly marked non-normative. -Everything else in this specification is normative. - -
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and -"OPTIONAL" in this document are to be interpreted as described in RFC 2119. -For readability, these words do not appear in all uppercase letters in this -specification. RFC2119 - -
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 end result is -equivalent. (In particular, the algorithms defined in this -specification are intended to be easy to follow, and not intended to -be performant.) - -
Terminology
- -The term presentation display refers to an external screen connected to the device that the user agent runs on.
- -The terms opener browsing context - and auxiliary browsing context are defined - in HTML5. - -
The terms event handlers - and event handler event types are - defined in HTML5.
- -The Promises model and the concept of event firing are defined in - the DOM living standard.
- -This document provides interface definitions using the WEBIDL standard. - -
The basic fetch algorithm is defined in - FETCH. - -
Presentation Extension to Navigator
-partial interface Navigator { - readonly attribute Presentation presentation; - + readonly attribute NavigatorPresentation presentation; };++
+AvailableChangeEvent++ Fired at the primary screen's
+NavigatorPresentationobject, + when screen availability changes. ++[Constructor(DOMString type, optional AvailableChangeEventInit eventInitDict)] +interface AvailableChangeEvent : Event { + readonly attribute boolean available; +}; -Presentation Interface
- --interface Presentation : EventTarget { - Promise requestShow(optional DOMString url = "about:blank"); - - readonly attribute boolean displayAvailable; - attribute EventHandler ondisplayavailablechange; +dictionary AvailableChangeEventInit : EventInit { + boolean available; };++
Fired at the secondary screen'sPresentEvent+NavigatorPresentation+ object, when the presentation session is established. ++[Constructor(DOMString type, optional PresentEventInit eventInitDict)] +interface PresentEvent : Event { + readonly attribute PresentationSession session; +}; -
requestShowMethod to request opening and showing a new browsing - context on the selected presentation display.
-Parameters:
-optional DOMString urlReturns:
-PromisePromise that is fulfilled when the request was successful, - rejected if it failed.
displayAvailableA boolean flag to indicate the secondary display availability in the UA. Updated when the display availability changes. - True if there is at least one available secondary display for the mentioned use - cases, false otherwise.
-If at least one event listener is registered to
-the ondisplayavailablechange event handler the user agent
-should start monitoring for the availability of secondary displays suitable
-for the for the mentioned use cases.
When there are no more event listeners attached to
- the ondisplayavailablechange event handler, the user
- agent may stop such monitoring for the availability of secondary displays.
This includes displays connected to the user agent's - system via wired connections (e.g. HDMI, DVI etc.) as well as via - wireless technologies (e.g. MiraCast, DLNA or similar) that use a - local or personal area network as a transport mechanism. The - discovery can be performend by using operating system APIs that - notifiy the user agent about display configuration changes or by - means of network discovery for remote display technologies that - are not handled by the operating system. In the latter case, the - user agent or the operating system that the user agent runs on may - prepare a video stream suitable for being decoded and displayed by - the wirelessly connected display.
- -When a user agent is to monitor for the availability of secondary displays, - it must execute the following steps.
- --
An implementation - of this API may chose to use operating system screen & display information APIs or start an - implementation dependent network discovery process.
displayAvailable to true if at least one suitable display was found in step 2, set to false
- otherwise.displayAvailable is different
- from currentDisplayFound, fire a new event displayavailablechange at
- the navigator.presentation object.displayAvailable.It is left to the implementation to determine a suitable polling/monitoring frequency or alternatively - using notification mechanisms of the host OS for display availability changes.
- -When requesting a presentation display, the user agent returns a Promise and asynchronously -goes through the steps needed to open access to that display. The UA needs to check for availability. If a display is -available, the user agent asks the user for permission to use and select one. Then it can open a new browsing context -on that display and fulfils the Promise with the WindowProxy object of the new auxiliary browsing context as the value -of the Promise, otherwise rejects the Promise with an error.
- -A user agent shall only open and maintain a maximum of one presentation browsing context per
- available secondary display. If requestShow is called a second time and the user selects an available
- display that was previously in use by a previous call to requestShow, the user agent shall close the
- previous browsing context.
When the requestShow method is called, the user agent must execute the
-following algorithm to request access to the presentation display:
displayAvailable is true. If it is false or the algorithm
- is not running, jump to the step labeled failure below.url to an absolute URL
- by relative to the entry
- script's base
- url. Let resolvedUrl be the result of this resolution.
- WindowProxy of the new presentation browsing context as its value.DOMError. The user agent must determine the error type in the following order of priority:SecurityError.NotSupportedError.The user agent should provide a means for the user to close - the presentation browsing context.
- -In a PC scenario, this could be by means of an overlay on the secondary display with a close icon. In a mobile scenario where the user has no means of using a mouse cursor or other interaction with the secondary display, it could be an icon on the primary display.
- -If the user closes the presentation browsing context, the user - agent should follow the regular algorithm for closing a browsing context.
- -This means, that the opener browsing context can register
- an onunload EventHandler on
- the presentation browsing context to detect when the window gets
- closed.
There are currently two open issues: A user of this API can subscribe to the onunload
- event of the presentation browsing context's Window
- object but this event only fires if the URL loaded in the presentation
- browsing context's is from the same origin. Secondly, there is no such thing as an onerror event
- if the presentation browsing context is closed unexpectedly.
Similarly, when the close() method of the WindowProxy
- is called, the user agent must behave as specified in the steps for the close() method of
- the Window object.
-
-
If the display configuration of the user agent's host system changes so that the secondary display is not available - anymore, or if a display connected via the network becomes unreachable, and the user agent was showing an existing - presentation browsing context on the display which is now unavaible, the user agent should follow the regular - algorithm for closing a browsing - context.
- -When the browsing context from which one or more presentation browsing - contexts were opened is getting closed, the user agent should close all presentation browsing contexts that it opened. - -
The widespread use of popup blockers shows that the window.open() functionality was often abused to interrupt the user's
-workflow with unsolicited advertising. It is clear that repeating this story should be avoided. Hence, when implementing
-this specification, user agents shall give clear indication to the user that a site is requesting to open a presentation
-display. User agents may prompt the user to give consent to displaying content on the selected presentation display.
User Agents may provide a setting which prevents pages from using -a presentation display -altogether.
- -Opening the presentation browsing context follows the legacy
- behavior of window.open() and thus
- allows navigating to URLs that are not at the same origin as the browsing context of the incumbent
- script. This does not introduce any new security issues in itself. However, it would be desirable to only
- navigate to URLs in the presentation browsing context using the basic fetch algorithm with the CORS flag flag set to true, but
- this would require changes to or a local redefinition of the
- navigation algorithm.
-
-
Thanks to Wayne Carr and Anssi Kostiainen for input, thorough reviews and feedback to this draft.
- - +dictionary PresentEventInit : EventInit { + PresentationSession session; +}; + +PresentationSession
+ + An object representing the established presentation session. +
+
+enum PresentationSessionState { "connected", "disconnected" /*, "resumed" */ };
+
+interface PresentationSession : EventTarget {
+ readonly attribute PresentationSessionState state;
+ void postMessage(DOMString message);
+ void close();
+ attribute EventHandler onmessage;
+ attribute EventHandler onstatechange;
+};
+
+ + Thanks to Wayne Carr, Louay Bassbous, Anssi Kostiainen, 闵洪波 (Hongbo Min), + Anton Vayvod for help with editing, reviews and feedback to this draft. +
+