WebRTC Extensions

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.

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.

WebIDLpartial dictionary RTCRtpHeaderExtensionCapability {
  required RTCRtpTransceiverDirection direction;
};

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

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

1. If transceivers of the same kind exist in the current PeerConnection, copy [[HeaderExtensionsToNegotiate]] from the first such transceiver, in the order defined by the CollectTransceivers algorithm. This ensures consistency across transceivers if they are added after initial negotiation.

   If no such transceiver exists, set [[HeaderExtensionsToNegotiate]] 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 direction attribute for extensions that will not be offered by default in an initial offer MUST be initialized to "stopped".

   If there are header extensions whose state needs to be consistent across all transceivers in a bundle, and any other transceiver exists that will be included in the same bundle, copy the direction attribute for that extension from that other transceiver.

   Note

   An example of header extensions that need to be identical across all media sections is the key management extensions from [RFC4567], as described in section 5.35 of [RFC8859], where they have category IDENTICAL. If this is supported and negotiated as "sendrecv", and a new transceiver is added, that transceiver needs to also have the extension as "sendrecv".

   Note

   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 [[NegotiatedHeaderExtensions]] to an empty list.

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

• In the step for processing a description of type "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.[[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 "stopped".

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

     3. If this extension cannot be used because of other options negotiated in the answer, set answeredDirection to "stopped".

     4. Set extension.direction to answeredDirection.

  3. Set transceiver.[[NegotiatedHeaderExtensions]] to negotiatedExtensions.

  4. Set transceiver.[[HeaderExtensionsToNegotiate]] to negotiatedExtensions. This ensures that unless further calls to setHeaderExtensionsToNegotiate are done, subsequent offer/answer will not alter the list of extensions.

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 [[HeaderExtensionsToNegotiate]] where direction is not "stopped", an "a=extmap" line, as specified in [RFC5285], section 5, with direction taken from "e"'s 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 [[HeaderExtensionsToNegotiate]], and where direction is not "stopped", generate an appropriate "a=extmap" line with "direction" set according to the rules of [RFC5285] section 6, considering the direction in [[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 [[HeaderExtensionsToNegotiate]] with a direction different from "stopped", set the appropriate direction based on direction that does not exceed the direction in the offer".

getHeaderExtensionsToNegotiate

Execute the following steps:

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

2. Return transceiver.[[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.[[HeaderExtensionsToNegotiate]] 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.uri is not equal to the uri of the i-th element of transceiver.[[HeaderExtensionsToNegotiate]], throw an InvalidModificationError.

   3. If extension.direction is not "sendrecv" and uri indicates a mandatory-to-use attribute that is required to be both sent and received, throw an InvalidModificationError.

   4. If extension.direction is "stopped" and uri indicates a mandatory-to-implement extension, throw an InvalidModificationError.

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

5. Set transceiver.[[HeaderExtensionsToNegotiate]] to extensions.

getNegotiatedHeaderExtensions

Execute the following steps:

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

2. Return transceiver.[[NegotiatedHeaderExtensions]].

scaleResolutionDownTo of type RTCResolutionRestriction

The maximum dimensions at which to restrict this encoding.

When scaleResolutionDownTo is specified, the 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 addTransceiver() throws a newly created OperationError and setParameters() rejects with a newly created InvalidModificationError:

• scaleResolutionDownTo is specified on all 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.

(Feature at Risk) Issue 1

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

Note

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.

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.

Note

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.

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.

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.

In the steps to call the 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 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 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.

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.

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 icecandidatepairnominate event.

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

1. Let connection be the RTCPeerConnection object associated with this.

2. If connection.[[IsClosed]] is true, throw an InvalidStateError.

3. If this.[[ProposalPending]] is true, throw an InvalidStateError.

4. If this.[[IceTransportState]] is either of "new", "failed" or "closed", throw an InvalidStateError.

5. Let candidatePair be the method's first argument.

6. If this.[[CandidatePairs]] does not contain candidatePair, throw a NotFoundError.

7. Let p 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 change the selected candidate pair and state steps to update this.[[SelectedCandidatePair]] and this.[[IceTransportState]] as necessary and fire any associated events.

      2. Resolve p.

9. Return p.

Note

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 be the RTCPeerConnection object associated with this.

2. If connection.[[IsClosed]] is true, throw an InvalidStateError.

3. If this.[[ProposalPending]] is true, throw an InvalidStateError.

4. If this.[[IceTransportState]] is either of "new", "failed" or "closed", throw an InvalidStateError.

5. Let candidatePair be the method's first argument.

6. If this.[[CandidatePairs]] does not contain candidatePair, throw a NotFoundError.

7. Remove candidatePair from this.[[CandidatePairs]].

8. Let p 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 icecandidatepairremove at transport, using RTCIceCandidatePairEvent, with the cancelable attribute initialized to false, and the candidatePair attribute initialized to candidatePair.

      2. Resolve p.

10. Return p.

The icecandidatepairadd, icecandidatepairnominate and icecandidatepairremove events use the RTCIceCandidatePairEvent interface.

WebIDL[Exposed=Window]
  interface RTCIceCandidatePairEvent : Event {
    constructor(DOMString type, RTCIceCandidatePairEventInit eventInitDict);
    readonly attribute RTCIceCandidatePair candidatePair;
  };

WebIDLdictionary RTCIceCandidatePairEventInit : EventInit {
  required RTCIceCandidatePair candidatePair;
};

In the steps to change the selected candidate pair and state, if the selected candidate pair was changed, modify the first step to the following:

1. Let newCandidatePair be the item contained in this.[[CandidatePairs]] whose local and remote attributes respectively match the local and remote candidates of the indicated pair if one is selected, and null otherwise.

The candidate match algorithm given two RTCIceCandidate first and second is as follows:

1. If first.candidate is not identical to second.candidate, return false.

2. If either (but not both) of first.sdpMid and second.sdpMid is null, return false.

3. If neither of first.sdpMid and second.sdpMid is null, and first.sdpMid is not identical to second.sdpMid, return false.

4. If either (but not both) of first.sdpMLineIndex and second.sdpMLineIndex is null, return false.

5. If neither of first.sdpMLineIndex and second.sdpMLineIndex is null and first.sdpMLineIndex is not equal to second.sdpMLineIndex, return false.

6. If either (but not both) of first.usernameFragment and second.usernameFragment is null, return false.

7. If neither of first.usernameFragment and second.usernameFragment is null and first.usernameFragment is not identical to second.usernameFragment, return false.

8. Return true.

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 Absolute Capture Timestamp RTP header extension, return the value of the absolute capture timestamp field and abort these steps.

2. Otherwise, if the relevant RTP packet does not contain the Absolute Capture Timestamp RTP header extension 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.

Note

If multiple receiving tracks are sourced from the same capture system, two captureTimestamps 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 Absolute Capture Timestamp RTP header extension 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 Absolute Capture Timestamp RTP header extension'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.

Note

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

Note

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

Note

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

Note

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.

This section extends RTCDataChannel by exposing it to any type of Worker (not just DedicatedWorker).

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

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

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

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

WebIDLpartial interface RTCRtpTransceiver {
  readonly attribute boolean rtpHeaderEncryptionNegotiated;
};

rtpHeaderEncryptionPolicy defines the policy for negotiation of RTP header encryption using [RFC9335].

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

onssrcchange of type EventHandler

Fired when the source in getSynchronizationSources() changes, see above.

oncsrcchange of type EventHandler

Fired when the source in getContributingSources() changes, see above.

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

WebIDLpartial 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 [[HardwareDisabled]] slot to true.

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

WebIDLpartial 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 [[HardwareDisabled]] slot to true.

In the set a session description algorithm, add a step right after the step that sets transceiver.[[Receiver]].[[ReceiveCodecs]], saying "If the RTCRtpReceiver's [[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 [[HardwareDisabled]] slot is true, remove any codec from transceiver.[[Sender]].[[SendCodecs]] for which the underlying encoder is hardware-accelerated".