WebRTC Priority Control API

Editor’s Draft,

This version:
http://w3c.github.io/webrtc-priority/
Latest published version:
https://www.w3.org/TR/webrtc-priority/
Feedback:
public-webrtc@w3.org with subject line “[webrtc-priority] … message topic …” (archives)
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 is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

If you wish to make comments regarding this document, please 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.

This document was produced by the Web Real-Time Communications Working Group.

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 [RTCWEB-TRANSPORT] and [TSVWG-RTCWEB-QOS] 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 [RTCWEB-TRANSPORT], Sections 4.1 and 4.2. Corresponds to "below normal" as defined in [RTCWEB-DATA].
low See [RTCWEB-TRANSPORT], Sections 4.1 and 4.2. Corresponds to "normal" as defined in [RTCWEB-DATA].
medium See [RTCWEB-TRANSPORT], Sections 4.1 and 4.2. Corresponds to "high" as defined in [RTCWEB-DATA].
high See [RTCWEB-TRANSPORT], Sections 4.1 and 4.2. Corresponds to "extra high" as defined in [RTCWEB-DATA].

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 [RTCWEB-TRANSPORT], 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 [RTCWEB-TRANSPORT] 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.

Conformance requirements phrased as algorithms or specific steps can 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 understand and are not intended to be performant. Implementers are encouraged to optimize.

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
[RTCWEB-DATA]
R. Jesup; S. Loreto; M. Tuexen. RTCWeb Data Channels. 14 October 2015. Active Internet-Draft. URL: https://tools.ietf.org/html/draft-ietf-rtcweb-data-channel
[RTCWEB-TRANSPORT]
H. Alvestrand. Transports for RTCWEB. 31 October 2016. Active Internet-Draft. URL: https://tools.ietf.org/html/draft-ietf-rtcweb-transports
[TSVWG-RTCWEB-QOS]
S. Dhesikan; et al. DSCP Packet Markings for WebRTC QoS. 22 August 2016. Internet Draft (work in progress). URL: https://tools.ietf.org/html/draft-ietf-tsvwg-rtcweb-qos
[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";
};