WebRTC Priority Control API

W3C Working Draft,

This version:
https://www.w3.org/TR/2020/WD-webrtc-priority-20200123/
Latest published version:
https://www.w3.org/TR/webrtc-priority/
Editor's Draft:
http://w3c.github.io/webrtc-priority/
Previous Versions:
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 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/.

Since the previous publication, this document has incorporated the priority attribute for RTCDataChannel (previously defined as part of the WebRTC 1.0 API), and has been retitled to match this new scope.

This document was published by the Web Real-Time Communications Working Group as a Working Draft. This document is intended to become a W3C Recommendation.

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.

Publication as a 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 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 March 2019 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;
  RTCPriorityType networkPriority;
};
priority of type , of type RTCPriorityTypeRTCPriorityType, 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 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;
};

4.1. New RTCDataChannel attribute

priority of type , of type RTCPriorityType, readonlyRTCPriorityType, 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 , of type RTCPriorityTypeRTCPriorityType, 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

Conformance

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.

Index

Terms defined by this specification

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]
Adam Bergkvist; et al. WebRTC 1.0: Real-time Communication Between Browsers. 27 September 2018. CR. URL: https://www.w3.org/TR/webrtc/

IDL Index

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

partial dictionary RTCRtpEncodingParameters {
  RTCPriorityType priority;
  RTCPriorityType networkPriority;
};

partial interface RTCDataChannel {
  readonly attribute RTCPriorityType priority;
};

partial dictionary RTCDataChannelInit {
  RTCPriorityType priority;
};