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.

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

   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.

Modifications to existing procedures

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. Set extension.direction to answeredDirection.

  3. Set transceiver.[[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 [[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".

Methods

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

Dictionary RTCRtpEncodingParameters Members

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.

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.

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.

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 setParameters() modifications to existing procedures

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.

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 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 candidatePair does not match any item in this. [[CandidatePairs]], 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 candidatePair does not match any item in this. [[CandidatePairs]], throw a NotFoundError.

7. Remove the item in this.[[CandidatePairs]] that matches candidatePair.

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 local and remote attributes initialized to the local and remote candidates, respectively, of candidatePair.

      2. Resolve p.

10. Return p.

RTCIceCandidatePairEvent

The icecandidatepairadd and icecandidatepairremove events use the RTCIceCandidatePairEvent interface.

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

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

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

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.

Transferable Data Channels

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

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

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

RTCRtpTransceiver interface extensions

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

WebIDLpartial interface RTCRtpTransceiver {
  readonly attribute boolean rtpHeaderEncryptionNegotiated;
};

RTCConfiguration extensions

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

WebIDLpartial 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 [[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.

RTCRtpSender extensions

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.

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