Abstract
This specification defines an API to enable web content to access
external presentation-type 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. Other documents may supersede this document. A list of
current W3C publications and the latest revision of this technical
report can be found in the W3C
technical reports index at http://www.w3.org/TR/.
This document was published by the Second Screen Presentation
Working Group as a First Public Working Draft. If you wish to make comments
regarding this document, please send them to public-secondscreen@w3.org
(subscribe,
archives).
All comments are welcome.
This document is a work in progress and is subject to change. It
builds on the final report
(dated 18 November 2014) produced by the Second Screen Presentation
Community Group. Algorithms have been drafted in particular. Most
sections are still incomplete or underspecified. Privacy and security
considerations are missing. A few open issues are noted inline. Please
check the group's issue tracker on
GitHub for an accurate list. Feedback from early experimentations is
encouraged to allow the Second Screen Presentation Working Group to
evolve the specification based on implementation issues.
Publication as a First Public Working Draft does not imply endorsement
by the W3C Membership.
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 5 February 2004
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 1 August 2014 W3C Process Document.
1
Introduction
This section is non-normative.
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.
At its core, this specification enables an exchange of messages between
a requesting page and a presentation page shown in the secondary
display. How those messages are transmitted is left to the UA in order
to allow for use of display devices that can be attached in a wide
variety of ways. For example, when a display device is attached using
HDMI or MiraCast, the UA on the requesting device can render the
requested presentation page in that same UA, but instead of displaying
in a window on that same device, it can use whatever means the
operating system provides for using those external displays. In that
case, both the requesting page and the presentation page run on the
requesting device and the operating system is used to route the
presentation display output to the other display device. The second
display device doesn't need to know anything about this spec or that
the content involves HTML5.
Alternately, some types of external displays may be able to render
HTML5 themselves and may have defined their own way to send messages to
that content. In that case, the UA on the requesting device would not
need to render the presentation page itself. Instead, the UA could act
as a proxy translating the request to show a page and the messages into
the form understood by the display device.
This way of attaching to displays could be enhanced in the future
through definition of a standard protocol for delivering these types of
messages that display devices could choose to implement.
The API defined here is intended be used with UAs that attach to
display devices through any of the above means.
2
Use cases and requirements
2.1
Use cases
-
Presentations
-
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.
-
Video and image sharing
-
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.
-
Multiplayer gaming
-
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.
ISSUE
27: Define a multiplayer gaming use case
-
Media flinging to multiple screens
-
Alice enters a video sharing site using a browser on her tablet.
Next, Alice picks her favorite video from the site, and the video
starts to play on her tablet. While the video is playing Alice
clicks a button "Share on different screen". The browser provides a
user interface that lists all the screens Alice has around her
home, asking her to select one. The screens are identified by names
that are familiar to Alice. Alice picks one screen from the list,
"Alice's big TV", and the video playback continues seamlessly on
the selected screen. Next she decides to switch the playback to a
different screen. She clicks the same button "Share on different
screen" provided by the site, and the browser presents the user
interface that lists all the screens. Alice picks another screen
from the list, "Alice's kitchen TV", and the playback resumes on
that screen. Video site also provides a feature to see the action
(Alice is watching a soccer game) from different angle. Alice
clicks a button "Select screen for additional angle", and the
browser asks Alice similarly to select the screen to be used for
playback. Alice picks "Alice's Projector" and the soccer game is
shown on the projector from a different angle, in parallel to the
content being played back on "Alice's kitchen TV".
ISSUE
40: Screen availability mechanism for multiple sessions
2.2
Requirements
The requirements enumerated in this section are derived from the
use cases.
2.2.1
Functional requirements
-
Discovery & availability
-
The UA must provide a way to find out whether at least one
secondary screen is available.
-
Launching presentation
-
The UA must provide a means of start sending content to the
secondary screen.
-
Resuming presentation
-
The UA must be able to resume an existing session with content
being displayed on the secondary screen.
-
Communication
-
The UA must enable exchanging data between the primary and the
secondary screen in order to have a control channel between the
primary and secondary page. The UA must not make assumptions
about the execution locality of the user agent of the remote
page it communicates with (i.e. the secondary page might run on a
remote user agent and thus the link between the two pages' UA
must be loosely coupled).
-
Signaling disconnection
-
The UA must signal disconnection from the presentation page to
the primary page and vice versa.
Multi-screen enumeration and named identification requirement was
removed after
discussion on the mailing list.
2.2.2
Non-functional requirements
-
Power saving friendly
-
All API design decisions must be analyzed from a power efficiency
point of view. Especially when using wireless display
technologies or querying availability over a radio channel, care
needs to be taken to design the API in a way that does not pose
obstacles to using radio resources in an efficient way. For
example, powering up the wireless display detection only when
needed.
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.)
5
Example
ISSUE 42:
Make the Example section more concise
Running in a compliant user agent, code for presenting a page
http://example.org/presentation.html on the presentation
display looks as follows:
/* controller.html */
<button disabled id=show>Show</button>
<button disabled id=stop>Stop</button>
<script>
var presentation = navigator.presentation,
showButton = document.getElementById('show'),
stopButton = document.getElementById('stop');
var session = null;
var screenAvailable = false;
var presentationUrl = 'http://example.org/presentation.html';
var presentationId = localStorage['presentationId'] ||
new String((Math.random() * 10000).toFixed(0));
// Join an existing presentation if one exists.
presentation.joinSession(presentationUrl, presentationId).then(
function(existingSession) {
setSession(existingSession);
updateButtons();
},
function() {
// No session to join.
});
presentation.onavailablechange = function(e) {
screenAvailable = e.available;
updateButtons();
};
function updateButtons() {
stopButton.disabled = !session;
stopButton.onClick = session ? stopPresent : null;
showButton.disabled = !screenAvailable;
showButton.onclick = screenAvailable ? startPresent : null;
};
function startPresent() {
presentation.startSession(presentationUrl, presentationId).then(
function(newSession) {
setSession(newSession);
updateButtons();
},
function() {
// User cancelled, etc.
});
};
function stopPresent() {
if (!session) return;
session.close();
delete localStorage['presentationId'];
};
function setSession(theSession) {
// NOTE: We could instead close the current session.
if (session) return;
session = theSession;
localStorage['presentationId'] = session.id;
session.onstatechange = function() {
switch (session.state) {
case 'connected':
session.postMessage(/*...*/);
session.onmessage = function() { /*...*/ };
break;
case 'disconnected':
console.log('Disconnected.');
break;
}
};
}
</script>
The availability monitoring for secondary screens begins when the page
adds an event listener for the availablechange event on
the navigator.presentation object. 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.
ISSUE 8:
Timing of availablechange event to signal screen availability
ISSUE 9: How
to filter available screens according to the content being
presented
5.1
Starting new presentations or manually connecting to existing
presentations
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.available is 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.)
Clicking the "Show" button calls
navigator.presentation.startSession(), which causes the
user agent to request from the user a screen to show the
presentation. The url argument indicates the content to
be presented. The presentationId argument (optional)
allows the page to identify this presentation instance, and control
which other pages may connect to it by setting a hard-to-guess id.
As previously discussed on the mailing list - we can add convenience
here by default-generating an ID.
If the user selects a screen with an existing presentation showing
the same url under the same presentationId,
the opening browsing context is connected to that
existing presentation. If the user selects a screen without an
existing presentation, or a screen presenting a different
url or presentationId, the UA connects to
the selected screen, brings up a new presentation window on it, and
starts to show the content denoted by the url argument.
The UA then connects the opening browsing context to
this new presentation and allows the opening browsing
context to exchange messages with it.
navigator.presentation.startSession(url, presentationId)
returns a Promise to the opening browsing
context. When the user selects a screen, the presentation page
is shown and a communication channel has been established the
Promise resolves to a PresentationSession
object, which acts as a handle to the presentation for communication
and state handling. Initially, the state of the
PresentationSession is "connected". At this
point, the opening browsing context can communicate with
the presentation page using the session's postMessage()
to send messages and its onmessage event handler to
receive messages. The presentation page will also have access to
PresentationSession that it can use to send and receive
messages with the opening browsing context (see Usage on remote screen).
If the user cancels screen selection, the Promise
returned by startSession(url, presentationId) remains
unresolved.
ISSUE 20:
Define return value for cancelled/missing session for
startSession()/joinSession()
While there is a pending call to startSession asking the
user to select a screen (that the user has not yet accepted or
canceled), the browser may choose to reject subsequent calls to
startSession from the same page, by returning a
Promise that never resolves. This will prevent the
browser from needing to 'queue up' requests to present to the user.
ISSUE 21:
Define whether multiple simultaneous calls are permitted to
startSession()
5.2
Automatically reconnecting to existing presentations
The opening browsing context may wish to reconnect to an
existing presentation without prompting the user to select a screen.
For example, the site could allow media items from different pages to
be shown on the same presentation page, and does not want to prompt
the user on each page to reconnect to that presentation. To reconnect
automatically, the page may call joinSession(url,
presentationId), which returns a Promise that
resolves to an existing PresentationSession if one
exists that is presenting the same url with the same
presentationId as was passed originally into
startSession. The opening browsing context
can then communicate with the presentation as if the user had
manually connected to it via startSession.
At the time the joinSession(url, presentationId) method
is called, if the browser is not aware of any
PresentationSession with a matching url and
presentationId, the Promise should remain
unresolved. The browser may become aware of such a session at a later
time (for example, by switching to a WiFi network that has a screen
showing that URL). In this case, the browser may resolve the Promise
to allow the page to connect to the running session.
If the browser knows of multiple matching sessions, it should connect
the page to the session that was most recently connected to; if that
cannot be determined by the browser (for example, if the matching
sessions have never been connected), then the Promise
should remain unresolved.
ISSUE 39:
Resumption of multiple sessions
If the page calls startSession(url, presentationId) and
there is a pending Promise from a call to
joinSession(url, presentationId) (with the same
url and presentationId, and the user
selects a screen in response to startSession, then the
Promise from startSession will be resolved
and the Promise from joinSession will not.
5.4
Usage on remote screen
For addressing the requirement of communication between originating
page and presentation page/screen, the presenting page can now use
the same session object. It accesses this object through
the navigator.presentation.session property, which is
only non-null for the page on the presentation screen.
if (navigator.presentation.session) {
var session = navigator.presentation.session;
// Communicate with opening browsing context
session.postMessage(/*...*/);
session.onmessage = function() {/*...*/};
session.onstatechange = function() {
switch (this.state) {
case "disconnected":
// Handle disconnection from opening browsing context
}
};
};
When the content denoted by the url argument in the
startSession() example above is loaded, the page on the
presentation screen will have its
navigator.presentation.session property set to 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 opening browsing
context using postMessage() and
onmessage.
The presentation page can also monitor the connection state by
listening for statechange events. When the state changes
to "disconnected" the page is made aware of the fact
that communication with the opening browsing context was
lost, but it can continue to display the current content. The
communication can be re-established when a statechange
event fires with a new state of "connected".
ISSUE 19:
Specify behavior when multiple controlling pages are connected to the
session
ISSUE 18:
Define reconnection for cross-page navigation on presenting user
agent
ISSUE 14:
Define user agent context for rendering the presentation
6
API
6.1
Common idioms
A presentation display refers to an external screen
available to the user agent via an implementation specific connection
technology.
A presentation is an active
connection between a user agent and a presentation
display for displaying web content on the latter at the
request of the former.
A presentation
session is an object relating an opening browsing
context to its presentation display and enabling
two-way-messaging between them. Each such object has a
presentation session state and a presentation session
identifier to distinguish it from other presentation sessions.
An opening browsing context is a browsing context that has initiated or resumed a
presentation session by calling
startSession() or
joinSession().
6.2
Common definitions
Let D be the set of presentations that are currently known
to the user agent (regardles of their state). D is
represented as a set of tuples (U, I, S) where U is
the URL that is being presented;
I is an alphanumeric identifier for the presentation; and
S is the user agent's PresentationSession for
the presentation. U and I together uniquely
identify the PresentationSession of the corresponding
presentation.
Each presentation
session is represented by a PresentationSession
object.
enum PresentationSessionState { "connected", "disconnected" /*, "resumed" */ };
interface PresentationSession : EventTarget {
readonly DOMString? id;
readonly attribute PresentationSessionState state;
void postMessage(DOMString message);
void close();
attribute EventHandler onmessage;
attribute EventHandler onstatechange;
};
The id attribute holds the alphanumeric
presentation session identifier.
The state attribute represents the
presentation session's current state. It can take one of
the values of PresentationSessionState
depending on connection state.
When the postMessage() method is called on a
PresentationSession object with a message,
the user agent must run the algorithm to post a message through a
PresentationSession.
When the close() method is called on a
PresentationSession, the user agent must run the
algorithm to close a presentation
session.
ISSUE 34:
Specify the presentation initialization algorithm
When the user agent is to close a
presentation session S, it must run the following steps:
- If S.state is not
connected, then:
- Abort these steps.
- Set S.state to
disconnected.
- Let D be the set of presentations known by the user
agent.
-
Queue a task T
to run the following steps in order:
- For each presentation (U, I, S') in D,
- Let u equal U, i equal
I, and s equal S'.
- If u is equal to S.url and i
is equal to S.id, run the following steps:
-
Queue a task
to fire an event named
statechange at s.onstatechange.
ISSUE
35: Refine how to do session teardown/disconnect/closing
6.3.3
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
PresentationSession interface:
|
Event handler
|
Event handler event type
|
onmessage
|
message
|
onstatechange
|
statechange
|
partial interface Navigator {
readonly attribute NavigatorPresentation presentation;
};
The presentation attribute is used to retrieve
an instance of the NavigatorPresentation interface, the
main interface of Presentation API.
interface NavigatorPresentation : EventTarget {
readonly attribute PresentationSession? session;
Promise<PresentationSession> startSession(DOMString url, DOMString? presentationId);
Promise<PresentationSession> joinSession(DOMString url, DOMString? presentationId);
attribute EventHandler onavailablechange;
};
ISSUE 52:
Specify the NavigatorPresentation.session attribute and its related
algorithms
7.1
Starting a presentation session
When the startSession(presentationUrl,
presentationId) method is called, the user agent must run the
following steps:
-
Input
-
presentationUrl, the URL of the document to be presented
-
presentationId, an optional identifier for the
presentation
-
Output
-
P, a Promise
- Let P be a new Promise.
- Return P.
- If the user agent does not monitor presentation display
availability, run the following steps:
-
Monitor presentation display availability.
- Wait until the algorithm completes.
- If the list of available presentation displays is
empty, then:
-
Reject P with a
"NoScreensAvailable" exception.
- Abort all remaining steps.
- Queue a task T to request user permission for the use of
a presentation display
and selection of one presentation display.
- If T completes with the user granting
permission to use a screen, run the following steps:
- If
presentationId is not undefined,
assign I to that that presentationId.
- If
presentationId is undefined,
let I be a random alphanumeric value of at least 16
characters drawn from the characters
[A-Za-z0-9].
- Create a new
PresentationSession S.
- Set
S.url to presentationUrl,
set S.id to I, and set
S.state to disconnected.
-
Queue a task
C to create a new browsing context on the user-selected
presentation display and
navigate to
presentationUrl in it.
- If C completes successfully, run the
following steps:
- Add (S.url, S.id, S) to D.
-
Resolve P with
S.
-
Establish a presentation connection
with S.
- If C fails, run the following steps:
-
Reject P with a "failed"
exception.
- If T completes with the user denying
permission, run the following steps:
-
Reject P with a
"PermissionDenied" exception.
The details of implementing the permission request and display
selection are left to the user agent; for example it may show the
user a dialog and allow the user to select an available screen
(granting permission), or cancel the selection (denying permission).
ISSUE: Do we want to distinguish the permission-denied outcome from
the no-screens-available outcome? Developers would be able to infer
it anyway from onavailablechange.
7.2
Joining a presentation session
When the joinSession(presentationUrl,
presentationId) method is called, the user agent must run the
following steps:
-
Input
-
presentationUrl, the URL of the document being presented
-
presentationId, the identifier for the presentation
-
Output
-
P, a Promise
- Let P be a new Promise.
- Return P.
- Let D be the set of presentations known by the user
agent.
-
Queue a task T to
run the following steps in order:
- For each presentation (U, I, S) in D,
- Let u equal U, i equal
I, and s equal S.
- If u is equal to
presentationUrl
and i is equal to presentationId, run
the following steps:
-
Resolve P with
S.
-
Establish a presentation connection with
S.
- Abort the remaining steps of T.
-
Reject P with a
"NoPresentationFound" exception.
ISSUE: If no matching presentation is found, we could leave the
Promise pending in case a matching presentation is started in the
future.
7.3
Establishing a presentation connection
When the user agent is to establish a presentation
connection using a presentation session
S, it must run the following steps:
- If S.state is
connected, then:
- Abort all remaining steps.
-
Queue a task T to
connect S to the document that is presenting
S.url.
- If T completes successfully, run the following steps:
- Set S.state to
connected.
- Let D be the set of presentations known by the user
agent.
- Queue a task T to run the following steps in order:
- For each presentation (U, I, S') in D,
- Let u equal U, i equal
I, and s equal S'.
- If u is equal to S.url and
i is equal to S.id, run the following
steps:
-
Queue a
task to fire an event
named
statechange at
s.onstatechange.
The mechanism that is used to present on the remote display and
connect the opening browsing context with the presented
document is an implementation choice of the user agent. The
connection must provide a two-way messaging abstraction capable of
carrying DOMString payloads in a reliable and in-order
fashion as described in the Send Message and Receive
Message steps below.
If T does not complete successfully, the user agent may
choose to re-execute the Presentation Connection algorithm at a later
time.
ISSUE: Do we want to notify the caller of a failure to connect, i.e.
with an "error" onstatechange?
ISSUE: Do we want to pass the new state as a property of the
statechange event?
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
PresentationSession interface:
|
Event handler
|
Event handler event type
|
onavailablechange
|
availablechange
|
In order to satisfy the power saving non-functionional
requirements the user agent must keep track of the number of
EventHandlers registered to the onavailable
event. Using this information, implementation specific discovery of
presentation displays can
be resumed or suspended, in order to save power.
The user agent must keep a list of available presentation
displays. According to the number of event handlers for
onavailablechange, the user agent must also keep the list
up to date by running the algorithm for monitoring the list of available
presentation displays.
[Constructor(DOMString type, optional AvailableChangeEventInit eventInitDict)]
interface AvailableChangeEvent : Event {
readonly attribute boolean available;
};
dictionary AvailableChangeEventInit : EventInit {
boolean available;
};
An event named availablechange is fired during the
execution of the monitoring presentation display
availability algorithm when the presentation display
availability changes. It is fired at the
PresentationSession object, using the
AvailableChangeEvent interface, with the
available attribute set to the boolean value that the
algorithm determined.
Acknowledgments
Thanks to Wayne Carr, Louay Bassbous, Anssi Kostiainen, 闵洪波 (Hongbo
Min), Anton Vayvod, and Mark Foltz for help with editing, reviews and
feedback to this draft.