This document defines a set of ECMAScript APIs in WebIDL to extend the WebRTC 1.0 API to enable user agents to support scalable video coding (SVC).

The API is based on preliminary work done in the W3C ORTC Community Group.

Introduction

This specification extends the WebRTC specification [[WEBRTC]] to enable configuration of encoding parameters for scalable video coding (SVC). Since SVC bitstreams are self-describing and SVC-capable codecs implemented in browsers require that compliant decoders be capable of decoding any legal encoding sent by an encoder, this specification does not support decoder configuration. However, it is possible for decoders that cannot decode any legal bitstream to describe the supported scalability modes.

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

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.)

Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL-1]], as this specification uses that specification and terminology.

Terminology

The EventHandler interface, representing a callback used for event handlers, and the ErrorEvent interface are defined in [[!HTML51]].

The concepts queue a task, fires a simple event and networking task source are defined in [[!HTML51]].

The terms event, event handlers and event handler event types are defined in [[!HTML51]].

When referring to exceptions, the terms throw and create are defined in [[!WEBIDL-1]].

The term simulcast envelope refers to the maximum number of simulcast streams and the order of the encoding parameters.

The terms fulfilled, rejected, resolved, pending and settled used in the context of Promises are defined in [[!ECMASCRIPT-6.0]].

The terms MediaStream, MediaStreamTrack, and MediaStreamConstraints are defined in [[!GETUSERMEDIA]].

For Scalable Video Coding (SVC), the terms single-session transmission (SST) and multi-session transmission (MST) are defined in [[RFC6190]]. This specification only supports SST but not MST. The term Single Real-time transport protocol stream Single Transport (SRST), defined in [[RFC7656]] Section 3.7, refers to Scalable Video Coding (SVC) implementations that transmit all layers within a single transport, using a single Real-time Transport Protocol (RTP) stream and synchronization source (SSRC). The term Multiple RTP stream Single Transport (MRST), also defined in [[RFC7656]] Section 3.7, refers to implementations that transmit all layers within a single transport, using multiple RTP streams with a distinct SSRC for each layer. This specification only supports SRST transport. Codecs with RTP payload specifications supporting SRST transport include VP8 [[RFC7741]], VP9 [[VP9-PAYLOAD]] and H.264/SVC [[RFC6190]].

This specification references objects, methods, internal slots and dictionaries defined in [[!WEBRTC]], including the RTCPeerConnection object (defined in Section 4.4), the RTCError object (defined in Section 11.1), the addTrack and addTransceiver methods (defined in Section 5.1), the setCodecPreferences method (defined in Section 5.4), the getParameters and setParameters methods (defined in Section 5.2), the RTCRtpParameters dictionary (defined in Section 5.2.1), the RTCRtpSendParameters dictionary (defined in Section 5.2.2), the RTCRtpReceiveParameters dictionary (defined in Section 5.2.3), the RTCRtpCodingParameters dictionary (defined in Section 5.2.4), the RTCRtpEncodingParameters dictionary (defined in Section 5.2.6), the RTCRtpCodecCapability dictionary (defined in Section 5.2.13), the RTCRtpTransceiver object including its [[\Sender]] and [[\Receiver]] internal slots (defined in Section 5.4), the RTCRtpSender object, including its [[\SendEncodings]] and [[\LastReturnedParameters]] internal slots (defined in Section 5.2) and the RTCRtpReceiver object (defined in Section 5.3).

Operational model

This specification extends [[!WEBRTC]] to enable configuration of encoding parameters for SVC, as well as discovery of the SVC capabilities of both an encoder and decoder, by extending the RTCRtpEncodingParameters and RTCRtpCodecCapability dictionaries.

Since this specification does not change the behavior of WebRTC objects and methods, restrictions relating to Offer/Answer negotiation and encoding parameters remain, as described in [[!WEBRTC]] Section 5.2: "setParameters does not cause SDP renegotiation and can only be used to change what the media stack is sending or receiving within the envelope negotiated by Offer/Answer."

The configuration of SVC-capable codecs implemented in browsers fits within this restriction. Codecs such as VP8 [[RFC6386]], VP9 [[VP9]] and AV1 [[AV1]] mandate support for SVC and require a compliant decoder to be able to decode any compliant encoding that an encoder can send. Therefore, for these codecs there is no need to configure the decoder or to negotiate SVC support within Offer/Answer, enabling encoding parameters to be used for SVC configuration.

Error handling

[[!WEBRTC]] Section 5.2 describes error handling in setParameters, including use of RTCError to indicate a "hardware-encoder-error" due to an unsupported encoding parameter, as well as OperationError for other errors. Implementations of this specification utilize RTCError and OperationError in the prescribed manner when an invalid scalabilityMode is provided to setParameters or addTranscever.

Note that since the addTransceiver and setCodecPreferences methods can be called before the Offer/Answer negotiation has concluded, the negotiated codec and its capabilities may not be known, and it is possible that the scalabilityMode values configured in sendEncodings cannot be applied due to incompatibility with the eventually selected codec. Since this cannot be determined at the time addTransceiver is called, an error may only be detected if a scalabilityMode value is invalid for any supported codec. In order for the application to determine whether the requested scalabilityMode values have been applied, the RTCRtpSender.getParameters method can be called after negotiation has completed and the sending codec has been determined. If the configuration is not satisfactory, the application can utilize setParameters to change it.

To influence the Offer/Answer negotiation so as to make it more likely that the desired scalabiltyMode values can be applied, setCodecPreferences can be used to limit the negotiated codecs to those supporting the desired configuration. For example, if it is desired to support temporal scalability as well as spatial adaptation, when addTransceiver is called, sendEncodings can be configured so as to send multiple simulcast streams with different resolutions, with each stream utilizing temporal scalability. Since temporal scalability is supported by the VP8, VP9 and AV1 codecs, such a configuration could be applied if any of these codecs were negotiated. In the event that H.264/AVC was negotiated, temporal scalability would not be available, but simulcast with different resolutions would be applied. If this was unsatisfactory, a subsequent call to setParameters could be used to adjust the parameters within the envelope negotiated in Offer/Answer.

In situations where the decoder cannot necessarily decode anything that an encoder can send (e.g. an H.264/SVC decoder), the getCapabilities method can be used to retrieve the scalability modes supported by the decoder and encoder. By exchanging capabilities, the application can compute the intersection of the scalabilityMode values supported by the local and remote peers, enabling it to configure scalabilityMode values supported by both the local and remote peers using the addTransceiver and setParameters methods. However, in situations where SVC modes are negotiated in SDP Offer/Answer, setParameters can only change scalabilityMode values within the envelope negotiated by Offer/Answer, resulting in an error if the requested scalabilityMode value is outside this envelope.

Dictionary extensions

RTCRtpEncodingParameters Dictionary Extensions

partial dictionary RTCRtpEncodingParameters {
             DOMString           scalabilityMode;
};

Dictionary RTCRtpEncodingParameters Members

scalabilityMode of type DOMString

An identifier of the scalability mode to be used for this stream. The scalabilityMode selected MUST be one of the scalability modes supported for the codec, as indicated in RTCRtpCodecCapability. Scalability modes are defined in Section 6.

RTCRtpCodecCapability Dictionary Extensions

partial dictionary RTCRtpCodecCapability {
             sequence<DOMString>           scalabilityModes;
};

Dictionary RTCRtpCodecCapability Members

scalabilityModes of type sequence<DOMString>

An sequence of the scalability modes (defined in Section 6) supported by the encoder implementation.

In response to a call to RTCRtpSender.getCapabilities(kind), conformant implementations of this specification MUST return a sequence of scalability modes supported by each codec of that kind. If a codec does not support encoding of any scalability modes, then the scalabilityModes member is not provided.

In response to a call to RTCRtpReceiver.getCapabilities(kind), decoders that do not support decoding of scalability modes (e.g. an H.264/AVC decoder) or that are required to decode any scalability mode (such as compliant VP8, VP9 and AV1 decoders) omit the scalabilityModes member. However, decoders that only support decoding of a subset of scalability modes MUST return a sequence of the scalability modes supported by that codec.

The scalabilityModes sequence represents the scalability modes supported by a user agent. While the user agent's SVC capabilities are assumed to be static, this may not be the case for a Selective Forwarding Unit (SFU), whose ability to forward SVC modes may depend on the negotiated header extensions. For example, if the SFU cannot parse codec payloads (either because it is not designed to do so, or because the payload is confidential), then without negotiating an RTP header extension such as [[FRAME-MARKING]], the SFU may not be able to forward any scalability modes. As a result, an application may choose to exchange scalabilityModes with an SFU after the initial offer/answer negotiation, so that it can compute the intersection of supported scalabilityModes.

Scalability modes

Scalability mode identifiers and characteristics are indicated in the table below, which is based on the pre-defined scalability modes in [[AV1]] Section 6.7.5.

Scalability Mode Spatial Layers Resolution Ratio Temporal Layers Inter-layer dependency
L1T2 1 2
L1T3 1 3
L2T1 2 2:1 1 Yes
L2T2 2 2:1 2 Yes
L2T3 2 2:1 3 Yes
L3T1 3 2:1 1 Yes
L3T2 3 2:1 2 Yes
L3T3 3 2:1 3 Yes
L2T1h 2 1.5:1 1 Yes
L2T2h 2 1.5:1 2 Yes
L2T3h 2 1.5:1 3 Yes
S2T1 2 2:1 1 No
S2T2 2 2:1 2 No
S2T3 2 2:1 3 No
S2T1h 2 1.5:1 1 No
S2T2h 2 1.5:1 2 No
S2T3h 2 1.5:1 3 No
S3T1 3 2:1 1 No
S3T2 3 2:1 2 No
S3T3 3 2:1 3 No
S3T1h 3 1.5:1 1 No
S3T2h 3 1.5:1 2 No
S3T3h 3 1.5:1 3 No
L3T2_KEY 3 2:1 2 Yes
L3T3_KEY 3 2:1 3 Yes
L4T5_KEY 4 2:1 5 Yes
L4T7_KEY 4 2:1 7 Yes
L3T2_KEY_SHIFT 3 2:1 2 Yes
L3T3_KEY_SHIFT 3 2:1 3 Yes
L4T5_KEY_SHIFT 4 2:1 5 Yes
L4T7_KEY_SHIFT 4 2:1 7 Yes

Examples

Spatial Simulcast and Temporal Scalability

// Example of 3 spatial simulcast layers + 3 temporal layers with
// an SSRC and RID for each simulcast layer
var encodings = [
  {rid: 'q', scaleResolutionDownBy: 4.0, scalabilityMode: 'L1T3'}
  {rid: 'h', scaleResolutionDownBy: 2.0, scalabilityMode: 'L1T3'},
  {rid: 'f', scalabilityMode: 'L1T3'},
];

// Example of 3 spatial simulcast layers + 3 temporal layers on a single SSRC
var encodings = [
  {scalabilityMode: 'S3T3'}
];

Spatial and Temporal Scalability

// Example of 1 spatial layer + 2 temporal layers
var encodings = [
  {scalabilityMode: 'L1T2'}
];

// Example of 2 spatial layers (with 2:1 ratio) + 3 temporal layers
var encodings = [
  {scalabilityMode: 'L2T3'}
];

SVC Encoder Capabilities

// Capabilities returned by RTCRtpSender.getCapabilities('video').codecs[]
  "codecs": [
    {
      "clockRate": 90000,
      "mimeType": "video/VP8",
      "scalabilityModes": ["L1T2","L1T3"]
    },
    {
      "clockRate": 90000,
      "mimeType": "video/rtx",
      "sdpFmtpLine": "apt=96"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/VP9",
      "scalabilityModes": ["L1T2","L1T3","L2T1","L2T2","L2T3","L3T1","L3T2","L3T3","L1T2h","L1T3h","L2T1h","L2T2h","L2T3h"]
    },
    {
      "clockRate": 90000,
      "mimeType": "video/rtx",
      "sdpFmtpLine": "apt=98"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/H264",
      "sdpFmtpLine": "packetization-mode=1;profile-level-id=42001f;level-asymmetry-allowed=1"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/rtx",
      "sdpFmtpLine": "apt=100"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/H264",
      "sdpFmtpLine": "packetization-mode=0;profile-level-id=42001f;level-asymmetry-allowed=1"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/rtx",
      "sdpFmtpLine": "apt=102"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/H264",
      "sdpFmtpLine": "level-asymmetry-allowed=1;profile-level-id=42e01f;packetization-mode=1"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/rtx",
      "sdpFmtpLine": "apt=104"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/H264",
      "sdpFmtpLine": "level-asymmetry-allowed=1;profile-level-id=42e01f;packetization-mode=0"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/rtx",
      "sdpFmtpLine": "apt=106"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/H264",
      "sdpFmtpLine": "level-asymmetry-allowed=1;profile-level-id=4d0032;packetization-mode=1"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/rtx",
      "sdpFmtpLine": "apt=108"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/H264",
      "sdpFmtpLine": "level-asymmetry-allowed=1;profile-level-id=640032;packetization-mode=1"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/rtx",
      "sdpFmtpLine": "apt=110"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/red"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/rtx",
      "sdpFmtpLine": "apt=112"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/ulpfec"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/AV1",
      "scalabilityModes": ["L1T2","L1T3","L2T1","L2T2","L2T3","L3T1","L3T2","L3T3","L1T2h","L1T3h","L2T1h","L2T2h","L2T3h","S2T1","S2T2","S2T3","S3T1","S3T2","S3T3","S2T1h","S2T2h","S2T3h","S3T1h","S3T2h","S3T3h"]
    },
    {
      "clockRate": 90000,
      "mimeType": "video/rtx",
      "sdpFmtpLine": "apt=113"
    }
]

SFU Capabilities

// RTCRtpReceiver.getCapabilities('video').codecs[] returned by 
// SFU that can only forward VP8 and VP9 temporal scalability modes
 "codecs": [
    {
      "clockRate": 90000,
      "mimeType": "video/VP8",
      "scalabilityModes": ["L1T2","L1T3"]
    },
    {
      "clockRate": 90000,
      "mimeType": "video/VP9",
      "scalabilityModes": ["L1T2","L1T3","L1T2h","L1T3h"]
    }
]

SVC Decoder Capabilities

// RTCRtpReceiver.getCapabilities('video').codecs[] returned by a browser that can
// support all scalability modes within the VP8 and VP9 codecs.
  "codecs": [
    { 
      "clockRate": 90000,
      "mimeType": "video/VP8"
    },
    { 
      "clockRate": 90000,
      "mimeType": "video/rtx",
      "sdpFmtpLine": "apt=96"
    },
    { 
      "clockRate": 90000,
      "mimeType": "video/VP9"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/rtx",
      "sdpFmtpLine": "apt=98"
    },
    {
      "clockRate": 90000,
      "mimeType": "video/H264",
      "sdpFmtpLine": "packetization-mode=1;profile-level-id=42001f;level-asymmetry-allowed=1"
    },

    ...
]

Privacy and Security Considerations

This section is non-normative; it specifies no new behaviour, but instead summarizes information already present in other parts of the specification. The overall security considerations of the APIs and protocols used in WebRTC are described in [[RTCWEB-SECURITY-ARCH]].

Impact on same origin policy

This API enables data to be communicated between browsers and other devices, including other browsers.

This means that data can be shared between applications running in different browsers, or between an application running in the same browser and something that is not a browser. This is an extension to the Web model which has had barriers against sending data between entities with different origins.

This specification provides no user prompts or chrome indicators for communication; it assumes that once the Web page has been allowed to access data, it is free to share that data with other entities as it chooses.

Impact on local network

Since the browser is an active platform executing in a trusted network environment (inside the firewall), it is important to limit the damage that the browser can do to other elements on the local network, and it is important to protect data from interception, manipulation and modification by untrusted participants.

Mitigations include:

These measures are specified in the relevant IETF documents.

Confidentiality of Communications

The fact that communication is taking place cannot be hidden from adversaries that can observe the network, so this has to be regarded as public information.

Persistent information

The WebRTC API exposes information about the underlying media system via the RTCRtpSender.getCapabilities and RTCRtpReceiver.getCapabilities methods, including detailed and ordered information about the codecs that the system is able to produce and consume. The WebRTC-SVC extension adds supported SVC modes to that information, which is in most cases persistent across time and origins, therefore increasing the fingerprint surface.

Change Log

This section will be removed before publication.

Acknowledgements

The editors wish to thank the Working Group chairs and Team Contact, Harald Alvestrand, Stefan Håkansson and Dominique Hazaël-Massieux, for their support.

Scalability Mode Dependency Diagrams

Illustrations of the layer dependencies of various scalability modes are provided in [[AV1]] Section 6.7.5 and are reproduced below for convenience.

L1T2: 2-layer temporal scalability encoding
L1T2: 1-layer spatial and 2-layer temporal scalability encoding
L1T3: 3-layer temporal scalability encoding
L1T3: 1-layer spatial and 3-layer temporal scalability encoding
L2T1: 2-layer spatial and 1-layer temporal scalability encoding
L2T1: 2-layer spatial and 1-layer temporal scalability encoding
L2T2: 2-layer spatial and 2-layer temporal scalability encoding
L2T2: 2-layer spatial and 2-layer temporal scalability encoding
S2T1: 2-layer spatial simulcast encoding
S2T1: 2-layer spatial simulcast encoding
S2T2: 2-layer spatial simulcast and 2-layer temporal scalability encoding
S2T2: 2-layer spatial simulcast and 2-layer temporal scalability encoding
S2T3: 2-layer spatial simulcast and 3-layer temporal scalability encoding
S2T3: 2-layer spatial simulcast and 3-layer temporal scalability encoding
L2T4_KEY: 2-layer spatial and 4-layer temporal scalability K-SVC encoding
L2T4_KEY: 2-layer spatial and 4-layer temporal scalability K-SVC encoding
L2T4_KEY_SHIFT: 2-layer spatial and 4-layer temporal scalability K-SVC encoding with temporal shift
L2T4_KEY_SHIFT: 2-layer spatial and 4-layer temporal scalability K-SVC encoding with temporal shift
L3T2_KEY: 3-layer spatial and 2-layer temporal scalability K-SVC encoding
L3T2_KEY: 3-layer spatial and 2-layer temporal scalability K-SVC encoding
L3T2_KEY_SHIFT: 3-layer spatial and 2-layer temporal scalability K-SVC encoding with temporal shift
L3T2_KEY_SHIFT: 3-layer spatial and 2-layer temporal scalability K-SVC encoding with temporal shift
L3T3_KEY: 3-layer spatial and 3-layer temporal scalability K-SVC encoding
L3T3_KEY: 3-layer spatial and 3-layer temporal scalability K-SVC encoding
L3T3_KEY_SHIFT: 3-layer spatial and 3-layer temporal scalability K-SVC encoding with temporal shift
L3T3_KEY_SHIFT: 3-layer spatial and 3-layer temporal scalability K-SVC encoding with temporal shift
L4T5_KEY: 4-layer spatial and 5-layer temporal scalability K-SVC encoding
L4T5_KEY: 4-layer spatial and 5-layer temporal scalability K-SVC encoding
L4T5_KEY_SHIFT: 4-layer spatial and 5-layer temporal scalability K-SVC encoding with temporal shift
L4T5_KEY_SHIFT: 4-layer spatial and 5-layer temporal scalability K-SVC encoding with temporal shift
L4T7_KEY: 4-layer spatial and 7-layer temporal scalability K-SVC encoding
L4T7_KEY: 4-layer spatial and 7-layer temporal scalability K-SVC encoding
L4T7_KEY_SHIFT: 4-layer spatial and 7-layer temporal scalability K-SVC encoding with temporal shift
L4T7_KEY_SHIFT: 4-layer spatial and 7-layer temporal scalability K-SVC encoding with temporal shift