Dictionary {{RTCConfiguration}} Members

iceServers of type sequence<{{RTCIceServer}}>, defaulting to [].

An array of objects describing servers available to be used by ICE, such as STUN and TURN servers. If the number of ICE servers exceeds an implementation-defined limit, ignore the ICE servers above the threshold. This implementation defined limit MUST be at least 32.

iceTransportPolicy of type {{RTCIceTransportPolicy}}, defaulting to "all".

Indicates which candidates the [= ICE Agent =] is allowed to use.

bundlePolicy of type {{RTCBundlePolicy}}, defaulting to "balanced".

Indicates which media-bundling policy to use when gathering ICE candidates.

rtcpMuxPolicy of type {{RTCRtcpMuxPolicy}}, defaulting to "require".

Indicates which rtcp-mux policy to use when gathering ICE candidates.

certificates of type sequence<{{RTCCertificate}}>, defaulting to [].

A set of certificates that the {{RTCPeerConnection}} uses to authenticate.

Valid values for this parameter are created through calls to the {{RTCPeerConnection/generateCertificate()}} function.

Although any given DTLS connection will use only one certificate, this attribute allows the caller to provide multiple certificates that support different algorithms. The final certificate will be selected based on the DTLS handshake, which establishes which certificates are allowed. The {{RTCPeerConnection}} implementation selects which of the certificates is used for a given connection; how certificates are selected is outside the scope of this specification.

Existing implementations only utilize the first certificate provided; the others are ignored.

If this value is absent, then a default set of certificates is generated for each {{RTCPeerConnection}} instance.

This option allows applications to establish key continuity. An {{RTCCertificate}} can be persisted in [[?INDEXEDDB]] and reused. Persistence and reuse also avoids the cost of key generation.

The value for this configuration option cannot change after its value is initially selected.

iceCandidatePoolSize of type octet, defaulting to 0

Size of the prefetched ICE pool as defined in [[!RFC9429]].

Dictionary {{RTCIceServer}} Members

urls of type (DOMString or sequence<DOMString>), required

STUN or TURN URI(s) as defined in [[!RFC7064]] and [[!RFC7065]] or other URI types.

username of type DOMString

If this {{RTCIceServer}} object represents a TURN server, then this attribute specifies the username to use with that TURN server.

credential of type {{DOMString}}

If this {{RTCIceServer}} object represents a TURN server, then this attribute specifies the credential to use with that TURN server.

{{credential}} represents a long-term authentication password, as described in [[!RFC5389]], Section 10.2.

Dictionary RTCOfferAnswerOptions Members

Dictionary RTCOfferOptions Members

iceRestart of type boolean, defaulting to false

When the value of this dictionary member is true, or the relevant {{RTCPeerConnection}} object's {{RTCPeerConnection/[[LocalIceCredentialsToReplace]]}} slot is not empty, then the generated description will have ICE credentials that are different from the current credentials (as visible in the {{RTCPeerConnection/currentLocalDescription}} attribute's SDP). Applying the generated description will restart ICE, as described in section 9.1.1.1 of [[RFC5245]].

When the value of this dictionary member is false, and the relevant {{RTCPeerConnection}} object's {{RTCPeerConnection/[[LocalIceCredentialsToReplace]]}} slot is empty, and the {{RTCPeerConnection/currentLocalDescription}} attribute has valid ICE credentials, then the generated description will have the same ICE credentials as the current value from the {{RTCPeerConnection/currentLocalDescription}} attribute.

Performing an ICE restart is recommended when {{RTCPeerConnection/iceConnectionState}} transitions to {{RTCIceConnectionState/"failed"}}. An application may additionally choose to listen for the {{RTCPeerConnection/iceConnectionState}} transition to {{RTCIceConnectionState/"disconnected"}} and then use other sources of information (such as using {{RTCPeerConnection/getStats}} to measure if the number of bytes sent or received over the next couple of seconds increases) to determine whether an ICE restart is advisable.

Attributes

localDescription of type {{RTCSessionDescription}}, readonly, nullable

The {{localDescription}} attribute MUST return {{RTCPeerConnection/[[PendingLocalDescription]]}} if it is not null and otherwise it MUST return {{RTCPeerConnection/[[CurrentLocalDescription]]}}.

Note that {{RTCPeerConnection/[[CurrentLocalDescription]]}}.{{RTCSessionDescription/sdp}} and {{RTCPeerConnection/[[PendingLocalDescription]]}}.{{RTCSessionDescription/sdp}} need not be string-wise identical to the {{RTCSessionDescriptionInit/sdp}} value passed to the corresponding {{setLocalDescription}} call (i.e. SDP may be parsed and reformatted, and ICE candidates may be added).

currentLocalDescription of type {{RTCSessionDescription}}, readonly, nullable

The {{currentLocalDescription}} attribute MUST return {{RTCPeerConnection/[[CurrentLocalDescription]]}}.

It represents the local description that was successfully negotiated the last time the {{RTCPeerConnection}} transitioned into the stable state plus any local candidates that have been generated by the [= ICE Agent =] since the offer or answer was created.

pendingLocalDescription of type {{RTCSessionDescription}}, readonly, nullable

The {{pendingLocalDescription}} attribute MUST return {{RTCPeerConnection/[[PendingLocalDescription]]}}.

It represents a local description that is in the process of being negotiated plus any local candidates that have been generated by the [= ICE Agent =] since the offer or answer was created. If the {{RTCPeerConnection}} is in the stable state, the value is null.

remoteDescription of type {{RTCSessionDescription}}, readonly, nullable

The {{remoteDescription}} attribute MUST return {{RTCPeerConnection/[[PendingRemoteDescription]]}} if it is not null and otherwise it MUST return {{RTCPeerConnection/[[CurrentRemoteDescription]]}}.

Note that {{RTCPeerConnection/[[CurrentRemoteDescription]]}}.{{RTCSessionDescription/sdp}} and {{RTCPeerConnection/[[PendingRemoteDescription]]}}.{{RTCSessionDescription/sdp}} need not be string-wise identical to the {{RTCSessionDescriptionInit/sdp}} value passed to the corresponding {{setRemoteDescription}} call (i.e. SDP may be parsed and reformatted, and ICE candidates may be added).

currentRemoteDescription of type {{RTCSessionDescription}}, readonly, nullable

The {{currentRemoteDescription}} attribute MUST return {{RTCPeerConnection/[[CurrentRemoteDescription]]}}.

It represents the last remote description that was successfully negotiated the last time the {{RTCPeerConnection}} transitioned into the stable state plus any remote candidates that have been supplied via {{RTCPeerConnection/addIceCandidate()}} since the offer or answer was created.

pendingRemoteDescription of type {{RTCSessionDescription}}, readonly, nullable

The {{pendingRemoteDescription}} attribute MUST return {{RTCPeerConnection/[[PendingRemoteDescription]]}}.

It represents a remote description that is in the process of being negotiated, complete with any remote candidates that have been supplied via {{RTCPeerConnection/addIceCandidate()}} since the offer or answer was created. If the {{RTCPeerConnection}} is in the stable state, the value is null.

signalingState of type {{RTCSignalingState}}, readonly

The {{signalingState}} attribute MUST return the {{RTCPeerConnection/RTCPeerConnection}} object's {{RTCPeerConnection/[[SignalingState]]}}.

iceGatheringState of type {{RTCIceGatheringState}}, readonly

The {{iceGatheringState}} attribute MUST return the {{RTCPeerConnection}} object's {{RTCPeerConnection/[[IceGatheringState]]}}.

iceConnectionState of type {{RTCIceConnectionState}}, readonly

The {{iceConnectionState}} attribute MUST return the {{RTCPeerConnection}} object's {{RTCPeerConnection/[[IceConnectionState]]}}.

connectionState of type {{RTCPeerConnectionState}}, readonly

The {{connectionState}} attribute MUST return the {{RTCPeerConnection}} object's {{RTCPeerConnection/[[ConnectionState]]}}.

canTrickleIceCandidates of type boolean, readonly, nullable

The {{canTrickleIceCandidates}} attribute indicates whether the remote peer is able to accept trickled ICE candidates [[RFC8838]]. The value is determined based on whether a remote description indicates support for trickle ICE, as defined in [[!RFC9429]]. Prior to the completion of {{RTCPeerConnection/setRemoteDescription}}, this value is null.

onnegotiationneeded of type EventHandler

The event type of this event handler is {{RTCPeerConnection/negotiationneeded}}.

onicecandidate of type EventHandler

The event type of this event handler is {{RTCPeerConnection/icecandidate}}.

onicecandidateerror of type EventHandler

The event type of this event handler is {{RTCPeerConnection/icecandidateerror}}.

onsignalingstatechange of type EventHandler

The event type of this event handler is {{RTCPeerConnection/signalingstatechange}}.

oniceconnectionstatechange of type EventHandler

The event type of this event handler is {{RTCPeerConnection/iceconnectionstatechange}}

onicegatheringstatechange of type EventHandler

The event type of this event handler is {{RTCPeerConnection/icegatheringstatechange}}.

onconnectionstatechange of type EventHandler

The event type of this event handler is {{RTCPeerConnection/connectionstatechange}}.

Methods

createOffer

The {{createOffer}} method generates a blob of SDP that contains an RFC 3264 offer with the supported configurations for the session, including descriptions of the local {{MediaStreamTrack}}s attached to this {{RTCPeerConnection}}, the codec/RTP/RTCP capabilities supported by this implementation, and parameters of the [= ICE agent =] and the DTLS connection. The options parameter may be supplied to provide additional control over the offer generated.

If a system has limited resources (e.g. a finite number of decoders), {{createOffer}} needs to return an offer that reflects the current state of the system, so that {{setLocalDescription}} will succeed when it attempts to acquire those resources. The session descriptions MUST remain usable by {{setLocalDescription}} without causing an error until at least the end of the [= fulfillment =] callback of the returned promise.

Creating the SDP MUST follow the appropriate process for generating an offer described in [[!RFC9429]], except the user agent MUST treat a {{RTCRtpTransceiver/stopping}} transceiver as {{RTCRtpTransceiver/stopped}} for the purposes of RFC9429 in this case.

As an offer, the generated SDP will contain the full set of codec/RTP/RTCP capabilities supported or preferred by the session (as opposed to an answer, which will include only a specific negotiated subset to use). In the event {{createOffer}} is called after the session is established, {{createOffer}} will generate an offer that is compatible with the current session, incorporating any changes that have been made to the session since the last complete offer-answer exchange, such as addition or removal of tracks. If no changes have been made, the offer will include the capabilities of the current local description as well as any additional capabilities that could be negotiated in an updated offer.

The generated SDP will also contain the [= ICE agent =]'s {{RTCIceParameters/usernameFragment}}, {{RTCIceParameters/password}} and ICE options (as defined in [[RFC5245]], Section 14) and may also contain any local candidates that have been gathered by the agent.

The {{RTCConfiguration/certificates}} value in configuration for the {{RTCPeerConnection}} provides the certificates configured by the application for the {{RTCPeerConnection}}. These certificates, along with any default certificates are used to produce a set of certificate fingerprints. These certificate fingerprints are used in the construction of SDP.

The process of generating an SDP exposes a subset of the media capabilities of the underlying system, which provides generally persistent cross-origin information on the device. It thus increases the fingerprinting surface of the application. In privacy-sensitive contexts, browsers can consider mitigations such as generating SDP matching only a common subset of the capabilities.

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

1. Let connection be the {{RTCPeerConnection}} object on which the method was invoked.

2. If connection.{{RTCPeerConnection/[[IsClosed]]}} is true, return a promise [= rejected =] with a newly [= exception/created =] {{InvalidStateError}}.

3. Return the result of [= chaining =] the result of [= creating an offer =] with connection to connection's [= operations chain =].

To create an offer given connection run the following steps:

1. If connection.{{RTCPeerConnection/[[SignalingState]]}} is neither {{RTCSignalingState/"stable"}} nor {{RTCSignalingState/"have-local-offer"}}, return a promise [= rejected =] with a newly [= exception/created =] {{InvalidStateError}}.

2. Let p be a new promise.

3. [=In parallel=], begin the [= in-parallel steps to create an offer =] given connection and p.

4. Return p.

The in-parallel steps to create an offer given connection and a promise p are as follows:

1. If connection was not constructed with a set of certificates, and one has not yet been generated, wait for it to be generated.

2. Inspect the offerer's system state to determine the currently available resources as necessary for generating the offer, as described in [[!RFC9429]].

3. If this inspection failed for any reason, [= reject =] p with a newly [= exception/created =] {{OperationError}} and abort these steps.

4. Queue a task that runs the [= final steps to create an offer =] given connection and p.

The final steps to create an offer given connection and a promise p are as follows:

1. If connection.{{RTCPeerConnection/[[IsClosed]]}} is true, then abort these steps.

2. If connection was modified in such a way that additional inspection of the [= offerer's system state =] is necessary, then [=in parallel=] begin the [= in-parallel steps to create an offer =] again, given connection and p, and abort these steps.

   This may be necessary if, for example, {{createOffer}} was called when only an audio {{RTCRtpTransceiver}} was added to connection, but while performing the [= in-parallel steps to create an offer =], a video {{RTCRtpTransceiver}} was added, requiring additional inspection of video system resources.

3. Given the information that was obtained from previous inspection, the current state of connection and its {{RTCRtpTransceiver}}s, generate an SDP offer, sdpString, as described in [[!RFC9429]].

   1. As described in [[RFC8843]] (Section 7), if bundling is used (see {{RTCBundlePolicy}}) an offerer tagged m= section must be selected in order to negotiate a BUNDLE group. The user agent MUST choose the m= section that corresponds to the first non-stopped transceiver in the [= set of transceivers =] as the offerer tagged m= section. This allows the remote endpoint to predict which transceiver is the offerer tagged m= section without having to parse the SDP.

   2. The codec preferences of a [= media description =]'s [= associated =] transceiver, transceiver, is said to be the value of transceiver.{{RTCRtpTransceiver/[[PreferredCodecs]]}} with the following filtering applied (or said not to be set if transceiver.{{RTCRtpTransceiver/[[PreferredCodecs]]}} is empty):

      1. Let kind be transceiver's {{RTCRtpTransceiver/[[Receiver]]}}'s {{RTCRtpReceiver/[[ReceiverTrack]]}}'s {{MediaStreamTrack/kind}}.

      3. If transceiver.{{RTCRtpTransceiver/direction}} is {{RTCRtpTransceiverDirection/"sendonly"}} or {{RTCRtpTransceiverDirection/"sendrecv"}}, exclude any codecs not included in the [=RTCRtpSender/list of implemented send codecs=] for kind.

      4. If transceiver.{{RTCRtpTransceiver/direction}} is {{RTCRtpTransceiverDirection/"recvonly"}} or {{RTCRtpTransceiverDirection/"sendrecv"}}, exclude any codecs not included in the [=list of implemented receive codecs=] for kind.

      The filtering MUST NOT change the order of the codec preferences.

   3. If the length of the {{RTCRtpSender/[[SendEncodings]]}} slot of the {{RTCRtpSender}} is larger than 1, then for each encoding given in {{RTCRtpSender/[[SendEncodings]]}} of the {{RTCRtpSender}}, add an a=rid send line to the corresponding media section, and add an a=simulcast:send line giving the RIDs in the same order as given in the {{RTCRtpSendParameters/encodings}} field. No RID restrictions are set.

      [[RFC8853]] section 5.2 specifies that the order of RIDs in the a=simulcast line suggests a proposed order of preference. If the browser decides not to transmit all encodings, one should expect it to stop sending the last encoding in the list first.

4. Let offer be a newly created {{RTCSessionDescriptionInit}} dictionary with its {{RTCSessionDescriptionInit/type}} member initialized to the string {{RTCSdpType/"offer"}} and its {{RTCSessionDescriptionInit/sdp}} member initialized to sdpString.

5. Set the {{RTCPeerConnection/[[LastCreatedOffer]]}} internal slot to sdpString.

6. [= Resolve =] p with offer.

createAnswer

The {{createAnswer}} method generates an [[!SDP]] answer with the supported configuration for the session that is compatible with the parameters in the remote configuration. Like {{createOffer}}, the returned blob of SDP contains descriptions of the local {{MediaStreamTrack}}s attached to this {{RTCPeerConnection}}, the codec/RTP/RTCP options negotiated for this session, and any candidates that have been gathered by the [= ICE Agent =]. The options parameter may be supplied to provide additional control over the generated answer.

Like {{createOffer}}, the returned description SHOULD reflect the current state of the system. The session descriptions MUST remain usable by {{setLocalDescription}} without causing an error until at least the end of the [= fulfillment =] callback of the returned promise.

As an answer, the generated SDP will contain a specific codec/RTP/RTCP configuration that, along with the corresponding offer, specifies how the media plane should be established. The generation of the SDP MUST follow the appropriate process for generating an answer described in [[!RFC9429]].

The generated SDP will also contain the [= ICE agent =]'s {{RTCIceParameters/usernameFragment}}, {{RTCIceParameters/password}} and ICE options (as defined in [[RFC5245]], Section 14) and may also contain any local candidates that have been gathered by the agent.

The {{RTCConfiguration/certificates}} value in configuration for the {{RTCPeerConnection}} provides the certificates configured by the application for the {{RTCPeerConnection}}. These certificates, along with any default certificates are used to produce a set of certificate fingerprints. These certificate fingerprints are used in the construction of SDP.

An answer can be marked as provisional, as described in [[!RFC9429]], by setting the {{RTCSessionDescriptionInit/type}} to {{RTCSdpType/"pranswer"}}.

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

1. Let connection be the {{RTCPeerConnection}} object on which the method was invoked.

2. If connection.{{RTCPeerConnection/[[IsClosed]]}} is true, return a promise [= rejected =] with a newly [= exception/created =] {{InvalidStateError}}.

3. Return the result of [= chaining =] the result of [= creating an answer =] with connection to connection's [= operations chain =].

To create an answer given connection run the following steps:

1. If connection.{{RTCPeerConnection/[[SignalingState]]}} is neither {{RTCSignalingState/"have-remote-offer"}} nor {{RTCSignalingState/"have-local-pranswer"}}, return a promise [= rejected =] with a newly [= exception/created =] {{InvalidStateError}}.

2. Let p be a new promise.

3. [=In parallel=], begin the [= in-parallel steps to create an answer =] given connection and p.

4. Return p.

The in-parallel steps to create an answer given connection and a promise p are as follows:

1. If connection was not constructed with a set of certificates, and one has not yet been generated, wait for it to be generated.

2. Inspect the answerer's system state to determine the currently available resources as necessary for generating the answer, as described in [[!RFC9429]].

3. If this inspection failed for any reason, [= reject =] p with a newly [= exception/created =] {{OperationError}} and abort these steps.

4. Queue a task that runs the [= final steps to create an answer =] given p.

The final steps to create an answer given a promise p are as follows:

1. If connection.{{RTCPeerConnection/[[IsClosed]]}} is true, then abort these steps.

2. If connection was modified in such a way that additional inspection of the [= answerer's system state =] is necessary, then [=in parallel=] begin the [= in-parallel steps to create an answer =] again given connection and p, and abort these steps.

   This may be necessary if, for example, {{createAnswer}} was called when an {{RTCRtpTransceiver}}'s direction was {{RTCRtpTransceiverDirection/"recvonly"}}, but while performing the [= in-parallel steps to create an answer =], the direction was changed to {{RTCRtpTransceiverDirection/"sendrecv"}}, requiring additional inspection of video encoding resources.

3. Given the information that was obtained from previous inspection and the current state of connection and its {{RTCRtpTransceiver}}s, generate an SDP answer, sdpString, as described in [[!RFC9429]].

   1. The codec preferences of an m= section's [= associated =] transceiver, transceiver, is said to be the value of transceiver.{{RTCRtpTransceiver/[[PreferredCodecs]]}} with the following filtering applied (or said not to be set if transceiver.{{RTCRtpTransceiver/[[PreferredCodecs]]}} is empty):

      1. Let kind be transceiver's {{RTCRtpTransceiver/[[Receiver]]}}'s {{RTCRtpReceiver/[[ReceiverTrack]]}}'s {{MediaStreamTrack/kind}}.

      2. If transceiver.{{RTCRtpTransceiver/direction}} is {{RTCRtpTransceiverDirection/"sendonly"}} or {{RTCRtpTransceiverDirection/"sendrecv"}}, exclude any codecs not included in the [=RTCRtpSender/list of implemented send codecs=] for kind.

      3. If transceiver.{{RTCRtpTransceiver/direction}} is {{RTCRtpTransceiverDirection/"recvonly"}} or {{RTCRtpTransceiverDirection/"sendrecv"}}, exclude any codecs not included in the [=list of implemented receive codecs=] for kind.

      The filtering MUST NOT change the order of the codec preferences.

   2. If this is an answer to an offer to receive simulcast, then for each media section requesting to receive simulcast, run the following steps:

      1. If the a=simulcast attribute contains comma-separated alternatives for RIDs, remove all but the first ones.

      2. If there are any identically named RIDs in the a=simulcast attribute, remove all but the first one. No RID restrictions are set.

      3. Exclude from the media section in the answer any RID not found in the corresponding transceiver's {{RTCRtpTransceiver/[[Sender]]}}.{{RTCRtpSender/[[SendEncodings]]}}.

      When a {{RTCPeerConnection/setRemoteDescription(offer)}} establishes a sender's [=proposed envelope=], the sender's {{RTCRtpSender/[[SendEncodings]]}} is updated in {{RTCSignalingState/"have-remote-offer"}}, exposing it to rollback. However, once a [=simulcast envelope=] has been established for the sender, subsequent pruning of the sender's {{RTCRtpSender/[[SendEncodings]]}} happen when this answer is set with {{RTCPeerConnection/setLocalDescription}}.

4. Let answer be a newly created {{RTCSessionDescriptionInit}} dictionary with its {{RTCSessionDescriptionInit/type}} member initialized to the string {{RTCSdpType/"answer"}} and its {{RTCSessionDescriptionInit/sdp}} member initialized to sdpString.

5. Set the {{RTCPeerConnection/[[LastCreatedAnswer]]}} internal slot to sdpString.

6. [= Resolve =] p with answer.

setLocalDescription

The {{setLocalDescription}} method instructs the {{RTCPeerConnection}} to apply the supplied {{RTCLocalSessionDescriptionInit}} as the local description.

This API changes the local media state. In order to successfully handle scenarios where the application wants to offer to change from one media format to a different, incompatible format, the {{RTCPeerConnection}} MUST be able to simultaneously support use of both the current and pending local descriptions (e.g. support codecs that exist in both descriptions) until a final answer is received, at which point the {{RTCPeerConnection}} can fully adopt the pending local description, or rollback to the current description if the remote side rejected the change.

Passing in a description is optional. If left out, then {{setLocalDescription}} will implicitly [= create an offer =] or [= create an answer =], as needed. As noted in [[!RFC9429]], if a description with SDP is passed in, that SDP is not allowed to have changed from when it was returned from either {{createOffer}} or {{createAnswer}}.

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

1. Let description be the method's first argument.

2. Let connection be the {{RTCPeerConnection}} object on which the method was invoked.

3. Let sdp be description.{{RTCSessionDescriptionInit/sdp}}.

4. Return the result of [= chaining =] the following steps to connection's [= operations chain =]:

   1. Let type be description.{{RTCSessionDescriptionInit/type}} if present, or {{RTCSdpType/"offer"}} if not present and connection.{{RTCPeerConnection/[[SignalingState]]}} is either {{RTCSignalingState/"stable"}}, {{RTCSignalingState/"have-local-offer"}}, or {{RTCSignalingState/"have-remote-pranswer"}}; otherwise {{RTCSdpType/"answer"}}.

   2. If type is {{RTCSdpType/"offer"}}, and sdp is not the empty string and not equal to connection.{{RTCPeerConnection/[[LastCreatedOffer]]}}, then return a promise [= rejected =] with a newly [= exception/created =] {{InvalidModificationError}} and abort these steps.

   3. If type is {{RTCSdpType/"answer"}} or {{RTCSdpType/"pranswer"}}, and sdp is not the empty string and not equal to connection.{{RTCPeerConnection/[[LastCreatedAnswer]]}}, then return a promise [= rejected =] with a newly [= exception/created =] {{InvalidModificationError}} and abort these steps.

   4. If sdp is the empty string, and type is {{RTCSdpType/"offer"}}, then run the following sub steps:

      1. Set sdp to the value of connection.{{RTCPeerConnection/[[LastCreatedOffer]]}}.

      2. If sdp is the empty string, or if it no longer accurately represents the [= offerer's system state =] of connection, then let p be the result of [= creating an offer =] with connection, and return the result of [= promise/reacting =] to p with a fulfillment step that [= set a local session description | sets the local session description =] indicated by its first argument.

   5. If sdp is the empty string, and type is {{RTCSdpType/"answer"}} or {{RTCSdpType/"pranswer"}}, then run the following sub steps:

      1. Set sdp to the value of connection.{{RTCPeerConnection/[[LastCreatedAnswer]]}}.

      2. If sdp is the empty string, or if it no longer accurately represents the [= answerer's system state =] of connection, then let p be the result of [= creating an answer =] with connection, and return the result of [= promise/reacting =] to p with the following fulfillment steps:

         1. Let answer be the first argument to these fulfillment steps.

         2. Return the result of [= setting the local session description =] indicated by {type, answer.{{RTCSessionDescriptionInit/sdp}}}.

   6. Return the result of [= setting the local session description =] indicated by {type, sdp}.

As noted in [[!RFC9429]], calling this method may trigger the ICE candidate gathering process by the [= ICE Agent =].

setRemoteDescription

The {{setRemoteDescription}} method instructs the {{RTCPeerConnection}} to apply the supplied {{RTCSessionDescriptionInit}} as the remote offer or answer. This API changes the local media state.

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

1. Let description be the method's first argument.

2. Let connection be the {{RTCPeerConnection}} object on which the method was invoked.

3. Return the result of [= chaining =] the following steps to connection's [= operations chain =]:

   1. If description.{{RTCSessionDescriptionInit/type}} is {{RTCSdpType/"offer"}} and is invalid for the current connection.{{RTCPeerConnection/[[SignalingState]]}} as described in [[!RFC9429]], then run the following sub steps:

      1. Let p be the result of [= setting the local session description =] indicated by {type: {{RTCSdpType/"rollback"}}}.

      2. Return the result of [= promise/reacting =] to p with a fulfillment step that [= set a remote session description | sets the remote session description =] description, and abort these steps.

   2. Return the result of [= setting the remote session description =] description.

addIceCandidate

The {{addIceCandidate}} method provides a remote candidate to the [= ICE Agent =]. This method can also be used to indicate the end of remote candidates when called with an empty string for the {{RTCIceCandidate/candidate}} member. The only members of the argument used by this method are {{RTCIceCandidate/candidate}}, {{RTCIceCandidate/sdpMid}}, {{RTCIceCandidate/sdpMLineIndex}}, and {{RTCIceCandidate/usernameFragment}}; the rest are ignored. When the method is invoked, the user agent MUST run the following steps:

1. Let candidate be the method's argument.

2. Let connection be the {{RTCPeerConnection}} object on which the method was invoked.

3. If candidate.{{RTCIceCandidate/candidate}} is not an empty string and both candidate.{{RTCIceCandidate/sdpMid}} and candidate.{{RTCIceCandidate/sdpMLineIndex}} are null, return a promise [= rejected =] with a newly [= exception/created =] {{TypeError}}.

4. Return the result of [= chaining =] the following steps to connection's [= operations chain =]:

   1. If {{RTCPeerConnection/remoteDescription}} is null return a promise [= rejected =] with a newly [= exception/created =] {{InvalidStateError}}.

   2. If candidate.{{RTCIceCandidate/sdpMid}} is not null, run the following steps:

      1. If candidate.{{RTCIceCandidate/sdpMid}} is not equal to the mid of any media description in {{RTCPeerConnection/remoteDescription}}, return a promise [= rejected =] with a newly [= exception/created =] {{OperationError}}.

   3. Else, if candidate.{{RTCIceCandidate/sdpMLineIndex}} is not null, run the following steps:

      1. If candidate.{{RTCIceCandidate/sdpMLineIndex}} is equal to or larger than the number of media descriptions in {{RTCPeerConnection/remoteDescription}}, return a promise [= rejected =] with a newly [= exception/created =] {{OperationError}}.

   4. If either candidate.{{RTCIceCandidate/sdpMid}} or candidate.{{RTCIceCandidate/sdpMLineIndex}} indicate a media description in {{RTCPeerConnection/remoteDescription}} whose associated transceiver is {{RTCRtpTransceiver/ stopped}}, return a promise [= resolved =] with undefined.

   5. If candidate.{{RTCIceCandidate/usernameFragment}} is not null, and is not equal to any username fragment present in the corresponding [= media description =] of an applied remote description, return a promise [= rejected =] with a newly [= exception/created =] {{OperationError}}.

   6. Let p be a new promise.

   7. [=In parallel=], if the candidate is not [= administratively prohibited =], add the ICE candidate candidate as described in [[!RFC9429]]. Use candidate.{{RTCIceCandidate/usernameFragment}} to identify the ICE [= generation =]; if {{RTCIceCandidate/usernameFragment}} is null, process the candidate for the most recent ICE [= generation =].

      If candidate.{{RTCIceCandidate/candidate}} is an empty string, process candidate as an end-of-candidates indication for the corresponding [= media description =] and ICE candidate [= generation =]. If both candidate.{{RTCIceCandidate/sdpMid}} and candidate.{{RTCIceCandidate/sdpMLineIndex}} are null, then this end-of-candidates indication applies to all [= media description =]s.

      1. If candidate could not be successfully added the user agent MUST queue a task that runs the following steps:

         1. If connection.{{RTCPeerConnection/[[IsClosed]]}} is true, then abort these steps.

         2. [= Reject =] p with a newly [= exception/created =] {{OperationError}} and abort these steps.

      2. If candidate is applied successfully, or if the candidate was [= administratively prohibited =] the user agent MUST queue a task that runs the following steps:

         1. If connection.{{RTCPeerConnection/[[IsClosed]]}} is true, then abort these steps.

         2. If connection.{{RTCPeerConnection/[[PendingRemoteDescription]]}} is not null, and represents the ICE [= generation =] for which candidate was processed, add candidate to connection.{{RTCPeerConnection/[[PendingRemoteDescription]]}}.sdp.

         3. If connection.{{RTCPeerConnection/[[CurrentRemoteDescription]]}} is not null, and represents the ICE [= generation =] for which candidate was processed, add candidate to connection.{{RTCPeerConnection/[[CurrentRemoteDescription]]}}.sdp.

         4. [= Resolve =] p with undefined.

   8. Return p.

A candidate is administratively prohibited if the UA has decided not to allow connection attempts to this address.

For privacy reasons, there is no indication to the developer about whether or not an address/port is blocked; it behaves exactly as if there was no response from the address.

The UA MUST prohibit connections to addresses on the [[!Fetch]] [= block bad port =] list, and MAY choose to prohibit connections to other addresses.

If the {{RTCConfiguration/iceTransportPolicy}} member of the {{RTCConfiguration}} is {{RTCIceTransportPolicy/relay}}, candidates requiring external resolution, such as mDNS candidates and DNS candidates, MUST be prohibited.

Due to WebIDL processing, {{RTCPeerConnection/addIceCandidate}}(null) is interpreted as a call with the default dictionary present, which, in the above algorithm, indicates end-of-candidates for all media descriptions and ICE candidate generation. This is by design for legacy reasons.

restartIce

The {{restartIce}} method tells the {{RTCPeerConnection}} that ICE should be restarted. Subsequent calls to {{createOffer}} will create descriptions that will restart ICE, as described in section 9.1.1.1 of [[RFC5245]].

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

1. Let connection be the {{RTCPeerConnection}} on which the method was invoked.

2. Empty connection.{{RTCPeerConnection/[[LocalIceCredentialsToReplace]]}}, and populate it with all ICE credentials (ice-ufrag and ice-pwd as defined in section 15.4 of [[RFC5245]]) found in connection.{{RTCPeerConnection/[[CurrentLocalDescription]]}}, as well as all ICE credentials found in connection.{{RTCPeerConnection/[[PendingLocalDescription]]}}.

3. [= Update the negotiation-needed flag =] for connection.

getConfiguration

Returns an {{RTCConfiguration}} object representing the current configuration of this {{RTCPeerConnection}} object.

When this method is called, the user agent MUST return the {{RTCConfiguration}} object stored in the {{RTCPeerConnection/[[Configuration]]}} internal slot.

setConfiguration

The {{setConfiguration}} method updates the configuration of this {{RTCPeerConnection}} object. This includes changing the configuration of the [= ICE Agent =]. As noted in [[!RFC9429]], when the ICE configuration changes in a way that requires a new gathering phase, an ICE restart is required.

When the {{setConfiguration}} method is invoked, the user agent MUST run the following steps:

1. Let connection be the {{RTCPeerConnection}} on which the method was invoked.

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

3. [= Set the configuration =] specified by configuration.

close

When the {{close}} method is invoked, the user agent MUST run the following steps:

1. Let connection be the {{RTCPeerConnection}} object on which the method was invoked.

2. [= close the connection =] with connection and the value false.

The close the connection algorithm given a connection and a disappear boolean, is as follows:

1. If connection.{{RTCPeerConnection/[[IsClosed]]}} is true, abort these steps.

2. Set connection.{{RTCPeerConnection/[[IsClosed]]}} to true.

3. Set connection.{{RTCPeerConnection/[[SignalingState]]}} to {{RTCSignalingState/"closed"}}. This does not fire any event.

4. Let transceivers be the result of executing the {{CollectTransceivers}} algorithm. For every {{RTCRtpTransceiver}} transceiver in transceivers, run the following steps:

   1. If transceiver.{{RTCRtpTransceiver/[[Stopped]]}} is true, abort these sub steps.

   2. [= Stop the RTCRtpTransceiver =] with transceiver and disappear.

5. Set the {{RTCDataChannel/[[ReadyState]]}} slot of each of connection's {{RTCDataChannel}}s to {{RTCDataChannelState/"closed"}}.

   The {{RTCDataChannel}}s will be closed abruptly and the closing procedure will not be invoked.

6. If connection.{{RTCPeerConnection/[[SctpTransport]]}} is not null, tear down the underlying SCTP association by sending an SCTP ABORT chunk and set the {{RTCSctpTransport/[[SctpTransportState]]}} to {{RTCSctpTransportState/"closed"}}.

7. Set the {{RTCDtlsTransport/[[DtlsTransportState]]}} slot of each of connection's {{RTCDtlsTransport}}s to {{RTCDtlsTransportState/"closed"}}.

8. Destroy connection's [= ICE Agent =], abruptly ending any active ICE processing and releasing any relevant resources (e.g. TURN permissions).

9. Set the {{RTCIceTransport/[[IceTransportState]]}} slot of each of connection's {{RTCIceTransport}}s to {{RTCIceTransportState/"closed"}}.

10. Set connection.{{RTCPeerConnection/[[IceConnectionState]]}} to {{RTCIceConnectionState/"closed"}}. This does not fire any event.

11. Set connection.{{RTCPeerConnection/[[ConnectionState]]}} to {{RTCPeerConnectionState/"closed"}}. This does not fire any event.

Constructors

constructor()

The {{RTCSessionDescription()}} constructor takes a dictionary argument, description, whose content is used to initialize the new {{RTCSessionDescription}} object. This constructor is deprecated; it exists for legacy compatibility reasons only.

Attributes

type of type {{RTCSdpType}}, readonly

The type of this session description.

sdp of type DOMString, readonly, defaulting to ""

The string representation of the SDP [[!SDP]].

Methods

toJSON()

When called, run [[!WEBIDL]]'s [= default toJSON steps =].

Dictionary RTCSessionDescriptionInit Members

type of type {{RTCSdpType}}, required

The type of this session description.

sdp of type DOMString

The string representation of the SDP [[!SDP]]; if {{RTCSessionDescriptionInit/type}} is {{RTCSdpType/"rollback"}}, this member is unused.

Dictionary RTCLocalSessionDescriptionInit Members

type of type {{RTCSdpType}}

The type of this description. If not present, then {{RTCPeerConnection/setLocalDescription}} will infer the type based on the {{RTCPeerConnection}}'s {{RTCPeerConnection/[[SignalingState]]}}.

sdp of type DOMString

The string representation of the SDP [[!SDP]]; if {{RTCLocalSessionDescriptionInit/type}} is {{RTCSdpType/"rollback"}}, this member is unused.

Constructor

constructor()

The RTCIceCandidate() constructor takes a dictionary argument, candidateInitDict, whose content is used to initialize the new {{RTCIceCandidate}} object.

When invoked, run the following steps:

1. If both the {{RTCIceCandidateInit/sdpMid}} and {{RTCIceCandidateInit/sdpMLineIndex}} members of candidateInitDict are null, [= exception/throw =] a {{TypeError}}.

2. Return the result of [= creating an RTCIceCandidate =] with candidateInitDict.

To create an RTCIceCandidate with a candidateInitDict dictionary, run the following steps:

1. Let iceCandidate be a newly created {{RTCIceCandidate}} object.
2. Create internal slots for the following attributes of iceCandidate, initilized to null: {{foundation}}, {{component}}, {{priority}}, {{address}}, {{protocol}}, {{port}}, {{type}}, {{tcpType}}, {{relatedAddress}}, and {{relatedPort}}.
3. Create internal slots for the following attributes of iceCandidate, initilized to their namesakes in candidateInitDict: {{candidate}}, {{sdpMid}}, {{sdpMLineIndex}}, {{usernameFragment}}.
4. Let candidate be the {{RTCIceCandidateInit/candidate}} dictionary member of candidateInitDict. If candidate is not an empty string, run the following steps:
   1. Parse candidate using the [= candidate-attribute =] grammar.
   2. If parsing of [= candidate-attribute =] has failed, abort these steps.
   3. If any field in the parse result represents an invalid value for the corresponding attribute in iceCandidate, abort these steps.
   4. Set the corresponding internal slots in iceCandidate to the field values of the parsed result.
5. Return iceCandidate.

The constructor for {{RTCIceCandidate}} only does basic parsing and type checking for the dictionary members in candidateInitDict. Detailed validation on the well-formedness of {{RTCIceCandidateInit/candidate}}, {{RTCIceCandidateInit/sdpMid}}, {{RTCIceCandidateInit/sdpMLineIndex}}, {{RTCIceCandidateInit/usernameFragment}} with the corresponding session description is done when passing the {{RTCIceCandidate}} object to {{RTCPeerConnection/addIceCandidate()}}.

To maintain backward compatibility, any error on parsing the candidate attribute is ignored. In such case, the {{candidate}} attribute holds the raw {{RTCIceCandidateInit/candidate}} string given in candidateInitDict, but derivative attributes such as {{foundation}}, {{priority}}, etc are set to null.

Attributes

Most attributes below are defined in section 15.1 of [[RFC5245]].

candidate of type DOMString, readonly

This carries the [= candidate-attribute =] as defined in section 15.1 of [[RFC5245]]. If this {{RTCIceCandidate}} represents an end-of-candidates indication or a peer reflexive remote candidate, {{candidate}} is an empty string.

sdpMid of type DOMString, readonly, nullable

If not null, this contains the media stream "identification-tag" defined in [[!RFC5888]] for the media component this candidate is associated with.

sdpMLineIndex of type unsigned short, readonly, nullable

If not null, this indicates the index (starting at zero) of the [= media description =] in the SDP this candidate is associated with.

foundation of type DOMString, readonly, nullable

A unique identifier that allows ICE to correlate candidates that appear on multiple {{RTCIceTransport}}s.

component of type {{RTCIceComponent}}, readonly, nullable

The assigned network component of the candidate ({{RTCIceComponent/"rtp"}} or {{RTCIceComponent/"rtcp"}}). This corresponds to the component-id field in [= candidate-attribute =], decoded to the string representation as defined in {{RTCIceComponent}}.

priority of type unsigned long, readonly, nullable

The assigned priority of the candidate.

address of type DOMString, readonly, nullable

The address of the candidate, allowing for IPv4 addresses, IPv6 addresses, and fully qualified domain names (FQDNs). This corresponds to the connection-address field in [= candidate-attribute =].

Remote candidates may be exposed, for instance via {{RTCIceTransport/[[SelectedCandidatePair]]}}.{{RTCIceCandidatePair/remote}}. By default, the user agent MUST leave the {{RTCIceCandidate/address}} attribute as null for any exposed remote candidate. Once a {{RTCPeerConnection}} instance learns on an address by the web application using {{RTCPeerConnection/addIceCandidate}}, the user agent can expose the {{address}} attribute value in any {{RTCIceCandidate}} of the {{RTCPeerConnection}} instance representing a remote candidate with that newly learnt address.

The addresses exposed in candidates gathered via ICE and made visibile to the application in {{RTCIceCandidate}} instances can reveal more information about the device and the user (e.g. location, local network topology) than the user might have expected in a non-WebRTC enabled browser.

These addresses are always exposed to the application, and potentially exposed to the communicating party, and can be exposed without any specific user consent (e.g. for peer connections used with data channels, or to receive media only).

These addresses can also be used as temporary or persistent cross-origin states, and thus contribute to the fingerprinting surface of the device.

Applications can avoid exposing addresses to the communicating party, either temporarily or permanently, by forcing the [= ICE Agent =] to report only relay candidates via the {{RTCConfiguration/iceTransportPolicy}} member of {{RTCConfiguration}}.

To limit the addresses exposed to the application itself, browsers can offer their users different policies regarding sharing local addresses, as defined in [[RFC8828]].

protocol of type {{RTCIceProtocol}}, readonly, nullable

The protocol of the candidate ({{RTCIceProtocol/"udp"}}/{{RTCIceProtocol/"tcp"}}). This corresponds to the transport field in [= candidate-attribute =].

port of type unsigned short, readonly, nullable

The port of the candidate.

type of type {{RTCIceCandidateType}}, readonly, nullable

The type of the candidate. This corresponds to the candidate-types field in [= candidate-attribute =].

tcpType of type {{RTCIceTcpCandidateType}}, readonly, nullable

If {{protocol}} is {{RTCIceProtocol/"tcp"}}, {{tcpType}} represents the type of TCP candidate. Otherwise, {{tcpType}} is null. This corresponds to the tcp-type field in [= candidate-attribute =].

relatedAddress of type DOMString, readonly, nullable

For a candidate that is derived from another, such as a relay or reflexive candidate, the {{relatedAddress}} is the IP address of the candidate that it is derived from. For host candidates, the {{relatedAddress}} is null. This corresponds to the rel-address field in [= candidate-attribute =].

relatedPort of type unsigned short, readonly, nullable

For a candidate that is derived from another, such as a relay or reflexive candidate, the {{relatedPort}} is the port of the candidate that it is derived from. For host candidates, the {{relatedPort}} is null. This corresponds to the rel-port field in [= candidate-attribute =].

usernameFragment of type DOMString, readonly, nullable

This carries the ufrag as defined in section 15.4 of [[RFC5245]].

relayProtocol of type RTCIceServerTransportProtocol, readonly, nullable

For local candidates of type {{RTCIceCandidateType/"relay"}} this is the protocol used by the endpoint to communicate with the TURN server. For all other candidates it is `null`.

url of type DOMString, readonly, nullable

For local candidates of type {{RTCIceCandidateType/"srflx"}} or type {{RTCIceCandidateType/"relay"}} this is the URL of the ICE server from which the candidate was obtained. For all other candidates it is `null`.

Methods

toJSON()

To invoke the {{toJSON()}} operation of the {{RTCIceCandidate}} interface, run the following steps:

1. Let json be a new {{RTCIceCandidateInit}} dictionary.
2. For each attribute identifier attr in «{{candidate}}, {{sdpMid}}, {{sdpMLineIndex}}, {{usernameFragment}}»:
   1. Let value be the result of getting the underlying value of the attribute identified by attr, given this {{RTCIceCandidate}} object.
   2. Set json[attr] to value.
3. Return json.

Dictionary RTCIceCandidateInit Members

candidate of type DOMString, defaulting to ""

This carries the [= candidate-attribute =] as defined in section 15.1 of [[RFC5245]]. If this represents an end-of-candidates indication, {{candidate}} is an empty string.

sdpMid of type DOMString, nullable, defaulting to null

If not null, this contains the [= media stream "identification-tag" =] defined in [[!RFC5888]] for the media component this candidate is associated with.

sdpMLineIndex of type unsigned short, nullable, defaulting to null

If not null, this indicates the index (starting at zero) of the [= media description =] in the SDP this candidate is associated with.

usernameFragment of type DOMString, nullable, defaulting to null

If not null, this carries the ufrag as defined in section 15.4 of [[RFC5245]].

Constructors

RTCPeerConnectionIceEvent.constructor()

Attributes

candidate of type {{RTCIceCandidate}}, readonly, nullable

The {{candidate}} attribute is the {{RTCIceCandidate}} object with the new ICE candidate that caused the event.

This attribute is set to null when an event is generated to indicate the end of candidate gathering.

Even where there are multiple media components, only one event containing a null candidate is fired.

url of type DOMString, readonly, nullable

The {{url}} attribute is the STUN or TURN URL that identifies the STUN or TURN server used to gather this candidate. If the candidate was not gathered from a STUN or TURN server, this parameter will be set to null.

This attribute is deprecated; it exists for legacy compatibility reasons only. Prefer the candidate {{RTCIceCandidate/url}}.

Dictionary RTCPeerConnectionIceEventInit Members

candidate of type {{RTCIceCandidate}}, nullable

See the {{RTCPeerConnectionIceEvent/candidate}} attribute of the {{RTCPeerConnectionIceEvent}} interface.

url of type DOMString, nullable

The {{url}} attribute is the STUN or TURN URL that identifies the STUN or TURN server used to gather this candidate.

Constructors

RTCPeerConnectionIceErrorEvent.constructor()

Attributes

address of type DOMString, readonly, nullable

The {{address}} attribute is the local IP address used to communicate with the STUN or TURN server.

On a multihomed system, multiple interfaces may be used to contact the server, and this attribute allows the application to figure out on which one the failure occurred.

If the local IP address value is not already exposed as part of a local candidate, the {{address}} attribute will be set to null.

port of type unsigned short, readonly, nullable

The {{port}} attribute is the port used to communicate with the STUN or TURN server.

If the {{address}} attribute is null, the {{port}} attribute is also set to null.

url of type DOMString, readonly

The {{url}} attribute is the STUN or TURN URL that identifies the STUN or TURN server for which the failure occurred.

errorCode of type unsigned short, readonly

The {{errorCode}} attribute is the numeric STUN error code returned by the STUN or TURN server [[STUN-PARAMETERS]].

If no host candidate can reach the server, {{errorCode}} will be set to the value 701 which is outside the STUN error code range. This error is only fired once per server URL while in the {{RTCIceGatheringState}} of {{RTCIceGatheringState/"gathering"}}.

errorText of type USVString, readonly

The {{errorText}} attribute is the STUN reason text returned by the STUN or TURN server [[STUN-PARAMETERS]].

If the server could not be reached, {{errorText}} will be set to an implementation-specific value providing details about the error.

Dictionary RTCPeerConnectionIceErrorEventInit Members

address of type DOMString, nullable

The local address used to communicate with the STUN or TURN server, or null.

port of type unsigned short, nullable

The local port used to communicate with the STUN or TURN server, or null.

url of type DOMString

The STUN or TURN URL that identifies the STUN or TURN server for which the failure occurred.

errorCode of type unsigned short, required

The numeric STUN error code returned by the STUN or TURN server.

errorText of type USVString

The STUN reason text returned by the STUN or TURN server.

Attributes

expires of type {{EpochTimeStamp}}, readonly

The expires attribute indicates the date and time in milliseconds relative to 1970-01-01T00:00:00Z after which the certificate will be considered invalid by the browser. After this time, attempts to construct an {{RTCPeerConnection}} using this certificate fail.

Note that this value might not be reflected in a notAfter parameter in the certificate itself.

Methods

getFingerprints

Returns the list of certificate fingerprints, one of which is computed with the digest algorithm used in the certificate signature.

Dictionary {{RTCRtpParameters}} Members

headerExtensions of type sequence<{{RTCRtpHeaderExtensionParameters}}>, required

A sequence containing parameters for RTP header extensions. Read-only parameter.

rtcp of type {{RTCRtcpParameters}}, required

Parameters used for RTCP. Read-only parameter.

codecs of type sequence<{{RTCRtpCodecParameters}}>, required

A sequence containing the media codecs that an {{RTCRtpSender}} will choose from, as well as entries for RTX, RED and FEC mechanisms. Corresponding to each media codec where retransmission via RTX is enabled, there will be an entry in {{codecs}} with a {{RTCRtpCodec/mimeType}} attribute indicating retransmission via audio/rtx or video/rtx, and an {{RTCRtpCodec/sdpFmtpLine}} attribute (providing the "apt" and "rtx-time" parameters). Read-only parameter.

Dictionary {{RTCRtpSendParameters}} Members

transactionId of type DOMString, required

A unique identifier for the last set of parameters applied. Ensures that {{RTCRtpSender/setParameters}} can only be called based on a previous {{RTCRtpSender/getParameters}}, and that there are no intervening changes. [= Read-only parameter =].

encodings of type sequence<{{RTCRtpEncodingParameters}}>, required

A sequence containing parameters for RTP encodings of media.

Dictionary {{RTCRtpCodingParameters}} Members

rid of type DOMString

If set, this RTP encoding will be sent with the RID header extension as defined by [[!RFC9429]]. The RID is not modifiable via {{RTCRtpSender/setParameters}}. It can only be set or modified in {{RTCPeerConnection/addTransceiver}} on the sending side. Read-only parameter.

Dictionary {{RTCRtpEncodingParameters}} Members

active of type boolean, defaulting to true

Indicates that this encoding is actively being sent. Setting it to false causes this encoding to no longer be sent. Setting it to true causes this encoding to be sent. Since setting the value to false does not cause the SSRC to be removed, an RTCP BYE is not sent.

codec of type RTCRtpCodec

Optional value selecting which codec is used for this encoding's RTP stream. If absent, the user agent can chose to use any negotiated codec.

maxBitrate of type unsigned long

When present, indicates the maximum bitrate that can be used to send this encoding. The user agent is free to allocate bandwidth between the encodings, as long as the {{maxBitrate}} value is not exceeded. The encoding may also be further constrained by other limits (such as per-transport or per-session bandwidth limits) below the maximum specified here. {{maxBitrate}} is computed the same way as the Transport Independent Application Specific Maximum (TIAS) bandwidth defined in [[RFC3890]] Section 6.2.2, which is the maximum bandwidth needed without counting IP or other transport layers like TCP or UDP. The unit of {{maxBitrate}} is bits per second.

How the bitrate is achieved is media and encoding dependent. For video, a frame will always be sent as fast as possible, but frames may be dropped until bitrate is low enough. Thus, even a bitrate of zero will allow sending one frame. For audio, it might be necessary to stop playing if the bitrate does not allow the chosen encoding enough bandwidth to be sent.

maxFramerate of type double

This member can only be present if the sender's kind is "video". When present, indicates the maximum frame rate that can be used to send this encoding, in frames per second. The user agent is free to allocate bandwidth between the encodings, as long as the {{maxFramerate}} value is not exceeded.

If changed with {{RTCRtpSender/setParameters()}}, the new frame rate takes effect after the current picture is completed; setting the max frame rate to zero thus has the effect of freezing the video on the next frame.

scaleResolutionDownBy of type double

This member is only present if the sender's kind is "video". The video's resolution will be scaled down in each dimension by the given value before sending. For example, if the value is 2.0, the video will be scaled down by a factor of 2 in each dimension, resulting in sending a video of one quarter the size. If the value is 1.0, the video will not be affected. The value must be greater than or equal to 1.0. By default, scaling is applied in reverse order by a factor of two, to produce an order of smaller to higher resolutions, e.g. 4:2:1. If there is only one layer, the sender will by default not apply any scaling, (i.e. {{RTCRtpEncodingParameters/scaleResolutionDownBy}} will be 1.0).

Dictionary {{RTCRtcpParameters}} Members

cname of type DOMString

The Canonical Name (CNAME) used by RTCP (e.g. in SDES messages). Read-only parameter.

reducedSize of type boolean

Whether reduced size RTCP [[RFC5506]] is configured (if true) or compound RTCP as specified in [[RFC3550]] (if false). Read-only parameter.

Dictionary {{RTCRtpHeaderExtensionParameters}} Members

uri of type DOMString, required

The URI of the RTP header extension, as defined in [[RFC5285]]. Read-only parameter.

id of type unsigned short, required

The value put in the RTP packet to identify the header extension. Read-only parameter.

encrypted of type boolean

Whether the header extension is encrypted or not. Read-only parameter.

Dictionary {{RTCRtpCodec}} Members

The {{RTCRtpCodec}} dictionary provides information about codec objects.

mimeType of type DOMString, required

The codec MIME media type/subtype. Valid media types and subtypes are listed in [[IANA-RTP-2]].

clockRate of type unsigned long, required

The codec clock rate expressed in Hertz.

channels of type unsigned short

If present, indicates the maximum number of channels (mono=1, stereo=2).

sdpFmtpLine of type DOMString

The "format specific parameters" field from the a=fmtp line in the SDP corresponding to the codec, if one exists, as defined by [[!RFC9429]].

Dictionary {{RTCRtpCodecParameters}} Members

The {{RTCRtpCodecParameters}} dictionary provides information about the negotiated codecs. The fields inherited from {{RTCRtpCodec}} MUST all be Read-only parameters.

For an {{RTCRtpSender}}, the {{RTCRtpCodec/sdpFmtpLine}} parameters come from the {{RTCPeerConnection/[[CurrentRemoteDescription]]}}, and for an {{RTCRtpReceiver}}, they come from the local description (which is {{RTCPeerConnection/[[PendingLocalDescription]]}} if not `null`, and {{RTCPeerConnection/[[CurrentLocalDescription]]}} otherwise).

payloadType of type octet, required

The RTP payload type used to identify this codec. Read-only parameter.

Dictionary {{RTCRtpCapabilities}} Members

codecs of type sequence<{{RTCRtpCodec}}>, required

Supported media codecs as well as entries for RTX, RED and FEC mechanisms. Only combinations that would utilize distinct payload types in a generated SDP offer are to be provided. For example:

1. Two H.264/AVC codecs, one for each of two supported packetization-mode values.
2. Two CN codecs with different clock rates.

There MUST only be a single entry in {{codecs}} for retransmission via RTX, with {{RTCRtpCodec/sdpFmtpLine}} not present.

headerExtensions of type sequence<{{RTCRtpHeaderExtensionCapability}}>, required

Supported RTP header extensions.

Dictionary {{RTCRtpHeaderExtensionCapability}} Members

uri of type DOMString, required

The URI of the RTP header extension, as defined in [[RFC5285]].

Dictionary {{RTCSetParameterOptions}} Members

RTCSetParameterOptions is defined as an empty dictionary to allow for extensibility.

Dictionary RTCDtlsFingerprint Members

algorithm of type DOMString

One of the the hash function algorithms defined in the 'Hash function Textual Names' registry [[!IANA-HASH-FUNCTION]].

value of type DOMString

The value of the certificate fingerprint in lowercase hex string as expressed utilizing the syntax of 'fingerprint' in [[!RFC4572]] Section 5.

Dictionary {{RTCIceParameters}} Members

usernameFragment of type DOMString

The ICE username fragment as defined in [[RFC5245]], Section 7.1.2.3.

password of type DOMString

The ICE password as defined in [[RFC5245]], Section 7.1.2.3.

Attributes

local of type {{RTCIceCandidate}}, readonly

The {{local}} attribute MUST, on getting, return the value of the {{RTCIceCandidatePair/[[Local]]}} internal slot.

remote of type {{RTCIceCandidate}}, readonly

The {{remote}} attribute MUST, on getting, return the value of the {{RTCIceCandidatePair/[[Remote]]}} internal slot.

Attributes

transport of type {{RTCDtlsTransport}}, readonly

The transport over which all SCTP packets for data channels will be sent and received.

state of type {{RTCSctpTransportState}}, readonly

The current state of the SCTP transport. On getting, this attribute MUST return the value of the {{RTCSctpTransport/[[SctpTransportState]]}} slot.

maxMessageSize of type unrestricted double, readonly

The maximum size of data that can be passed to {{RTCDataChannel}}'s {{RTCDataChannel/send()}} method. The attribute MUST, on getting, return the value of the {{RTCSctpTransport/[[MaxMessageSize]]}} slot.

maxChannels of type unsigned short , readonly, nullable

The maximum amount of {{RTCDataChannel}}'s that can be used simultaneously. The attribute MUST, on getting, return the value of the {{RTCSctpTransport/[[MaxChannels]]}} slot.

This attribute's value will be null until the SCTP transport goes into the {{RTCSctpTransportState/"connected"}} state.

onstatechange of type EventHandler

The event type of this event handler is {{RTCSctpTransport/statechange}}.

Error on creating data channels

In some cases, the user agent may be unable to create an {{RTCDataChannel}} 's [= underlying data transport =]. For example, the data channel's {{RTCDataChannel/id}} may be outside the range negotiated by the [[RFC8831]] implementations in the SCTP handshake. When the user agent determines that an {{RTCDataChannel}}'s [= underlying data transport =] cannot be created, the user agent MUST queue a task to run the following steps:

1. Let channel be the {{RTCDataChannel}} object for which the user agent could not create an [= underlying data transport =].

2. Set channel.{{RTCDataChannel/[[ReadyState]]}} to {{RTCDataChannelState/"closed"}}.

3. [= Fire an event =] named {{RTCDataChannel/error}} using the {{RTCErrorEvent}} interface with the {{RTCError/errorDetail}} attribute set to {{RTCErrorDetailType/"data-channel-failure"}} at channel.

4. [= Fire an event =] named close at channel.

Receiving messages on a data channel

When an {{RTCDataChannel}} message has been received via the [= underlying data transport =] with type type and data rawData, the user agent MUST queue a task to run the following steps:

1. Let channel be the {{RTCDataChannel}} object for which the user agent has received a message.

2. Let connection be the {{RTCPeerConnection}} object associated with channel.

3. If channel.{{RTCDataChannel/[[ReadyState]]}} is not {{RTCDataChannelState/"open"}}, abort these steps and discard rawData.

4. Execute the sub step by switching on type and channel.{{RTCDataChannel/binaryType}}:

   • If type indicates that rawData is a string:

     Let data be a DOMString that represents the result of decoding rawData as UTF-8.

   • If type indicates that rawData is binary and {{RTCDataChannel/binaryType}} is "blob":

     Let data be a new {{Blob}} object containing rawData as its raw data source.

   • If type indicates that rawData is binary and {{RTCDataChannel/binaryType}} is "arraybuffer":

     Let data be a new {{ArrayBuffer}} object containing rawData as its raw data source.

5. [= Fire an event =] named {{RTCDataChannel/message}} using the {{MessageEvent}} interface with its origin attribute initialized to the serialization of an origin of connection.{{RTCPeerConnection/[[DocumentOrigin]]}}, and the data attribute initialized to data at channel.

RTCDataChannelEvent

The {{RTCPeerConnection/datachannel}} event uses the {{RTCDataChannelEvent}} interface.

[Exposed=Window]
interface RTCDataChannelEvent : Event {
  constructor(DOMString type, RTCDataChannelEventInit eventInitDict);
  readonly attribute RTCDataChannel channel;
};

dictionary RTCDataChannelEventInit : EventInit {
  required RTCDataChannel channel;
};

Garbage Collection

An {{RTCDataChannel}} object MUST not be garbage collected if its

• {{RTCDataChannel/[[ReadyState]]}} slot is {{RTCDataChannelState/"connecting"}} and at least one event listener is registered for {{RTCDataChannel/open}} events, {{RTCDataChannel/message}} events, {{RTCDataChannel/error}} events, {{RTCDataChannel/closing}} events, or close events.

• {{RTCDataChannel/[[ReadyState]]}} slot is {{RTCDataChannelState/"open"}} and at least one event listener is registered for {{RTCDataChannel/message}} events, {{RTCDataChannel/error}} events, {{RTCDataChannel/closing}} events, or close events.

• {{RTCDataChannel/[[ReadyState]]}} slot is {{RTCDataChannelState/"closing"}} and at least one event listener is registered for {{RTCDataChannel/error}} events, or close events.

• [= underlying data transport =] is established and data is queued to be transmitted.

Peer-to-peer DTMF

This section describes an interface on {{RTCRtpSender}} to send DTMF (phone keypad) values across an {{RTCPeerConnection}}. Details of how DTMF is sent to the other peer are described in [[RFC7874]].

          partial interface RTCRtpSender {
  readonly attribute RTCDTMFSender? dtmf;
};

[Exposed=Window]
interface RTCDTMFSender : EventTarget {
  undefined insertDTMF(DOMString tones, optional unsigned long duration = 100, optional unsigned long interToneGap = 70);
  attribute EventHandler ontonechange;
  readonly attribute boolean canInsertDTMF;
  readonly attribute DOMString toneBuffer;
};

[Exposed=Window]
interface RTCDTMFToneChangeEvent : Event {
  constructor(DOMString type, optional RTCDTMFToneChangeEventInit eventInitDict = {});
  readonly attribute DOMString tone;
};

          dictionary RTCDTMFToneChangeEventInit : EventInit {
  DOMString tone = "";
};

Statistics Model

          partial interface RTCPeerConnection {
  Promise<RTCStatsReport> getStats(optional MediaStreamTrack? selector = null);
};

[Exposed=Window]
interface RTCStatsReport {
  readonly maplike<DOMString, object>;
};

dictionary RTCStats {
  required DOMHighResTimeStamp timestamp;
  required RTCStatsType type;
  required DOMString id;
};

async function gatherStats(pc) {
  try {
    const [sender] = pc.getSenders();
    const baselineReport = await sender.getStats();
    await new Promise(resolve => setTimeout(resolve, aBit)); // wait a bit
    const currentReport = await sender.getStats();

    // compare the elements from the current report with the baseline
    for (const now of currentReport.values()) {
      if (now.type != 'outbound-rtp') continue;

      // get the corresponding stats from the baseline report
      const base = baselineReport.get(now.id);
      if (!base) continue;

      const remoteNow = currentReport.get(now.remoteId);
      const remoteBase = baselineReport.get(base.remoteId);

      const packetsSent = now.packetsSent - base.packetsSent;
      const packetsReceived = remoteNow.packetsReceived -
                              remoteBase.packetsReceived;

      const fractionLost = (packetsSent - packetsReceived) / packetsSent;
      if (fractionLost > 0.3) {
        // if fractionLost is > 0.3, we have probably found the culprit
      }
    }
  } catch (err) {
    console.error(err);
  }
}
      

Media Stream API Extensions for Network Use

Error Handling

Some operations throw or fire {{RTCError}}. This is an extension of {{DOMException}} that carries additional WebRTC-specific information.

[Exposed=Window]
interface RTCError : DOMException {
  constructor(RTCErrorInit init, optional DOMString message = "");
  readonly attribute RTCErrorDetailType errorDetail;
  readonly attribute long? sdpLineNumber;
  readonly attribute long? sctpCauseCode;
  readonly attribute unsigned long? receivedAlert;
  readonly attribute unsigned long? sentAlert;
};

dictionary RTCErrorInit {
  required RTCErrorDetailType errorDetail;
  long sdpLineNumber;
  long sctpCauseCode;
  unsigned long receivedAlert;
  unsigned long sentAlert;
};

enum RTCErrorDetailType {
  "data-channel-failure",
  "dtls-failure",
  "fingerprint-failure",
  "sctp-failure",
  "sdp-syntax-error",
  "hardware-encoder-not-available",
  "hardware-encoder-error"
};

[Exposed=Window]
interface RTCErrorEvent : Event {
  constructor(DOMString type, RTCErrorEventInit eventInitDict);
  [SameObject] readonly attribute RTCError error;
};

          dictionary RTCErrorEventInit : EventInit {
  required RTCError error;
};