Remote Playback API

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.

This document builds on the group's experience on presenting web content on external presentation-type displays, and re-uses patterns and design considerations from the Presentation API specification whenever appropriate [PRESENTATION-API].

Although this document is still a work in progress and is subject to change, the Working Group believes that the API surface is stable. Most of the remaining issues listed on the issue tracker are considered minor at this stage except for Issue #41.

Issue #41 discusses the set of media playback features that remote playback devices are expected to support. The group will seek further developer feedback and implementation experience to identify any interoperability issues around these features when used during remote playback, and will further clarify the specification based on feedback received.

For other issues or concerns, it is possible to file a bug or send an email to the mailing list. For small editorial changes like typos, sending a pull request is appreciated.

The Working Group invites everyone to review this document, and will work with relevant groups at W3C to conduct horizontal reviews on accessibility, internationalization, privacy, security and technical architecture principles.

No feature has been identified as being at risk.

The Second Screen Working Group will develop a test suite for the Remote Playback API during the Candidate Recommendation period and prepare an 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 03 November 2023 W3C Process Document.

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, RECOMMENDED, and SHOULD 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.

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to expose the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL].

This section is non-normative.

This specification aims to make remote playback devices such as connected TVs, projectors or audio-only speakers, available to the Web and takes into account playback devices that are attached using wired (HDMI, DVI, or similar) and wireless technologies (Miracast, Chromecast, DLNA, AirPlay, or similar).

Devices with limited screen size or quiet speakers lack the ability to playback media content to a larger audience, for example, a group of colleagues in a conference room, or friends and family at home. Playing media content on an external larger and/or louder remote playback device helps to improve the perceived quality and impact of the played media.

At its core, this specification enables a page that acts as the browsing context to initiate and control remote playback of a particular media element on a selected remote playback device. How the remoting is initiated and controlled is left to the UA in order to allow the use of remote playback devices that can be attached in a wide variety of ways. For example, when a remote playback device is attached using HDMI or Miracast, the same UA that acts as the browsing context renders the remote media. Instead of playing the media on the same device, however, it can use whatever means the operating system provides for using the external remote playback device. In such a case, both the browsing context and the media player run on the same UA and the operating system is used to route the player output to the remote playback device. This is commonly referred to as the media mirroring case. This specification imposes no requirements on the remote playback devices connected in such a manner.

If the remote playback device is able to play the media and communicate with the browsing context but is unable to fetch the media, the browsing context needs to fetch the media data and pass it on to the remote playback device for rendering. This is commonly referred to as media remoting case.

If the remote playback device is able to fetch and play the media and communicate with the browsing context, the browsing context does not need to fetch or render the remoted media. In this case, the UA acts as a proxy that requests the remote playback device to play the media itself by passing the necessary data like the media source. This is commonly referred to as the media flinging case. This way of attaching to displays could be enhanced in the future by defining a standard protocol for delivering these types of messages that remote playback devices could choose to implement.

The API defined here is intended to be used with UAs that attach to remote playback device devices through any of the above means.

This section shows code examples that highlight the usage of the main features of the Remote Playback API. In these examples, player.html implements the player page controlling the remote playback and media.ext is the media file to be played remotely. Both the page and the media are served from the domain https://example.org. Please refer to the comments in the code examples for further details.

Example 1



<video id="videoElement" src="https://example.org/media.ext" />
<button id="deviceBtn" style="display: none;">Pick devicebutton>
<script>
  // The "Pick device" button is visible if at least one remote playback device is available.
  const deviceBtn = document.getElementById("deviceBtn");
  const videoElem = document.getElementById("videoElement");

  function availabilityCallback(available) {
    // Show or hide the device picker button depending on device availability.
    deviceBtn.style.display = available ? "inline" : "none";
  }

  videoElem.remote.watchAvailability(availabilityCallback).catch(() => {
    // Availability monitoring is not supported by the platform, so discovery of
    // remote playback devices will happen only after remote.prompt() is called.
    // Pretend the devices are available for simplicity; or, one could implement
    // a third state for the button.
    deviceBtn.style.display = "inline";
  });
script>

Example 2


<script>
  deviceBtn.onclick = () => {
    // Request the user to select a remote playback device.
    videoElem.remote.prompt()
      // Update the UI and monitor the connected state.
      .then(updateRemotePlaybackState);
      // Otherwise, the user cancelled the selection UI or no screens were found.
  };

Remote Playback API

Abstract

Status of This Document

1. Conformance

2. Introduction

3. Use cases and requirements

4. Examples

4.1 Monitor availability of remote playback devices example

4.2 Starting remote playback of a video example