WebRTC Priority Control API

W3C Candidate Recommendation Snapshot,

This version:
https://www.w3.org/TR/2021/CR-webrtc-priority-20210318/
Latest published version:
https://www.w3.org/TR/webrtc-priority/
Editor's Draft:
https://w3c.github.io/webrtc-priority/
Previous Versions:
Implementation report:
https://wpt.fyi/results/webrtc-priority?label=experimental&label=master&aligned
Test Suite:
https://github.com/web-platform-tests/wpt/tree/master/webrtc-priority
Issue Tracking:
GitHub
Editor:
(Google)

Abstract

This API defines a control surface for manipulating the network control bits (DSCP bits) of outgoing WebRTC packets, and the queueing priority of outgoing WebRTC packets under congestion.

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 https://www.w3.org/TR/.

This document was published by the Web Real-Time Communications Working Group as a Candidate Recommendation Snapshot. This document is intended to become a W3C Recommendation. This document will remain a Candidate Recommendation at least until in order to ensure the opportunity for wide review.

If you wish to make comments regarding this document, please file an issue or send them to public-webrtc@w3.org (subscribe, archives). When sending e-mail, please put the text “webrtc-priority” in the subject, preferably like this: “[webrtc-priority] …summary of comment…”. All comments are welcome.

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. A Candidate Recommendation Snapshot has received wide review and is intended to gather implementation experience.

The entrance criteria for this document to enter the Proposed Recommendation stage is to have a minimum of two independent and interoperable implementations of all the features of this specification, which will be determined by passing the tests defined in the test suite developed by the Working Group. The Working Group will prepare an implementation report to track 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 15 September 2020 W3C Process Document.

1. Introduction

This document defines a "priority" field as part of the WEBRTC RTCRtpEncodingParameters structure, with the possible values "very-low", "low", "medium" and "high".

This feature was originally part of the [WEBRTC] specification, but was removed in November 2019 due to lack of implementation experience. It is now part of this document.

In addition, this specification adds fields to RTCRtpEncodingParameters that allow control over the DSCP markings without affecting local prioritization, and vice versa.

2. Priority and QoS Model

Many applications have multiple media flows of the same data type and often some of the flows are more important than others. WebRTC uses the priority and Quality of Service (QoS) framework described in [rfc8835] and [rfc8837] to provide priority and DSCP marking for packets that will help provide QoS in some networking environments. The priority setting can be used to indicate the relative priority of various flows. The priority API allows the JavaScript applications to tell the browser whether a particular media flow is high, medium, low or of very low importance to the application by setting the priority property of RTCRtpEncodingParameters objects to one of the values defined below.

3. Extensions for media priority

3.1. RTCPriorityType Enum

enum RTCPriorityType {
  "very-low",
  "low",
  "medium",
  "high"
};
Enumeration description
very-low See [rfc8835], Sections 4.1 and 4.2. Corresponds to "below normal" as defined in [rfc8831].
low See [rfc8835], Sections 4.1 and 4.2. Corresponds to "normal" as defined in [rfc8831].
medium See [rfc8835], Sections 4.1 and 4.2. Corresponds to "high" as defined in [rfc8831].
high See [rfc8835], Sections 4.1 and 4.2. Corresponds to "extra high" as defined in [rfc8831].

Applications that use this API should be aware that often better overall user experience is obtained by lowering the priority of things that are not as important rather than raising the priority of the things that are.

3.2. Extension to RTCRtpEncodingParameters

partial dictionary RTCRtpEncodingParameters {
  RTCPriorityType priority = "low";
  RTCPriorityType networkPriority;
};
priority, of type RTCPriorityType, defaulting to "low"

Indicates the priority of an RTCRtpSender, which influences the bandwidth allocation among RTCRtpSender objects. It is specified in [rfc8835], Section 4. The user agent is free to sub-allocate bandwidth between the encodings of an RTCRtpSender.

networkPriority, of type RTCPriorityType
This has the same effect as priority, except that it only affects the DSCP markings of the generated packets, as described in [rfc8835] section 4.2.

If networkPriority is unset, the DSCP markings of the generated packets are controlled by the priority member.

4. Extensions for RTCDataChannel

partial interface RTCDataChannel {
  readonly attribute RTCPriorityType priority;
};

partial dictionary RTCDataChannelInit {
  RTCPriorityType priority = "low";
};

4.1. New RTCDataChannel attribute

priority, of type RTCPriorityType, readonly

The priority attribute returns the priority for this RTCDataChannel. The priority is assigned by the user agent at channel creation time. On getting, the attribute MUST return the value of the [[DataChannelPriority]] slot.

4.2. New RTCDataChannelInit member

priority, of type RTCPriorityType, defaulting to "low"

Priority of this channel.

4.3. RTCDataChannel processing steps

The following steps are added to the initialization steps for DataChannel:

Let DataChannel have an internal slot [[DataChannelPriority]].

In the processing steps for initializing a DataChannel, insert the following step into processing the option argument:

configuration priority value RTCPriorityType value
0 to 128 very-low
129 to 256 low
257 to 512 medium
513 and greater high

5. Security and Privacy Considerations

This API extension does not, per se, expose any new information, and none of the data handled through this extension can be considered sensitive or personally identifiable.

In conjunction with the ability to monitor network traffic, it is possible to use this extension to figure out which parts of the specification are actually honored by the implementation; in particular, whether setting priority causes modification of DSCP markings on the generated packets.

This specification allows some control over parts of network headers that are commonly used for prioritization of network traffic (DSCP markings). If the network to which the UA is attached is misconfigured or underprovisioned, this may influence the local network environment by emitting packets with DSCP markings that are not expected by the configuration.

Countermeasures against this risk include proper configuration; the simplest configuration is DSCP bleaching - always zeroing or ignoring the DSCP markings. Congestion control (always mandatory for WebRTC) will prevent network overload in most cases.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC8831]
R. Jesup; S. Loreto; M. Tüxen. WebRTC Data Channels. January 2021. Proposed Standard. URL: https://datatracker.ietf.org/doc/html/rfc8831
[RFC8835]
H. Alvestrand. Transports for WebRTC. January 2021. Proposed Standard. URL: https://datatracker.ietf.org/doc/html/rfc8835
[RFC8837]
P. Jones; et al. Differentiated Services Code Point (DSCP) Packet Markings for WebRTC QoS. January 2021. Proposed Standard. URL: https://datatracker.ietf.org/doc/html/rfc8837
[WEBRTC]
Cullen Jennings; Henrik Boström; Jan-Ivar Bruaroey. WebRTC 1.0: Real-Time Communication Between Browsers. 26 January 2021. REC. URL: https://www.w3.org/TR/webrtc/

IDL Index

enum RTCPriorityType {
  "very-low",
  "low",
  "medium",
  "high"
};

partial dictionary RTCRtpEncodingParameters {
  RTCPriorityType priority = "low";
  RTCPriorityType networkPriority;
};

partial interface RTCDataChannel {
  readonly attribute RTCPriorityType priority;
};

partial dictionary RTCDataChannelInit {
  RTCPriorityType priority = "low";
};