This document defines a set of ECMAScript APIs in WebIDL to extend the WebRTC 1.0 API.

The API is based on preliminary work done in the W3C WEBRTC Working Group.

Introduction

This document contains proposed extensions to the [[WEBRTC]] specification. Some of these extensions were originally included within the [[WEBRTC]] specification, but needed to be removed due to lack of implementation experience. Others were not sufficiently mature to be incorporated into that specification when they were developed, but were too small to warrant creation of a separate document.

This document contains some sections extending one specific interface or dictionary in the base specification; in this case the extension is only described in an individual section. Where an extension affects multiple interfaces or dictionaries, a subsection in the "Overviews" section describes the extension as a whole, while normative text is provided in sections relating to the individual interfaces.

As extensions mature and gain implementation experience, they may move from this document to the base specification if WG consensus emerges to do so.

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]], as this specification uses that specification and terminology.

Terminology

The following terms are defined in RTP Header Extension for Absolute Capture Time:

The process of chaining an operation to an operations chain is defined in [[WEBRTC]] Section 4.4.1.2.

The OAuth Client and Authorization Server roles are defined in [[RFC6749]] Section 1.1.

Overviews

RTP header control

The extension for RTP header extension control consists of 2 parts:

The RTP header extension mechanism is defined in [[RFC8285]], with the SDP negotiation mechanism defined in section 5. It goes into some detail on the meaning of "direction" with regard to RTP header extensions, and gives a detailed procedure for negotiating RTP header extension IDs.

This API extension gives the means to control the use and direction of RTP header extensions as documented in [[RFC8285]]. It does not influence the ID negotiation mechanism, except for being able to control the number of extensions offered.

{{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 {{RTCPeerConnection/getDefaultIceServers}} on {{RTCPeerConnection}} instances provides persistent information across time and origins which increases the fingerprinting surface of a given browser.

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

{{RTCRtpTransceiver}} extensions

The {{RTCRtpTransceiver}} interface is defined in [[WEBRTC]]. This document extends that interface by adding an additional method and attribute in order to control negotiation of RTP header extensions.

partial dictionary RTCRtpHeaderExtensionCapability {
  RTCRtpTransceiverDirection direction = "sendrecv";
};
      
partial interface RTCRtpTransceiver {
  undefined setOfferedRtpHeaderExtensions(
sequence<RTCRtpHeaderExtensionCapability> headerExtensionsToOffer);
  readonly attribute FrozenArray<RTCRtpHeaderExtensionCapability> headerExtensionsToOffer;
  readonly attribute FrozenArray<RTCRtpHeaderExtensionCapability> headerExtensionsNegotiated;
};
    

Let [[\HeaderExtensionsToOffer]] be an internal slot of the {{RTCRtpTransceiver}}, initialized to the platform-specific list of implemented RTP header extensions. The direction attribute for all extensions that are mandatory to use MUST be initialized to an appropriate value other than "stopped". The {{RTCRtpHeaderExtensionCapability/direction}} attribute for extensions that will not be offered by default in an initial offer MUST be initialized to {{RTCRtpTransceiverDirection/"stopped"}}.

The list of header extensions that MUST/SHOULD be supported is listed in [[RTCWEB-RTP]], section 5.2. The "mid" extension is mandatory to use when BUNDLE is in use, per [[BUNDLE]] section 9.1.

Let {{RTCRtpTransceiver/[[HeaderExtensionsNegotiationed]]}} be an internal slot of the {{RTCRtpTransceiver}}, initialized to an empty list.

Modifications to existing procedures

In the set a session description algorithm, add a step right after the step that sets transceiver.[[\Sender]].[[\SendCodecs]], saying "For each transciever, set {{RTCRtpTransceiver/[[HeaderExtensionsNegotiationed]]}} to an empty list, and then for each "a=hdrext" line, add an appropriate {{RTCRtpHeaderExtensionCapability}} to the list.

\ In the algorithms for generating initial offers in [[RTCWEB-JSEP]] section 5.2.1, replace "for each supported RTP header extension, an "a=extmap" line, as specified in [[RFC5285]], section 5" " with "For each RTP header extension "e" listed in {{RTCRtpTransceiver/[[HeaderExtensionsToOffer]]}} where {{RTCRtpHeaderExtensionCapability/direction}} is not {{RTCRtpTransceiverDirection/"stopped"}}, an "a=extmap" line, as specified in [[RFC5285]], section 5, with direction taken from "e"'s {{RTCRtpHeaderExtensionCapability/direction}} attribute."

In the algorithm for generating subsequent offers in [[RTCWEB-JSEP]] section 5.2.2, replace "The RTP header extensions MUST only include those that are present in the most recent answer" with "For each RTP header extension listed in {{RTCRtpTransceiver/[[HeaderExtensionsToOffer]]}}, and where {{RTCRtpHeaderExtensionCapability/direction}} is not {{RTCRtpTransceiverDirection/"stopped"}}, generate an appropriate "a=extmap" line with "direction" set according to the rules of [[RFC5285]] section 6, considering the {{RTCRtpHeaderExtensionCapability/direction}} in {{RTCRtpTransceiver/[[HeaderExtensionsToOffer]]}} to indicate the answerer's desired usage".

In the algorithm for generating initial answers in [[RTCWEB-JSEP]] section 5.3.1, replace "For each supported RTP header extension that is present in the offer" with "For each supported RTP header extension that is present in the offer and is also present in {{RTCRtpTransceiver/[[HeaderExtensionsToOffer]]}} with a {{RTCRtpHeaderExtensionCapability/direction}} different from {{ RTCRtpTransceiverDirection/"stopped"}}".

Since JSEP does not know about WebRTC internal slots, merging this change requires more work on a JSEP revision.

Methods

setOfferedRtpHeaderExtensions
Execute the following steps:
  1. Let extlist be the list of extensions in the argument.
  2. For each extension ext in extlist, do the following:
    1. If ext.{{RTCRtpHeaderExtensionCapability/uri}} value is missing, [=exception/throw=] a {{TypeError}}.
    2. If ext.{{RTCRtpHeaderExtensionCapability/uri}} value is not present in {{RTCRtpTransceiver/[[HeaderExtensionsToOffer]]}}, [=exception/throw=] a {{NotSupportedError}}.
    3. Let entry be the entry with the same {{RTCRtpHeaderExtensionCapability/uri}} value in {{RTCRtpTransceiver/[[HeaderExtensionsToOffer]]}}.
    4. If ext.{{RTCRtpHeaderExtensionCapability/direction}} is not {{ RTCRtpTransceiverDirection/"sendrecv"}}, and {{RTCRtpHeaderExtensionParameters/uri}} indicates a mandatory-to-use attribute that is required to be both sent and received, [=exception/throw=] an {{InvalidModificationError}}.
    5. if ext.{{RTCRtpHeaderExtensionCapability/direction}} field is {{RTCRtpTransceiverDirection/"stopped"}}, and {{RTCRtpHeaderExtensionCapability/uri}} indicates a mandatory-to-implement extension, [=exception/throw=] an {{InvalidModificationError}}.
    6. Set the {{RTCRtpHeaderExtensionCapability/direction}} field of entry to ext's {{RTCRtpHeaderExtensionCapability/direction}} field.

Attributes

headerExtensionsToOffer, readonly
Returns the value of the {{RTCRtpTransceiver/[[HeaderExtensionsToOffer]]}} slot.
headerExtensionsNegotiated, readonly
Returns the value of the {{RTCRtpTransceiver/[[HeaderExtensionsNegotiationed]]}} slot.

{{RTCRtpHeaderExtensionParameters}} extensions

The {{RTCRtpHeaderExtensionParameters}} dictionary is defined in [[WEBRTC]]. This document extends that dictionary by adding an additional member.

      partial dictionary RTCRtpHeaderExtensionParameters {
        boolean enabled;
      };
    

Attributes

enabled, of type boolean

When returned from {{RTCRtpSender/getParameters()}} on an {{RTCRtpSender}}, {{RTCRtpHeaderExtensionParameters/enabled}} is true when the RTP sender is configured to send this header extension when appropriate. If the attribute is missing, it means that it is enabled and cannot be disabled.

When passed to {{RTCRtpSender/setParameters()}}, setting {{RTCRtpHeaderExtensionParameters/enabled}} to true instructs the RTP sender to send this header extension when appropriate. Setting {{RTCRtpHeaderExtensionParameters/enabled}} to false instructs the RTP sender to never send this extension.

When calling {{RTCRtpReceiver/getParameters()}} on an {{RTCRtpReceiver}}, the {{RTCRtpHeaderExtensionParameters/enabled}} member will always be missing.

The list of extensions returned from {{RTCRtpSender/getParameters()}} on a sender will only include the extensions that have been negotiated for sending.

The inclusion of a settable member of {{RTCRtpHeaderExtensionParameters}} means that {{RTCRtpParameters/headerExtensions}} is no longer a read-only member of {{RTCRtpParameters}}. The {{RTCRtpHeaderExtensionParameters/uri}}, {{RTCRtpHeaderExtensionParameters/id}} and {{RTCRtpHeaderExtensionParameters/encrypted}} members of {{RTCRtpHeaderExtensionParameters}} remain read-only.

Changing the list, apart from setting the {{RTCRtpHeaderExtensionParameters/enabled}} member, MUST cause {{RTCRtpSender/setParameters()}} to reject with an {{InvalidModificationError}}.

{{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 [[\PlayoutDelay]] internal slot initially initialized to null.

partial interface RTCRtpReceiver {
  attribute double? playoutDelay;
  };

Attributes

playoutDelay of type double, nullable

This attribute allows the application to specify a target duration of time between network reception of media and playout. 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.

The User Agent may have a minimum allowed delay and a maximum allowed delay reflecting what the User Agent is able or willing to provide based on network conditions and memory constraints.

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 {{RTCRtpReceiver/[[PlayoutDelay]]}} then the User Agent synchronization mechanism will automatically delay all others paired tracks. If multiple such paired tracks are delayed through {{RTCRtpReceiver/[[PlayoutDelay]]}} by different amounts then the largest of those hints will take precedence in synchronization mechanism.

The receiver's average delay can be measured as the delta {{RTCInboundRtpStreamStats/jitterBufferDelay}} divided by the delta {{RTCInboundRtpStreamStats/jitterBufferEmittedCount}}.

On getting, this attribute MUST return the value of the {{RTCRtpReceiver/[[PlayoutDelay]]}} 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 or larger than 4 seconds then, [=exception/throw=] a {{RangeError}} and abort these steps.

  4. Set the value of receiver's {{RTCRtpReceiver/[[PlayoutDelay]]}} internal slot to delay.

  5. In parallel, begin executing the following steps:

    1. Update the underlying system about the new delay request, or that there is no hint if delay is null.

      If the given delay value is below minimum allowed delay or above maximum allowed delay then the value used MUST be clamped to minimum allowed delay or maximum allowed delay to be as close as possible to the requested one.

      If User Agent chooses delay different from requested one, for e.g. due to network conditions or physical memory constraints, this is not reflected in the {{RTCRtpReceiver/[[PlayoutDelay]]}} internal slot.

    2. Modifying the delay of the underlying system SHOULD affect the internal audio or video buffering gradually in order not to hurt user experience. Audio samples or video frames SHOULD be accelerated or decelerated before playout, similarly to how it is done for audio/video synchronization or in response to congestion control.

      The acceleration or deceleration rate may vary depending on network conditions or the type of audio received (e.g. speech or background noise). It MAY take several seconds to achieve 1 second of buffering but SHOULD not take more than 30 seconds assuming packets are being received. The speed MAY be different for audio and video.

      For audio, acceleration and deceleration can be measured with {{RTCInboundRtpStreamStats/insertedSamplesForDeceleration}} and {{RTCInboundRtpStreamStats/removedSamplesForAcceleration}}. For video, this may result in the same frame being rendered multiple times or frames may be dropped.

RTCRtpEncodingParameters extensions

The {{RTCRtpEncodingParameters}} dictionary is defined in [[WEBRTC]]. This document extends that dictionary with additional members.

partial dictionary RTCRtpEncodingParameters {
      unsigned long ptime;
      boolean adaptivePtime = false;
      double maxFramerate;
    };

Dictionary {{RTCRtpEncodingParameters}} Members

ptime of type unsigned long

The preferred duration of media represented by a packet in milliseconds.

Support for {{RTCRtpEncodingParameters/ptime}} is marked as a feature at risk, since there is no clear commitment from implementers.

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. If the value is false, the user agent MUST use a fixed frame length.

If {{adaptivePtime}} is set to true, {{ptime}} MUST NOT be set; otherwise, {{InvalidModificationError}} MUST be [=exception/throw|thrown=].

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.

maxFramerate of type double

When present, indicates the maximum frame rate that can be used to send this encoding, in frames per second. The user agent is free to allocate bandwidth between the encodings, as long as the {{maxFramerate}} value is not exceeded.

When set with {{RTCPeerConnection/addTransceiver()}}, the frame rate is required to be 0.0 or greater. If this is not the case, [=exception/throw=] a {{RangeError}}.

If changed with {{RTCRtpSender/setParameters()}}, the new frame rate takes effect after the current picture is completed; setting the max frame rate to zero thus has the effect of freezing the video on the next frame. Upon setting with {{RTCRtpSender/setParameters()}}, if the value is less than 0.0, [=reject=] with a {{RangeError}}.

{{RTCIceCredentialType}} extensions

The following enum values are added to the {{RTCIceCredentialType}} enum defined in [[WEBRTC]].

// This is a partial enum, but this is not yet expressable in WebIDL.
enum RTCIceCredentialType {
    "oauth"
};
Enumeration description
oauth

An OAuth 2.0 based authentication method, as described in [[RFC7635]].

For OAuth Authentication, the ICE Agent requires three pieces of credential information. The credential is composed of a kid, which the {{RTCIceServer.username}} member is used for, and macKey and accessToken, which are placed in the {{RTCOAuthCredential}} dictionary.

This specification does not define how an application (acting as the [=OAuth Client=]) obtains the accessToken, kid and macKey from the [=Authorization Server=], as WebRTC only handles the interaction between the ICE Agent and TURN server. For example, the application may use the OAuth 2.0 Implicit Grant type, with PoP (Proof-of-Possession) Token type, as described in [[RFC6749]] and [[OAUTH-POP-KEY-DISTRIBUTION]]; an example of this is provided in [[RFC7635]], Appendix B.

The application, acting as the OAuth Client, is responsible for refreshing the credential information and updating the ICE Agent with fresh new credentials before the accessToken expires. The OAuth Client can use the {{RTCPeerConnection.setConfiguration()}} method to periodically refresh the TURN credentials.

The length of the HMAC key ({{RTCOAuthCredential.macKey}}) MAY be any integer number of bytes greater than 20 (160 bits).

According to [[RFC7635]] Section 4.1, the HMAC key MUST be a symmetric key, as asymmetric keys would result in large access tokens which may not fit in a single STUN message.

Currently the STUN/TURN protocols use only SHA-1 and SHA-2 family hash algorithms for Message Integrity Protection, as defined in [[RFC5389]] Section 15.4, and [[STUN-BIS]] Section 14.6.

When setting a configuration and evaluating urls, also run the following step:

  1. If scheme name is turn or turns, and server.{{RTCIceServer/credentialType}} is "oauth", and server.{{RTCIceServer/credential}} is not an {{RTCOAuthCredential}}, then [=exception/throw=] an {{InvalidAccessError}}.

Support for the {{RTCIceCredentialType/"oauth"}} value of {{RTCIceCredentialType}} is marked as a feature at risk, since there is no clear commitment from implementers.

RTCOAuthCredential Dictionary

The {{RTCOAuthCredential}} dictionary is used to describe the OAuth auth credential information which is used by the STUN/TURN client (inside the ICE Agent) to authenticate against a STUN/TURN server, as described in [[RFC7635]]. Note that the kid parameter is not located in this dictionary, but in {{RTCIceServer.username}} member.

Support for the {{RTCOAuthCredential}} dictionary is marked as a feature at risk, since there is no clear commitment from implementers.

dictionary RTCOAuthCredential {
    required DOMString macKey;
    required DOMString accessToken;
};

Dictionary {{RTCOAuthCredential}} Members

macKey of type DOMString, required

The "mac_key", as described in [[RFC7635]], Section 6.2, in a base64-url encoded format. It is used in STUN message integrity hash calculation (as the password is used in password based authentication). Note that the OAuth response "key" parameter is a JSON Web Key (JWK) or a JWK encrypted with a JWE format. Also note that this is the only OAuth parameter whose value is not used directly, but must be extracted from the "k" parameter value from the JWK, which contains the needed base64-encoded "mac_key".

accessToken of type DOMString, required

The "access_token", as described in [[RFC7635]], Section 6.2, in a base64-encoded format. This is an encrypted self-contained token that is opaque to the application. Authenticated encryption is used for message encryption and integrity protection. The access token contains a non-encrypted nonce value, which is used by the Authorization Server for unique mac_key generation. The second part of the token is protected by Authenticated Encryption. It contains the mac_key, a timestamp and a lifetime. The timestamp combined with lifetime provides expiry information; this information describes the time window during which the token credential is valid and accepted by the TURN server.

An example of an RTCOAuthCredential dictionary is:

{
  macKey: 'WmtzanB3ZW9peFhtdm42NzUzNG0=',
  accessToken: 'AAwg3kPHWPfvk9bDFL936wYvkoctMADzQ5VhNDgeMR3+ZlZ35byg972fW8QjpEl7bx91YLBPFsIhsxloWcXPhA=='
}

{{RTCIceServer}} extensions

The {{RTCIceServer}} dictionary is defined in [[WEBRTC]]. This document extends that dictionary by adding the {{RTCIceServer/credential}} attribute, and adds a paragraph to how to interpret the existing {{RTCIceServer/username}} attribute.

partial dictionary RTCIceServer {
    // This attribute is not new in this extension spec, but how to interpret it
    // in the case of credentialType being "oauth" is described here.
    DOMString username;
    (DOMString or RTCOAuthCredential) credential;
};

Dictionary {{RTCIceServer}} Members

username of type {{DOMString}}

How to interpret the {{username}} when this {{RTCIceServer}} object represents a TURN server, and {{RTCIceServer/credentialType}} is {{RTCIceCredentialType/"password"}} is specified in {{RTCIceServer}} of [[WEBRTC]].

If this {{RTCIceServer}} object represents a TURN server, and {{RTCIceServer/credentialType}} is {{RTCIceCredentialType/"oauth"}}, then this attribute specifies the Key ID (kid) of the shared symmetric key, which is shared between the TURN server and the Authorization Server, as described in [[RFC7635]]. It is an ephemeral and unique key identifier. The kid allows the TURN server to select the appropriate keying material for decryption of the Access-Token, so the key identified by this kid is used in the Authenticated Encryption of the "access_token". The kid value is equal with the OAuth response "kid" parameter, as defined in [[RFC7515]] Section 4.1.4.

credential of type (DOMString or {{RTCOAuthCredential}})

If this {{RTCIceServer}} object represents a TURN server, then this attribute specifies the credential to use with that TURN server.

If {{RTCIceServer/credentialType}} is {{RTCIceCredentialType/"password"}}, {{credential}} is a DOMString, and represents a long-term authentication password, as described in [[RFC5389]], Section 10.2.

If {{RTCIceServer/credentialType}} is {{RTCIceCredentialType/"oauth"}}, {{credential}} is an {{RTCOAuthCredential}}, which contains the OAuth access token and MAC key.

If this {{RTCIceServer}} object represents a TURN server, and {{RTCIceServer/credentialType}} is {{RTCIceCredentialType/"oauth"}}, then this attribute specifies the Key ID (kid) of the shared symmetric key, which is shared between the TURN server and the Authorization Server, as described in [[RFC7635]]. It is an ephemeral and unique key identifier. The kid allows the TURN server to select the appropriate keying material for decryption of the Access-Token, so the key identified by this kid is used in the Authenticated Encryption of the "access_token". The kid value is equal with the OAuth response "kid" parameter, as defined in [[RFC7515]] Section 4.1.4.

An example array of {{RTCIceServer}} objects is:

{
  urls: 'turns:turn2.example.net',	
  username: '22BIjxU93h/IgwEb',	
  credential: {	
    macKey: 'WmtzanB3ZW9peFhtdm42NzUzNG0=',	
    accessToken: 'AAwg3kPHWPfvk9bDFL936wYvkoctMADzQ5VhNDgeMR3+ZlZ35byg972fW8QjpEl7bx91YLBPFsIhsxloWcXPhA=='	
  },	
  credentialType: 'oauth'
}

{{RTCRtpContributingSource}} extensions

The {{RTCRtpContributingSource}} dictionary is defined in [[WEBRTC]]. This document extends that dictionary by adding two additional members.

In this section, the capture system refers to the system where media is sourced from and the sender system refers to the system that is sending RTP and RTCP packets to the receiver system where {{RTCRtpContributingSource}} data is populated.

In a direct connection, the capture system is the same as the sender system. But when one or more RTCP-terminating intermediate systems (e.g. mixers) are involved this is not the case. In such cases, media is sourced from the capture system, may be relayed through a number of intermediate systems and is then finally sent from the sender system to the receiver system. The sender system-receiver system path only represents the "last hop".

Despite {{RTCRemoteInboundRtpStreamStats.roundTripTime}} measurements only accounting for the "last hop", one-way delay from the [=capture system=]'s time of capture to the [=receiver system=]'s time of playout can be estimated if the [=RTP Header Extension for Absolute Capture Time=] is used all hops of the way, where each RTCP-terminating intermediate system appropriately updates the [=estimated capture clock offset=].

partial dictionary RTCRtpContributingSource {
      DOMHighResTimeStamp captureTimestamp;
      DOMHighResTimeStamp senderCaptureTimeOffset;
    };

Dictionary {{RTCRtpContributingSource}} Members

captureTimestamp of type {{DOMHighResTimeStamp}}.

The {{captureTimestamp}} is the timestamp that, the most recent frame (from an RTP packet originating from this source) delivered to the {{RTCRtpReceiver}}'s {{MediaStreamTrack}}, was originally captured. Its reference clock is the capture system's NTP clock (same clock used to generate NTP timestamps for RTCP sender reports on that system).

On populating this member, the user agent MUST run the following steps:

  1. If the relevant RTP packet contains the RTP Header Extension for Absolute Capture Time, return the value of the absolute capture timestamp field and abort these steps.

  2. Otherwise, if the relevant RTP packet does not contain the RTP Header Extension for Absolute Capture Time but a previous RTP packet did, return the result of calculating the absolute capture timestamp according to timestamp interpolation and abort these steps.

  3. Otherwise, return undefined.

If multiple receiving tracks are sourced from the same capture system, two {{captureTimestamp}}s can be used to accurately measure audio-video synchronization since both timestamps are based on the same system's clock.

senderCaptureTimeOffset of type {{DOMHighResTimeStamp}}.

The {{senderCaptureTimeOffset}} is the sender system's estimate of the offset between its own NTP clock and the capture system's NTP clock, for the same frame that the {{captureTimestamp}} was originated from.

On populating this member, the user agent MUST run the following steps:

  1. If the relevant RTP packet contains the RTP Header Extension for Absolute Capture Time and the estimated capture clock offset field is present, return the value of the estimated capture clock offset field and abort these steps.

  2. Otherwise, if the relevant RTP packet does not contain the RTP Header Extension for Absolute Capture Time's estimated capture clock offset field, but a previous RTP packet did, return the most recent value that was present and abort these steps.

  3. Otherwise, return undefined.

The time of capture can estimatedly be expressed in the sender system's clock as follows: senderCaptureTimestamp = {{captureTimestamp}} + {{senderCaptureTimeOffset}}.

The offset between the sender system's clock and the receiver system's clock can be estimated as follows: senderReceiverTimeOffset = {{RTCRemoteOutboundRtpStreamStats}}.timestamp}} - ({{RTCRemoteOutboundRtpStreamStats.remoteTimestamp}} + {{RTCRemoteInboundRtpStreamStats.roundTripTime}} / 2).

The time of capture can estimatedly be expressed in the receiver system's clock as follows: receiverCaptureTimestamp = senderCaptureTimestamp + senderReceiverTimeOffset.

The one-way delay between the capture system's time of capture and the receiver system's time of playout can be estimated as follows: {{RTCRtpContributingSource.timestamp}} - receiverCaptureTimestamp.

{{RTCRtpSynchronizationSource}} extensions

This document extends {{RTCRtpSynchronizationSource}} with a {{RTCRtpSynchronizationSource/voiceActivityFlag}} member (initially defined in the WebRTC 1.0 specification but later dropped due to lack of implementation).

    partial dictionary RTCRtpSynchronizationSource {
    boolean voiceActivityFlag;
    };
voiceActivityFlag of type boolean

Only present for audio receivers. Whether the last RTP packet, delivered from this source, contains voice activity (true) or not (false). If the RFC 6464 extension header was not present, or if the peer has signaled that it is not using the V bit by setting the "vad" extension attribute to "off", as described in [[!RFC6464]], Section 4, {{voiceActivityFlag}} will be absent.

{{RTCRtpSynchronizationSource/voiceActivityFlag}} is marked as a feature at risk, since there is no clear commitment from implementers.

{{RTCDataChannel}} extensions

This document extends {{RTCDataChannel}} by making it transferable.

This allows sending and receiving messages outside the context the connection was created, for instance in workers or third-party iframes.

The WebIDL changes are the following:

[Exposed=(Window,Worker), Transferable]
partial interface RTCDataChannel {
};

The create an RTCDataChannel algorithm is updated by adding the following steps after step 4 of the original algorithm:

  1. Initialize channel.`[[IsTransferable]]` to true.

  2. Queue a task to run the following step:

    1. Set channel.`[[IsTransferable]]` to false.

This task needs to run before any task enqueued by the receiving messages on a data channel algorithm for channel. This ensures that no message is lost during the transfer of a {{RTCDataChannel}}.

The send() algorithm is modified by adding the following step after step 1 of the original algorithm:
  1. Set channel.`[[IsTransferable]]` to false.

The {{RTCDataChannel}} transfer steps, given value and dataHolder, are:

  1. If value.`[[IsTransferable]]` is false, throw a "DataCloneError" DOMException.

  2. Set dataHolder.`[[ReadyState]]` to value.`[[ReadyState]]`.

  3. Set dataHolder.`[[DataChannelLabel]]` to value.`[[DataChannelLabel]]`.

  4. Set dataHolder.`[[Ordered]]` to value.`[[Ordered]]`.

  5. Set dataHolder.`[[MaxPacketLifeTime]]` to value..`[[MaxPacketLifeTime]]`

  6. Set dataHolder.`[[MaxRetransmits]]` to value.`[[MaxRetransmits]]`.

  7. Set dataHolder.`[[DataChannelProtocol]]` to value.`[[DataChannelProtocol]]`.

  8. Set dataHolder.`[[Negotiated]]` to value.`[[Negotiated]]`.

  9. Set dataHolder.`[[DataChannelId]]` to value.`[[DataChannelId]]`.

  10. Set dataHolder.`[[underlyingDataTransport]]` to value underlying data transport.

  11. Set value.`[[IsTransferable]]` to false.

  12. Set value.`[[ReadyState]]` to "closed".

The {{RTCDataChannel}} transfer-receiving steps, given dataHolder and channel, are:

  1. Initialize channel.`[[ReadyState]]` to dataHolder.`[[ReadyState]]`.

  2. Initialize channel.`[[DataChannelLabel]]` to dataHolder.`[[\DataChannelLabel]]`.

  3. Initialize channel.`[[Ordered]]` to dataHolder.`[[Ordered]]`.

  4. Initialize channel.`[[MaxPacketLifeTime]]` to dataHolder.`[[MaxPacketLifeTime]]`.

  5. Initialize channel.`[[MaxRetransmits]]` to dataHolder.`[[MaxRetransmits]]`.

  6. Initialize channel.`[[DataChannelProtocol]]` to dataHolder.`[[DataChannelProtocol]]`.

  7. Initialize channel.`[[Negotiated]]` to dataHolder.`[[Negotiated]]`.

  8. Initialize channel.`[[DataChannelId]]` to dataHolder.`[[DataChannelId]]`.

  9. Initialize channel underlying data transport to dataHolder.`[[underlyingDataTransport]]`.

The above steps do not need to transfer `[[BufferedAmount]]` as its value will always be equal to 0. The reason is an {{RTCDataChannel}} can be transferred only if its send() algorithm was not called prior the transfer.

If the underlying data transport is closed at the time of the transfer-receiving steps, the {{RTCDataChannel}} object will be closed by running the announcing a data channel as closed algorithm immediately after the transfer-receiving steps.

Security Considerations

This section is non-normative; it specifies no new behaviour. The overall security considerations of the general set of APIs and protocols used in WebRTC are described in [[?RFC8827]].

Impact on local network

The extensions defined in this document do not provide additional impact on the local network beyond what is described in [[WEBRTC]] Section 13.3.

Confidentiality of Communications

This document defines extensions for encryption of RTP Header Extensions which improve the confidentiality of communications by encrypting header extension IDs, as well as CSRCs.

Privacy Considerations

This section is non-normative; it specifies no new behaviour.

Revealing IP addresses

The extensions defined in this document do not reveal additional information on IP addresses beyond that already described in [[WEBRTC]] Section 13.2.

Persistent information exposed by WebRTC

The extensions defined in this document do not provide additional persistent information beyond that which is discussed in [[WEBRTC]] Section 13.5.

Accessibility Considerations

The WebRTC 1.0 specification exposes an API to control protocols (defined within the IETF) necessary to establish real-time audio, video and data exchange. Real-Time Text, defined in [[RFC4103]], is supported via the data channel API as described in [[WEBRTC]] Section 14. The extensions defined in this document do not affect support for Real-Time Text.

Acknowledgements

The editors wish to thank the Working Group chairs and Team Contact, Dominique Hazaƫl-Massieux, for their support. Substantial text in this specification was provided by many people including Harald Alvestrand, Justin Uberti and Peter Thatcher.

The {{RTCRtpSender}} and {{RTCRtpReceiver}} objects were initially described in the W3C ORTC CG, and have been adapted for use in this specification.