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.
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.
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 {{EventHandler}} interface, representing a callback used for event handlers, is defined in [[!HTML]].
The concepts [= queue a task =] and [= networking task source =] are defined in [[!HTML]].
The concept [= fire an event =] is defined in [[!DOM]].
The terms [= event =], [= event handlers =] and [= event handler event types =] are defined in [[!HTML]].
The {{RTCPeerConnection}} interface is defined in [[WEBRTC]]. This document extends that interface by using Content-Security-Policy for ICE candidate filtering.
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.
RTP header extension control is an extension to {{RTCRtpTransceiver}} that allows to set and query the RTP header extensions supported and negotiated in SDP.
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.
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:
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.
Set {{RTCRtpTransceiver/[[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 {{RTCSdpType/"answer"}} that runs for both local and remote descriptions, insert the following steps:
For each media description and corresponding transceiver, let negotiatedExtensions be the value of transceiver.{{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}}.
For each extension in negotiatedExtensions, run the following steps:
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"}}.
If description is a remote description, reverse answeredDirection to represent the peer's point of view.
Set extension.{{RTCRtpHeaderExtensionCapability/direction}} to answeredDirection.
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.
Execute the following steps:
Let transceiver be the {{RTCRtpTransceiver}} that this method was invoked on.
Return transceiver.{{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}}.
Execute the following steps:
Let transceiver be the {{RTCRtpTransceiver}} that this method was invoked on.
Let extensions be the first argument of this method.
If the size of extensions does not match the size of transceiver.{{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}} [=exception/throw=] an {{InvalidModificationError}}.
For each index i of extensions, run the following steps:
Let extension be the i-th element of extensions.
If extension.{{RTCRtpHeaderExtensionCapability/uri}} is not equal to the {{RTCRtpHeaderExtensionCapability/uri}} of the i-th element of transceiver.{{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}}, [=exception/throw=] an {{InvalidModificationError}}.
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}}.
If extension.{{RTCRtpHeaderExtensionCapability/direction}} is {{RTCRtpTransceiverDirection/"stopped"}} and {{RTCRtpHeaderExtensionCapability/uri}} indicates a mandatory-to-implement extension, [=exception/throw=] an {{InvalidModificationError}}.
If necessary, restrict extension.{{RTCRtpHeaderExtensionCapability/direction}} as to not exceed the user agent's capabilities for this extension.
Set transceiver.{{RTCRtpTransceiver/[[HeaderExtensionsToNegotiate]]}} to extensions.
Execute the following steps:
Let transceiver be the {{RTCRtpTransceiver}} that this method was invoked on.
Return transceiver.{{RTCRtpTransceiver/[[NegotiatedHeaderExtensions]]}}.
The {{RTCRtpReceiver}} interface is defined in [[WEBRTC]]. This document extends that interface by adding an additional attribute to adjust the receiver's jitter buffer.
Let {{RTCRtpReceiver}} objects have a [[\JitterBufferTarget]] internal slot initially
initialized to null
.
partial interface RTCRtpReceiver { attribute DOMHighResTimeStamp? jitterBufferTarget; };
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:
Let receiver be the {{RTCRtpReceiver}} object on which the setter is invoked.
Let target be the argument to the setter.
If target is negative or larger than 4000 milliseconds, then [=exception/throw=] a {{RangeError}}.
Set receiver's {{RTCRtpReceiver/[[JitterBufferTarget]]}} to target.
Let track be receiver's {{RTCRtpReceiver/[[ReceiverTrack]]}}.
In parallel, begin executing the following steps:
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.
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.
The {{RTCRtpEncodingParameters}} dictionary is defined in [[WEBRTC]]. This document extends that dictionary with additional members to control audio packetization.
partial dictionary RTCRtpEncodingParameters { unsigned long ptime; boolean adaptivePtime = false; RTCRtpCodec codec; };
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.
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.
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.
Add the following steps to the [=RTCRtpSender/setParameters validation steps=]:
Let choosableCodecs be parameters.{{RTCRtpParameters/codecs}}.
If choosableCodecs is an empty list, set choosableCodecs to transceiver.{{RTCRtpTransceiver/[[PreferredCodecs]]}}.
If choosableCodecs is still an empty list, set choosableCodecs to the [=RTCRtpSender/list of implemented send codecs=] for transceiver's kind.
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}}.
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}}.
Add the following steps to the [=RTCPeerConnection/addTransceiver sendEncodings validation steps=]:
If any codec parameter in sendEncodings does [= codec match | not match =] any codec in
{{RTCRtpSender.getCapabilities(kind)}}.codecs
,
[= exception/throw =] an {{OperationError}}.
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}}.
Append the following steps to the set the session description algorithm:
For each transceiver in connection's [= set of transceivers =]:
Let codecs be transceiver.{{RTCRtpTransceiver/[[Sender]]}}.{{RTCRtpSender/[[SendCodecs]]}}.
If codecs is not an empty list:
Remove any codec value in transceiver.{{RTCRtpTransceiver/[[Sender]]}}.{{RTCRtpSender/[[SendEncodings]]}} that does not [= codec match | match =] any entry in codecs.
The {{RTCRtpSender}}'s {{RTCRtpSender/setParameters()}} method is defined in [[WEBRTC]]. This document extends the optional second argument to request generation of a key frame by the encoder.
partial dictionary RTCSetParameterOptions { sequence<RTCEncodingOptions> encodingOptions = []; }; dictionary RTCEncodingOptions { boolean keyFrame = false; };
The {{RTCSetParameterOptions}} are extended by a sequence of {{RTCEncodingOptions}}, one for each encoding.
[]
.
A sequence containing encoding options for each RTP encoding.
{{RTCEncodingOptions}} is the WebRTC equivalent of {{VideoEncoderEncodeOptions}} in [[WebCodecs]].
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 {{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.
The {{RTCIceTransport}} interface is defined in [[WEBRTC]]. This document extends that interface to allow an application to observe and affect certain actions that an ICE agent [[RFC5245]] performs.
When the [= ICE agent =] has picked a candidate pair to remove, the [= user agent =] MUST [= queue a task =] to remove a candidate pair:
Let |connection:RTCPeerConnection| be the {{RTCPeerConnection}} object associated with this [= ICE agent =].
If connection.{{RTCPeerConnection/[[IsClosed]]}} is
true
, abort these steps.
Let |transport:RTCIceTransport| be the {{RTCIceTransport}} object associated with this candidate pair.
Let |candidatePair:RTCIceCandidatePair| be the candidate pair which is being removed.
Let |cancelable:boolean| be true
if the candidate pair is being removed in order to free an unused candidate, and false
otherwise.
Let |accepted:boolean| be the result of [= fire an event | firing an event =] named {{RTCIceTransport/icecandidatepairremove}} at |transport|, using {{RTCIceCandidatePairEvent}}, with the {{Event/cancelable}} attribute initialized to cancelable, and the {{RTCIceCandidatePairEvent/local}} and {{RTCIceCandidatePairEvent/remote}} attributes initialized to the local and remote candidates, respectively, of |candidatePair|.
If |accepted| is false
, instruct the [= ICE agent =] to not remove the candidate pair indicated by |candidatePair|, and instead continue to send and respond to ICE connectivity checks on the candidate pair as before.
Otherwise, instruct the [= ICE agent =] to remove the candidate pair indicated by |candidatePair|.
partial interface RTCIceTransport { attribute EventHandler onicecandidatepairadd; attribute EventHandler onicecandidatepairremove; };
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.
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 =].
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; };
The {{local}} attribute represents the local {{RTCIceCandidate}} of the candidate pair associated with the event.
The {{remote}} attribute represents the remote {{RTCIceCandidate}} of the candidate pair associated with the event.
dictionary RTCIceCandidatePairEventInit : EventInit { required RTCIceCandidate local; required RTCIceCandidate remote; };
The local {{RTCIceCandidate}} of the candidate pair announced by the event.
The remote {{RTCIceCandidate}} of the candidate pair announced by the event.
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; };
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:
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.
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.
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.
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:
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.
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.
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.
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.
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:
Initialize channel.`[[IsTransferable]]` to true
.
Queue a task to run the following step:
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}}.
Set channel.`[[IsTransferable]]` to false
.
The {{RTCDataChannel}} transfer steps, given value and dataHolder, are:
If value.`[[IsTransferable]]` is false
, throw a "DataCloneError" DOMException.
Set dataHolder.`[[ReadyState]]` to value.`[[ReadyState]]`.
Set dataHolder.`[[DataChannelLabel]]` to value.`[[DataChannelLabel]]`.
Set dataHolder.`[[Ordered]]` to value.`[[Ordered]]`.
Set dataHolder.`[[MaxPacketLifeTime]]` to value..`[[MaxPacketLifeTime]]`
Set dataHolder.`[[MaxRetransmits]]` to value.`[[MaxRetransmits]]`.
Set dataHolder.`[[DataChannelProtocol]]` to value.`[[DataChannelProtocol]]`.
Set dataHolder.`[[Negotiated]]` to value.`[[Negotiated]]`.
Set dataHolder.`[[DataChannelId]]` to value.`[[DataChannelId]]`.
Set dataHolder.`[[underlyingDataTransport]]` to value underlying data transport.
Set value.`[[IsTransferable]]` to false
.
Set value.`[[ReadyState]]` to "closed".
The {{RTCDataChannel}} transfer-receiving steps, given dataHolder and channel, are:
Initialize channel.`[[ReadyState]]` to dataHolder.`[[ReadyState]]`.
Initialize channel.`[[DataChannelLabel]]` to dataHolder.`[[\DataChannelLabel]]`.
Initialize channel.`[[Ordered]]` to dataHolder.`[[Ordered]]`.
Initialize channel.`[[MaxPacketLifeTime]]` to dataHolder.`[[MaxPacketLifeTime]]`.
Initialize channel.`[[MaxRetransmits]]` to dataHolder.`[[MaxRetransmits]]`.
Initialize channel.`[[DataChannelProtocol]]` to dataHolder.`[[DataChannelProtocol]]`.
Initialize channel.`[[Negotiated]]` to dataHolder.`[[Negotiated]]`.
Initialize channel.`[[DataChannelId]]` to dataHolder.`[[DataChannelId]]`.
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.
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" };
Enumeration description (non-normative) | |
---|---|
negotiate |
Negotiate RTP header extension encryption as defined in [[CRYPTEX]]. If encryption cannot be negotiated, RTP header extensions are sent in the clear.
|
require |
Require RTP header extension encryption. In [[WEBRTC]] Section 4.4.1.5, add the
following check after Step 4.4.4:
If remote is |
{{RTCRtpTransceiver/rtpHeaderEncryptionNegotiated}} defines whether the transceiver is sending enrypted RTP header extensions as defined in [[CRYPTEX]].
partial interface RTCRtpTransceiver { readonly attribute boolean rtpHeaderEncryptionNegotiated; };
The {{rtpHeaderEncryptionNegotiated}} attribute indicates whether [[CRYPTEX]] has been
negotiated. On getting, the attribute MUST
return the value of the {{RTCRtpTransceiver/[[RtpHeaderEncryptionNegotiated]]}} slot.
In [[WEBRTC]] Section 5.4, add the following step to "create an {{RTCRtpTransceiver}}":
Let transceiver have a [[\RtpHeaderEncryptionNegotiated]]
internal slot, initialized to false
.
{{RTCConfiguration/rtpHeaderEncryptionPolicy}} defines the policy for negotiation of RTP header encryption using [[CRYPTEX]].
partial dictionary RTCConfiguration { RTCRtpHeaderEncryptionPolicy rtpHeaderEncryptionPolicy = "negotiate"; };
{{RTCConfiguration/rtpHeaderEncryptionPolicy}} is marked as a feature at risk, since there is no clear commitment from implementers.
While hardware acceleration of video encoding and decoding is generally desirable, it has proven to be operationally challenging to achieve in the environment of a browser with no detailed information about the underlying hardware. In some cases, falling back to software encoding yields better results.
The methods specified in this section should be used sparingly and not for extended amounts of time.
In privacy-sensitive contexts, browsers may disable hardware acceleration by default to reduce the fingerprinting surface.
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:
When the RTCPeerConnection.constructor()
has been invoked abort these steps.
Set the RTCRtpReceiver's {{RTCRtpReceiver/[[HardwareDisabled]]}} slot to true
.
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:
When the RTCPeerConnection.constructor()
has been invoked abort these steps.
Set the RTCRtpSender's {{RTCRtpSender/[[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 {{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".
The following events fire on {{RTCIceTransport}} objects:
Event name | Interface | Fired when... |
---|---|---|
icecandidatepairadd | {{RTCIceCandidatePairEvent}} | The [= ICE agent =] has formed a candidate pair and is making it available to the script. |
icecandidatepairremove | {{RTCIceCandidatePairEvent}} |
The [= ICE agent =] has picked a candidate pair to remove, and unless the operation is canceled by invoking the preventDefault() method on the event, it will be removed.
|
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]].
The extensions defined in this document do not provide additional impact on the local network beyond what is described in [[WEBRTC]] Section 13.3.
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.
This section is non-normative; it specifies no new behaviour.
The extensions defined in this document do not reveal additional information on IP addresses beyond that already described in [[WEBRTC]] Section 13.2.
The extensions defined in this document do not provide additional persistent information beyond that which is discussed in [[WEBRTC]] Section 13.5.
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.
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.