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]]}}.

Dictionary {{RTCRtpEncodingParameters}} Members

scaleResolutionDownTo of type {{RTCResolutionRestriction}}

The maximum dimensions at which to restrict this encoding.

When {{scaleResolutionDownTo}} is specified, the {{RTCRtpEncodingParameters/scaleResolutionDownBy}} value MUST be ignored. Instead, frames are sent according to the specified resolution restrictions: frames MUST NOT be upscaled.

When configuring parameters, the following validation MUST be performed if {{scaleResolutionDownTo}} is specified on any encoding or else {{RTCPeerConnection/addTransceiver()}} [= exception/throws =] a newly [= exception/created =] {{OperationError}} and {{RTCRtpSender/setParameters()}} [= reject|rejects =] with a newly [= exception/created =] {{InvalidModificationError}}:

• {{scaleResolutionDownTo}} is specified on all {{RTCRtpEncodingParameters/active}} encodings.

• For each {{scaleResolutionDownTo}} value, both dimensions have a value greater than 0.

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.

Dictionary {{RTCResolutionRestriction}} Members

maxWidth of type unsigned long

The maximum width that frames will be encoded with. The restrictions are orientation agnostic, see note below. When scaling is applied, both dimensions of the frame MUST be downscaled using the same factor.

maxHeight of type unsigned long

The maximum height that frames will be encoded with. The restrictions are orientation agnostic, see note below. When scaling is applied, both dimensions of the frame MUST be downscaled using the same factor.

The restrictions being orientation agnostic means that they will automatically be adjusted to the orientation of the frame being restricted (portrait mode or landscape mode) by swapping width and height if necessary. This means that it does not matter if 1280x720 or 720x1280 is specified, both always result in the exact same scaling factor regardless of the orientation of the frame.

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}}, and is fired as part of the [= add a candidate pair =] algorithm.

onicecandidatepairremove of type {{EventHandler}}

The event type of this event handler is {{icecandidatepairremove}}, and is fired as part of the [= remove a candidate pair =] algorithm.

onicecandidatepairnominate of type {{EventHandler}}

The event type of this event handler is {{icecandidatepairnominate}}, and is fired as part of the [= nominate a candidate pair =] algorithm.

Methods

selectCandidatePair

The {{selectCandidatePair}} method attempts to select a different candidate pair to send data over. If successful, data will be sent on the provided candidate pair. It is meant to be called after the application defers the {{nomination}} of a candidate pair by cancelling the {{RTCIceTransport/icecandidatepairnominate}} event.

When this method is invoked, the [= user agent =] MUST run the following steps:

1. Let |connection:RTCPeerConnection| be the {{RTCPeerConnection}} object associated with [=this=].

2. If connection.{{RTCPeerConnection/[[IsClosed]]}} is true, [= exception/throw =] an {{InvalidStateError}}.

3. If [=this=].{{RTCIceTransport/[[ProposalPending]]}} is true, [= exception/throw =] an {{InvalidStateError}}.

4. If [=this=].{{RTCIceTransport/[[IceTransportState]]}} is either of {{RTCIceTransportState/"new"}}, {{RTCIceTransportState/"failed"}} or {{RTCIceTransportState/"closed"}}, [= exception/throw =] an {{InvalidStateError}}.

5. Let |candidatePair:RTCIceCandidatePair| be the method's first argument.

6. If |candidatePair| does not [= candidate pair match | match =] any item in [=this=]. {{RTCIceTransport/[[CandidatePairs]]}}, [= exception/throw =] a {{NotFoundError}}.

7. Let |p:Promise| be a new promise.

8. In parallel, instruct the [= ICE agent =] to use |candidatePair| to send data.

   1. When the [= ICE agent =] has completed selecting |candidatePair|, [= queue a task =] to run the following steps:

      1. Run the [=RTCIceTransport/change the selected candidate pair and state=] steps to update [=this=].{{RTCIceTransport/[[SelectedCandidatePair]]}} and [=this=].{{RTCIceTransport/[[IceTransportState]]}} as necessary and fire any associated events.

      2. Resolve p.

9. Return p.

After changing the selected candidate pair, the controlling [= ICE agent =] may attempt to [= nominate the candidate pair =] as well to conclude ICE processing. The application may cancel the nomination to allow further changes to the selected candidate pair.

removeCandidatePair

The {{removeCandidatePair}} method removes the provided candidate pair. The [= ICE agent =] will stop sending and responding to ICE connectivity checks on the removed candidate pair, and it can no longer be used to send data for this transport. This method is meant to be called when the application wants to allow the [= ICE agent =] to [= free =] candidates that it no longer needs.

When this method is invoked, the [= user agent =] MUST run the following steps:

1. Let |connection:RTCPeerConnection| be the {{RTCPeerConnection}} object associated with [= this =].

2. If connection.{{RTCPeerConnection/[[IsClosed]]}} is true, [= exception/throw =] an {{InvalidStateError}}.

3. If [= this =].{{RTCIceTransport/[[ProposalPending]]}} is true, [= exception/throw =] an {{InvalidStateError}}.

4. If [= this =].{{RTCIceTransport/[[IceTransportState]]}} is either of {{RTCIceTransportState/"new"}}, {{RTCIceTransportState/"failed"}} or {{RTCIceTransportState/"closed"}}, [= exception/throw =] an {{InvalidStateError}}.

5. Let |candidatePair:RTCIceCandidatePair| be the method's first argument.

6. If |candidatePair| does not [= candidate pair match | match =] any item in [=this=]. {{RTCIceTransport/[[CandidatePairs]]}}, [= exception/throw =] a {{NotFoundError}}.

7. [= list/Remove =] the item in [=this=].{{RTCIceTransport/[[CandidatePairs]]}} that [= candidate pair match | matches =] |candidatePair|.

8. Let |p:Promise| be a new promise.

9. In parallel, instruct the [= ICE agent =] to remove the candidate pair indicated by candidatePair.

   1. When the [= ICE agent =] has completed the removal, [= queue a task =] to run the following steps:

      1. [= Fire an event =] named {{RTCIceTransport/icecandidatepairremove}} at |transport|, using {{RTCIceCandidatePairEvent}}, with the {{Event/cancelable}} attribute initialized to false, and the {{RTCIceCandidatePairEvent/local}} and {{RTCIceCandidatePairEvent/remote}} attributes initialized to the {{RTCIceCandidatePair/local}} and {{RTCIceCandidatePair/remote}} candidates, respectively, of candidatePair.

      2. Resolve p.

10. Return p.

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 exposing it to any type of {{Worker}} (not just DedicatedWorker).

  [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 [[RFC9335]]. If the remote endpoint supports [[RFC9335]], all media streams are sent utilizing [[RFC9335]].

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

{{RTCRtpTransceiver}} interface extensions

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

partial interface RTCRtpTransceiver {
  readonly attribute boolean rtpHeaderEncryptionNegotiated;
};

{{RTCConfiguration}} extensions

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

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".