Modifications to existing procedures

Append the following paragraph to the administratively prohibited algorithm:

If should RTC connections be blocked for global? with the [=relevant global object=] of the {{RTCPeerConnection}} object in question returns `"Blocked"`, then all candidates MUST be administratively prohibited.

{{RTCRtpTransceiver}} interface 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 {
  required RTCRtpTransceiverDirection direction;
};

partial interface RTCRtpTransceiver {
  sequence<RTCRtpHeaderExtensionCapability> getHeaderExtensionsToNegotiate();
  undefined setHeaderExtensionsToNegotiate(
      sequence<RTCRtpHeaderExtensionCapability> extensions);
  sequence<RTCRtpHeaderExtensionCapability> getNegotiatedHeaderExtensions();
};
      

Let {{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}} and {{RTCRtpTransceiver/[[NegotiatedHeaderExtensions]]}} be internal slots of the {{RTCRtpTransceiver}}, initialized as follows:

1. Set {{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}} to the platform-specific list of implemented RTP header extensions. The {{RTCRtpHeaderExtensionCapability/direction}} attribute for all extensions that are mandatory to use MUST be initialized to an appropriate value other than {{RTCRtpTransceiverDirection/"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.

2. Set {{RTCRtpTransceiver/[[NegotiatedHeaderExtensions]]}} to an empty list.

Modifications to existing procedures

Make the following modifications to the set a session description algorithm:

• In the step for processing a description of type {{RTCSdpType/"answer"}} that runs for both local and remote descriptions, insert the following steps:

  1. For each media description and corresponding transceiver, let negotiatedExtensions be the value of transceiver.{{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}}.

  2. For each extension in negotiatedExtensions, run the following steps:

     1. Let answeredDirection be the direction attribute of the "a=extmap" line in the answer's media description that correspond to this extension if one exists, otherwise set answeredDirection to {{RTCRtpTransceiverDirection/"stopped"}}.

     2. If description is a remote description, reverse answeredDirection to represent the peer's point of view.

     3. Set extension.{{RTCRtpHeaderExtensionCapability/direction}} to answeredDirection.

  3. Set transceiver.{{RTCRtpTransceiver/[[NegotiatedHeaderExtensions]]}} to negotiatedExtensions.

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/[[HeaderExtensionsToNegotiate]]}} 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/[[HeaderExtensionsToNegotiate]]}}, 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/[[HeaderExtensionsToNegotiate]]}} 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/[[HeaderExtensionsToNegotiate]]}} with a {{RTCRtpHeaderExtensionCapability/direction}} different from {{RTCRtpTransceiverDirection/"stopped"}}, set the appropriate direction based on {{RTCRtpHeaderExtensionCapability/direction}} that does not exceed the direction in the offer".

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

Methods

getHeaderExtensionsToNegotiate

Execute the following steps:

1. Let transceiver be the {{RTCRtpTransceiver}} that this method was invoked on.

2. Return transceiver.{{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}}.

setHeaderExtensionsToNegotiate

Execute the following steps:

1. Let transceiver be the {{RTCRtpTransceiver}} that this method was invoked on.

2. Let extensions be the first argument of this method.

3. If the size of extensions does not match the size of transceiver.{{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}} [=exception/throw=] an {{InvalidModificationError}}.

4. For each index i of extensions, run the following steps:

   1. Let extension be the i-th element of extensions.

   2. If extension.{{RTCRtpHeaderExtensionCapability/uri}} is not equal to the {{RTCRtpHeaderExtensionCapability/uri}} of the i-th element of transceiver.{{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}}, [=exception/throw=] an {{InvalidModificationError}}.

   3. If extension.{{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}}.

   4. If extension.{{RTCRtpHeaderExtensionCapability/direction}} is {{RTCRtpTransceiverDirection/"stopped"}} and {{RTCRtpHeaderExtensionCapability/uri}} indicates a mandatory-to-implement extension, [=exception/throw=] an {{InvalidModificationError}}.

   5. If necessary, restrict extension.{{RTCRtpHeaderExtensionCapability/direction}} as to not exceed the user agent's capabilities for this extension.

5. Set transceiver.{{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}} to extensions.

getNegotiatedHeaderExtensions

Execute the following steps:

1. Let transceiver be the {{RTCRtpTransceiver}} that this method was invoked on.

2. Return transceiver.{{RTCRtpTransceiver/[[NegotiatedHeaderExtensions]]}}.

Modification to existing procedures

Let {{RTCRtpReceiver}} objects have a [[\JitterBufferTarget]] internal slot initially initialized to null.

{{RTCRtpReceiver}} interface extensions

partial interface RTCRtpReceiver {
  attribute DOMHighResTimeStamp? jitterBufferTarget;
};

Attributes

jitterBufferTarget of type DOMHighResTimeStamp, nullable

This attribute allows the application to specify a target duration of time in milliseconds of media for the {{RTCRtpReceiver}}'s jitter buffer to hold. This influences the amount of buffering done by the user agent, which in turn affects retransmissions and packet loss recovery. Altering the target value allows applications to control the tradeoff between playout delay and the risk of running out of audio or video frames due to network jitter.

The user agent MUST have a minimum allowed target and a maximum allowed target reflecting what the user agent is able or willing to provide based on network conditions and memory constraints, which can change at any time.

This is a target value. The resulting change in delay can be gradually observed over time. The receiver's average jitter buffer delay can be measured as the delta {{RTCInboundRtpStreamStats/jitterBufferDelay}} divided by the delta {{RTCInboundRtpStreamStats/jitterBufferEmittedCount}}.

An average delay is expected even if DTX is used. For example, if DTX is used and packets start flowing after silence, larger targets can influence the user agent to buffer these packets rather than playing them out.

On getting, this attribute MUST return the value of the {{RTCRtpReceiver/[[JitterBufferTarget]]}} 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 target be the argument to the setter.

3. If target is negative or larger than 4000 milliseconds, then [=exception/throw=] a {{RangeError}}.

4. Set receiver's {{RTCRtpReceiver/[[JitterBufferTarget]]}} to target.

5. Let track be receiver's {{RTCRtpReceiver/[[ReceiverTrack]]}}.

6. In parallel, begin executing the following steps:

   1. Update the underlying system about the new target, or that there is no application preference if target is null.

      If track is synchronized with another {{RTCRtpReceiver}}'s track for audio/video synchronization, then the user agent SHOULD use the larger of the two receivers' {{RTCRtpReceiver/[[JitterBufferTarget]]}} for both receivers.

      When the underlying system is applying a jitter buffer target, it will continuously make sure that the actual jitter buffer target is clamped within the minimum allowed target and maximum allowed target.

      If the user agent ends up using a target different from the requested one (e.g. due to network conditions or physical memory constraints), this is not reflected in the {{RTCRtpReceiver/[[JitterBufferTarget]]}} internal slot.

   2. Modifying the jitter buffer target 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.

Dictionary {{RTCRtpEncodingParameters}} Members

ptime of type unsigned long

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

{{RTCRtpEncodingParameters/ptime}} was moved from [[WEBRTC]] to this specification due to lack of support from implementers. It is therefore marked as a feature at risk.

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.

codec of type RTCRtpCodec

Optional value selecting which codec is used for this encoding's RTP stream. The {{RTCRtpCodec}} dictionary is defined in [[WEBRTC]]. If [=map/exists|absent=], the user agent can chose to use any negotiated codec.

Modifications to existing procedures

setParameters()

Add the following steps to the [=RTCRtpSender/setParameters validation steps=]:

1. Let choosableCodecs be parameters.{{RTCRtpParameters/codecs}}.

2. If choosableCodecs is an empty list, set choosableCodecs to transceiver.{{RTCRtpTransceiver/[[PreferredCodecs]]}}.

3. If choosableCodecs is still an empty list, set choosableCodecs to the [=RTCRtpSender/list of implemented send codecs=] for transceiver's kind.

4. If any encoding in encodings [=map/exists|contains=] a codec [= codec match | not found =] in choosableCodecs, return a promise [= rejected =] with a newly [= exception/created =] {{InvalidModificationError}}.

5. If the user agent does not support setting the codec for any encoding or mixing different codec values on the different encodings, return a promise [= rejected =] with a newly [= exception/created =] {{OperationError}}.

addTransceiver()

Add the following steps to the [=RTCPeerConnection/addTransceiver sendEncodings validation steps=]:

1. If any codec parameter in sendEncodings does [= codec match | not match =] any codec in {{RTCRtpSender.getCapabilities(kind)}}.codecs, [= exception/throw =] an {{OperationError}}.

2. If the user agent does not support changing codecs without negotiation or does not support setting codecs for individual encodings, return a promise [= rejected =] with a newly [= exception/created =] {{OperationError}}.

Set the session description

Append the following steps to the set the session description algorithm:

1. For each transceiver in connection's [= set of transceivers =]:

   1. Let codecs be transceiver.{{RTCRtpTransceiver/[[Sender]]}}.{{RTCRtpSender/[[SendCodecs]]}}.

   2. If codecs is not an empty list:

      1. Remove any codec value in transceiver.{{RTCRtpTransceiver/[[Sender]]}}.{{RTCRtpSender/[[SendEncodings]]}} that does not [= codec match | match =] any entry in codecs.

Dictionary {{RTCSetParameterOptions}} Members

The {{RTCSetParameterOptions}} are extended by a sequence of {{RTCEncodingOptions}}, one for each encoding.

encodingOptions of type sequence<{{RTCEncodingOptions}}>, defaulting to [].

A sequence containing encoding options for each RTP encoding.

Dictionary {{RTCEncodingOptions}} Members

{{RTCEncodingOptions}} is the WebRTC equivalent of {{VideoEncoderEncodeOptions}} in [[WebCodecs]].

keyFrame of type boolean, defaulting to false.

When set to true, request that RTCRtpSender's encoder generates a keyframe for the encoding. The semantic of this boolean is similar to the RTCP FIR message described in [RFC5104], section 3.5.1.

{{RTCRtpSender}} {{RTCRtpSender/setParameters()}} modifications to existing procedures

In the steps to call the {{RTCRtpSender/setParameters()}} method, let parameters be the method's first argument and let setParameterOptions be the method's second argument.

Append the following steps after the steps to validate the parameters:

• If the [=RTCRtpTransceiver/transceiver kind=] of the associated kind is `"audio"`, set setParameterOptions.encodingOptions to the empty list.

• If setParameterOptions.encodingOptions is not empty and setParameterOptions.encodingOptions.length is different from parameters.encodings.length, return a promise [= rejected =] with a newly [= exception/created =] {{InvalidModificationError}}.

In the steps to configure the media stack to use parameters, append the following step:

• For each setParameterOptions.encodingOptions indexed by i, if setParameterOptions.encodingOptions[i].keyFrame is set to true, request that the encoder associated with parameters.encodings[i] generates a key frame.

{{RTCRtpSender/setParameters()}} does not wait for a key frame to be produced by the encoder.

Attributes

onicecandidatepairadd of type {{EventHandler}}

The event type of this event handler is {{icecandidatepairadd}}.

When the [= ICE agent =] has formed a candidate pair, the [= user agent =] MUST queue a task to [= fire an event =] named {{icecandidatepairadd}} using the {{RTCIceCandidatePairEvent}} interface, with the {{RTCIceCandidatePairEvent/local}} and {{RTCIceCandidatePairEvent/remote}} attributes set to the local and remote candidates, respectively, of the formed candidate pair.

onicecandidatepairremove of type {{EventHandler}}

The event type of this event handler is {{icecandidatepairremove}}.

When the [= ICE agent =] has picked a candidate pair to remove, but before the removal has actually occurred, the [= user agent =] MUST run the steps to [= remove a candidate pair =].

RTCIceCandidatePairEvent

The {{RTCIceTransport/icecandidatepairadd}} and {{RTCIceTransport/icecandidatepairremove}} events use the {{RTCIceCandidatePairEvent}} interface.

[Exposed=Window]
interface RTCIceCandidatePairEvent : Event {
  constructor(DOMString type, RTCIceCandidatePairEventInit eventInitDict);
  readonly attribute RTCIceCandidate local;
  readonly attribute RTCIceCandidate remote;
};

dictionary RTCIceCandidatePairEventInit : EventInit {
  required RTCIceCandidate local;
  required RTCIceCandidate remote;
};

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.

Transferable Data Channels

This section 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.

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

RTCRtpHeaderEncryptionPolicy Enum

RTP header extension encryption policy affects whether RTP header extension encryption is negotiated if the remote endpoint does not support [[CRYPTEX]]. If the remote endpoint supports [[CRYPTEX]], all media streams are sent utilizing [[CRYPTEX]].

enum RTCRtpHeaderEncryptionPolicy {
  "negotiate",
  "require"
};

{{RTCRtpTransceiver}} interface extensions

{{RTCRtpTransceiver/rtpHeaderEncryptionNegotiated}} defines whether the transceiver is sending enrypted RTP header extensions as defined in [[CRYPTEX]].

partial interface RTCRtpTransceiver {
  readonly attribute boolean rtpHeaderEncryptionNegotiated;
};

{{RTCConfiguration}} extensions

{{RTCConfiguration/rtpHeaderEncryptionPolicy}} defines the policy for negotiation of RTP header encryption using [[CRYPTEX]].

partial dictionary RTCConfiguration {
  RTCRtpHeaderEncryptionPolicy rtpHeaderEncryptionPolicy = "negotiate";
};

{{RTCRtpReceiver}} extensions

The {{RTCRtpReceiver}} interface is defined in [[WEBRTC]]. This document extends this interface by adding a static method and internal slot {{RTCRtpReceiver/[[HardwareDisabled]]}} initialized to false.

partial interface RTCRtpReceiver {
  static undefined disableHardwareDecoding();
};

When the {{RTCRtpReceiver}}'s disableHardwareDecoding method is called, the user agent MUST run the following steps:

1. When the RTCPeerConnection.constructor() has been invoked abort these steps.

2. Set the RTCRtpReceiver's {{RTCRtpReceiver/[[HardwareDisabled]]}} slot to true.

{{RTCRtpSender}} extensions

The {{RTCRtpSender}} interface is defined in [[WEBRTC]]. This document extends this interface by adding a static method and internal slot {{RTCRtpSender/[[HardwareDisabled]]}} initialized to false.

partial interface RTCRtpSender {
  static undefined disableHardwareEncoding();
};

When the {{RTCRtpSender}}'s disableHardwareEncoding method is called, the user agent MUST run the following steps:

1. When the RTCPeerConnection.constructor() has been invoked abort these steps.

2. Set the RTCRtpSender's {{RTCRtpSender/[[HardwareDisabled]]}} slot to true.

Modifications to existing procedures

In the set a session description algorithm, add a step right after the step that sets transceiver.[[\Receiver]].[[\ReceiveCodecs]], saying "If the RTCRtpReceiver's {{RTCRtpReceiver/[[HardwareDisabled]]}} slot is true, remove any codec from transceiver.[[\Receiver]].[[\ReceiveCodecs]] for which the underlying decoder is hardware-accelerated".

In the set a session description algorithm, add a step right after the step that sets transceiver.[[\Sender]].[[\SendCodecs]], saying "If the RTCRtpSender's {{RTCRtpSender/[[HardwareDisabled]]}} slot is true, remove any codec from transceiver.[[\Sender]].[[\SendCodecs]] for which the underlying encoder is hardware-accelerated".