TODO(henbos): Fill in.

This is an unofficial proposal.

Introduction

TODO(henbos): Fill in.

Terminology

The term RTCIceServer is defined in [[WEBRTC]].

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

RTCPeerConnection extensions

The RTCPeerConnection interface is defined in [[WEBRTC]]. This document extends that interface by adding an additional static method.

partial interface RTCPeerConnection {
  static sequence<RTCIceServer> getDefaultIceServers();
};

Methods

getDefaultIceServers

Returns a list of ICE servers that are configured into the browser. A browser might be configured to use local or private STUN or TURN servers. This method allows an application to learn about these servers and optionally use them.

This list is likely to be persistent and is the same across origins. It thus increases the fingerprinting surface of the browser. In privacy-sensitive contexts, browsers can consider mitigations such as only providing this data to whitelisted origins (or not providing it at all.)

Since the use of this information is left to the discretion of application developers, configuring a user agent with these defaults does not per se increase a user's ability to limit the exposure of their IP addresses.

If set, the configured default ICE servers exposed by getDefaultIceServers on RTCPeerConnection instances provides persistent information across time and origins which increases the fingerprinting surface of a given browser.

getDefaultIceServers() was moved from [[WEBRTC]] to this extension spec due to lack of support from implementers and concerns discussed in webrtc-pc#2023.

RTCRtpReceiver extensions

The RTCRtpReceiver interface is defined in [[WEBRTC]]. This document extends that interface by adding an additional internal slot and attribute.

Let RTCRtpReceiver objects have a [[\PlayoutDelayHint]] internal slot initially initialized to null.

partial interface RTCRtpReceiver {
  attribute double? playoutDelayHint;
  };

Attributes

playoutDelayHint of type double, nullable

This attribute allows the application to give a hint to the User Agent about what playout delay is acceptable. The User Agent SHOULD NOT playout audio or video that is received unless this amount of time has passed in seconds, allowing the User Agent to perform more or less buffering than it might otherwise do. This allows to influence the tradeoffs between having a higher delay and the risk that buffers such as the jitter buffer will run out of audio or video frames to play due to network jitter. This API only serves to provide a hint, and the User Agent may ignore it. The hint SHOULD NOT be followed if it significantly impacts audio or video quality (e.g. bad network), or if the value implies allocating larger buffers than the User Agent is willing to provide.

The playout delay hint applies even if DTX is used. For example, if DTX is used and packets start flowing after silence, the hint can influence the User Agent to buffer these packets rather than playing them out.

If the track is paired with other tracks through RTCRtpReceiver [[\AssociatedRemoteMediaStreams]] internal slot, then it will be synchronized with other tracks (for e.g. audio video synchronization). This means that even if one of the paired tracks is delayed through [[\PlayoutDelayHint]] then the User Agent synchronization mechanism will automatically delay all others paired tracks. If multiple such paired tracks are delayed through [[\PlayoutDelayHint]] by different amounts then the largest of those hints will take precedence in synchronization mechanism.

On getting, this attribute MUST return the value of the [[\PlayoutDelayHint]] internal slot.

On setting, the User Agent MUST run the following steps:

  1. Let receiver be the RTCRtpReceiver object on which the setter is invoked.

  2. Let delay be the argument to the setter.

  3. If delay is negative, throw an TypeError and abort these steps.

  4. Set the value of receiver's [[\PlayoutDelayHint]] internal slot to delay.

  5. In parallel, begin executing the following steps:

    1. Update the underlying system about the new delay hint, or that there is no hint if delay is null. If at any point in time this value is larger than the User Agent is able or willing to provide, the User Agent SHOULD use the maximum value available to match the requested delay as close as possible. If at any point in time this value is smaller than the User Agent determines is needed in order provide sufficient audio or video quality, the User Agent SHOULD use the smallest value possible.

      If User Agent ignores the hint at any time, this is not reflected in the [[\PlayoutDelayHint]] internal slot.

RTCRtpEncodingParameters extensions

The RTCRtpEncodingParameters dictionary is defined in [[WEBRTC]]. This document extends that dictionary by adding an additional boolean flag.

partial dictionary RTCRtpEncodingParameters {
      boolean adaptivePtime = false;
    };

Dictionary RTCRtpEncodingParameters Members

adaptivePtime of type boolean, defaulting to false.

Indicates whether this encoding MAY dynamically change the frame length. If the value is true, the user agent MAY use any valid frame length for any of its frames, and MAY change this at any time. Valid values are multiples of 10ms. If the maxptime attribute (defined in [[RFC4566]] Section 6) is specified, that maximum applies. Read-only parameter.

Using a longer frame length reduces the bandwidth consumption due to overhead, but does so at the cost of increased latency. Changing the frame length dynamically allows the user agent to adapt its bandwidth allocation strategy based on the current network conditions.

If adaptivePtime is set to true, ptime MUST NOT be set; otherwise, InvalidModificationError MUST be thrown.