WebRTC 1.0: Real-time Communication Between Browsers

W3C Candidate Recommendation

This version:
https://www.w3.org/TR/2020/CR-webrtc-20200825/
Latest published version:
https://www.w3.org/TR/webrtc/
Latest editor's draft:
https://w3c.github.io/webrtc-pc/
Test suite:
https://github.com/web-platform-tests/wpt/tree/master/webrtc/
Implementation report:
https://wpt.fyi/webrtc
Previous version:
https://www.w3.org/TR/2019/CR-webrtc-20191213/
Editors:
Cullen Jennings (Cisco)
Henrik Boström (Google)
Jan-Ivar Bruaroey (Mozilla)
Former editors:
Adam Bergkvist (Ericsson) - Until
Daniel C. Burnett (Invited Expert) - Until
Anant Narayanan (Mozilla) - Until
Bernard Aboba (Microsoft Corporation) - Until
Taylor Brandstetter (Google) - Until
Participate:
GitHub w3c/webrtc-pc
File a bug
Commit history
Pull requests
Participate:
Mailing list
IETF RTCWEB Working Group

Abstract

This document defines a set of ECMAScript APIs in WebIDL to allow media to be sent to and received from another browser or device implementing the appropriate set of real-time protocols. This specification is being developed in conjunction with a protocol specification developed by the IETF RTCWEB group and an API specification to get access to local media devices.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

The API is based on preliminary work done in the WHATWG.

The specification is feature complete and is expected to be stable with no further substantive change. Since the previous Candidate Recommendation, the following substantive changes have been brought to the specification:

Its associated test suite will be used to build an implementation report of the API.

To go into Proposed Recommendation status, the group expects to demonstrate implementation of each feature in at least two deployed browsers, and at least one implementation of each optional feature. Mandatory feature with only one implementation may be marked as optional in a revised Candidate Recommendation where applicable.

This document was published by the Web Real-Time Communications Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation.

GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-webrtc@w3.org (archives).

W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 24 September 2020.

Please see the Working Group's implementation report.

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2019 W3C Process Document.

1. Introduction

This section is non-normative.

There are a number of facets to peer-to-peer communications and video-conferencing in HTML covered by this specification:

This document defines the APIs used for these features. This specification is being developed in conjunction with a protocol specification developed by the IETF RTCWEB group and an API specification to get access to local media devices [GETUSERMEDIA] developed by the WebRTC Working Group. An overview of the system can be found in [RTCWEB-OVERVIEW] and [RTCWEB-SECURITY].

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

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.

3. Terminology

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

Performance.timeOrigin and Performance.now() are defined in [hr-time].

The terms serializable objects, serialization steps, and deserialization steps are defined in [HTML].

The terms MediaStream, MediaStreamTrack, and MediaStreamConstraints are defined in [GETUSERMEDIA]. Note that MediaStream is extended in § 9.2 MediaStream in this document while MediaStreamTrack is extended in § 9.3 MediaStreamTrack in this document.

The term Blob is defined in [FILEAPI].

The term media description is defined in [RFC4566].

The term media transport is defined in [RFC7656].

The term generation is defined in [TRICKLE-ICE] Section 2.

The terms stats object and monitored object are defined in [WEBRTC-STATS].

When referring to exceptions, the terms throw and created are defined in [WEBIDL].

The callback VoidFunction is defined in [WEBIDL].

The term "throw" is used as specified in [INFRA]: it terminates the current processing steps.

The terms fulfilled, rejected, resolved, pending and settled used in the context of Promises are defined in [ECMASCRIPT-6.0].

The terms bundle, bundle-only and bundle-policy are defined in [JSEP].

The AlgorithmIdentifier is defined in [WebCryptoAPI].

Note

The general principles for Javascript APIs apply, including the principle of run-to-completion and no-data-races as defined in [API-DESIGN-PRINCIPLES]. That is, while a task is running, external events do not influence what's visible to the Javascript application. For example, the amount of data buffered on a data channel will increase due to "send" calls while Javascript is executing, and the decrease due to packets being sent will be visible after a task checkpoint.
It is the responsibility of the user agent to make sure the set of values presented to the application is consistent - for instance that getContributingSources() (which is synchronous) returns values for all sources measured at the same time.

4. Peer-to-peer connections

4.1 Introduction

An RTCPeerConnection instance allows an application to establish peer-to-peer communications with another RTCPeerConnection instance in another browser, or to another endpoint implementing the required protocols. Communications are coordinated by the exchange of control messages (called a signaling protocol) over a signaling channel which is provided by unspecified means, but generally by a script in the page via the server, e.g. using Web Sockets or XMLHttpRequest [xhr].

4.2 Configuration

4.2.1 RTCConfiguration Dictionary

The RTCConfiguration defines a set of parameters to configure how the peer-to-peer communication established via RTCPeerConnection is established or re-established.

WebIDLdictionary RTCConfiguration {
  sequence<RTCIceServer> iceServers;
  RTCIceTransportPolicy iceTransportPolicy;
  RTCBundlePolicy bundlePolicy;
  RTCRtcpMuxPolicy rtcpMuxPolicy;
  sequence<RTCCertificate> certificates;
  [EnforceRange] octet iceCandidatePoolSize = 0;
};
Dictionary RTCConfiguration Members
iceServers of type sequence<RTCIceServer>

An array of objects describing servers available to be used by ICE, such as STUN and TURN servers.

iceTransportPolicy of type RTCIceTransportPolicy.

Indicates which candidates the ICE Agent is allowed to use.

bundlePolicy of type RTCBundlePolicy.

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

rtcpMuxPolicy of type RTCRtcpMuxPolicy.

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

certificates of type sequence<RTCCertificate>

A set of certificates that the RTCPeerConnection uses to authenticate.

Valid values for this parameter are created through calls to the 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.

Note

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 [JSEP] (section 3.5.4. and section 4.1.1.).

4.2.2 RTCIceCredentialType Enum

WebIDLenum RTCIceCredentialType {
  "password"
};
Enumeration description
password The credential is a long-term authentication username and password, as described in [RFC5389], Section 10.2.

4.2.3 RTCIceServer Dictionary

The RTCIceServer dictionary is used to describe the STUN and TURN servers that can be used by the ICE Agent to establish a connection with a peer.

WebIDLdictionary RTCIceServer {
  required (DOMString or sequence<DOMString>) urls;
  DOMString username;
  DOMString credential;
  RTCIceCredentialType credentialType = "password";
};
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, and credentialType is "password", 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.

If credentialType is "password", credential represents a long-term authentication password, as described in [RFC5389], Section 10.2.

Note

To support additional values of credentialType, credential may evolve in future as a union.

credentialType of type RTCIceCredentialType, defaulting to "password"

If this RTCIceServer object represents a TURN server, then this attribute specifies how credential should be used when that TURN server requests authorization.

An example array of RTCIceServer objects is:

[
  {urls: 'stun:stun1.example.net'},
  {urls: ['turns:turn.example.org', 'turn:turn.example.net'],
    username: 'user',
    credential: 'myPassword',
    credentialType: 'password'},
];

4.2.4 RTCIceTransportPolicy Enum

As described in [JSEP] (section 4.1.1.), if the iceTransportPolicy member of the RTCConfiguration is specified, it defines the ICE candidate policy [JSEP] (section 3.5.3.) the browser uses to surface the permitted candidates to the application; only these candidates will be used for connectivity checks.

WebIDLenum RTCIceTransportPolicy {
  "relay",
  "all"
};
Enumeration description (non-normative)
relay

The ICE Agent uses only media relay candidates such as candidates passing through a TURN server.

Note
This can be used to prevent the remote endpoint from learning the user's IP addresses, which may be desired in certain use cases. For example, in a "call"-based application, the application may want to prevent an unknown caller from learning the callee's IP addresses until the callee has consented in some way.
all

The ICE Agent can use any type of candidate when this value is specified.

Note
The implementation can still use its own candidate filtering policy in order to limit the IP addresses exposed to the application, as noted in the description of RTCIceCandidate.address.

4.2.5 RTCBundlePolicy Enum

As described in [JSEP] (section 4.1.1.), bundle policy affects which media tracks are negotiated if the remote endpoint is not bundle-aware, and what ICE candidates are gathered. If the remote endpoint is bundle-aware, all media tracks and data channels are bundled onto the same transport.

WebIDLenum RTCBundlePolicy {
  "balanced",
  "max-compat",
  "max-bundle"
};
Enumeration description (non-normative)
balanced Gather ICE candidates for each media type in use (audio, video, and data). If the remote endpoint is not bundle-aware, negotiate only one audio and video track on separate transports.
max-compat Gather ICE candidates for each track. If the remote endpoint is not bundle-aware, negotiate all media tracks on separate transports.
max-bundle Gather ICE candidates for only one track. If the remote endpoint is not bundle-aware, negotiate only one media track.

4.2.6 RTCRtcpMuxPolicy Enum

As described in [JSEP] (section 4.1.1.), the RTCRtcpMuxPolicy affects what ICE candidates are gathered to support non-multiplexed RTCP. The only value defined in this spec is "require".

WebIDLenum RTCRtcpMuxPolicy {
  "require"
};
Enumeration description (non-normative)
require Gather ICE candidates only for RTP and multiplex RTCP on the RTP candidates. If the remote endpoint is not capable of rtcp-mux, session negotiation will fail.

4.2.7 Offer/Answer Options

These dictionaries describe the options that can be used to control the offer/answer creation process.

WebIDLdictionary RTCOfferAnswerOptions {};
Dictionary RTCOfferAnswerOptions Members
WebIDLdictionary RTCOfferOptions : RTCOfferAnswerOptions {
  boolean iceRestart = false;
};
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 [[LocalIceCredentialsToReplace]] slot is not empty, then the generated description will have ICE credentials that are different from the current credentials (as visible in the currentLocalDescription attribute's SDP). Applying the generated description will restart ICE, as described in section 9.1.1.1 of [ICE].

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

Note

Performing an ICE restart is recommended when iceConnectionState transitions to "failed". An application may additionally choose to listen for the iceConnectionState transition to "disconnected" and then use other sources of information (such as using 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.

The RTCAnswerOptions dictionary describe options specific to session description of type "answer" (none in this version of the specification).

WebIDLdictionary RTCAnswerOptions : RTCOfferAnswerOptions {};

4.3 State Definitions

4.3.1 RTCSignalingState Enum

WebIDLenum RTCSignalingState {
  "stable",
  "have-local-offer",
  "have-remote-offer",
  "have-local-pranswer",
  "have-remote-pranswer",
  "closed"
};
Enumeration description
stable There is no offer/answer exchange in progress. This is also the initial state, in which case the local and remote descriptions are empty.
have-local-offer A local description, of type "offer", has been successfully applied.
have-remote-offer A remote description, of type "offer", has been successfully applied.
have-local-pranswer A remote description of type "offer" has been successfully applied and a local description of type "pranswer" has been successfully applied.
have-remote-pranswer A local description of type "offer" has been successfully applied and a remote description of type "pranswer" has been successfully applied.
closed The RTCPeerConnection has been closed; its [[IsClosed]] slot is true.
signaling state transition diagram
Figure 1 Non-normative signaling state transitions diagram. Method calls abbreviated.

An example set of transitions might be:

Caller transition:
Callee transition:

4.3.2 RTCIceGatheringState Enum

WebIDLenum RTCIceGatheringState {
  "new",
  "gathering",
  "complete"
};
Enumeration description
new Any of the RTCIceTransports are in the "new" gathering state and none of the transports are in the "gathering" state, or there are no transports.
gathering Any of the RTCIceTransports are in the "gathering" state.
complete At least one RTCIceTransport exists, and all RTCIceTransports are in the "complete" gathering state.

4.3.3 RTCPeerConnectionState Enum

WebIDLenum RTCPeerConnectionState {
  "closed",
  "failed",
  "disconnected",
  "new",
  "connecting",
  "connected"
};
Enumeration description
closed The RTCPeerConnection object's [[IsClosed]] slot is true.
failed The previous state doesn't apply and any RTCIceTransports are in the "failed" state or any RTCDtlsTransports are in the "failed" state.
disconnected None of the previous states apply and any RTCIceTransports are in the "disconnected" state.
new None of the previous states apply and all RTCIceTransports are in the "new" or "closed" state, and all RTCDtlsTransports are in the "new" or "closed" state, or there are no transports.
connecting None of the previous states apply and any RTCIceTransport is in the "checking" state or any RTCDtlsTransport is in the "connecting" state.
connected None of the previous states apply and all RTCIceTransports are in the "connected", "completed" or "closed" state, and all RTCDtlsTransports are in the "connected" or "closed" state.

4.3.4 RTCIceConnectionState Enum

WebIDLenum RTCIceConnectionState {
  "closed",
  "failed",
  "disconnected",
  "new",
  "checking",
  "completed",
  "connected"
};
Enumeration description
closed The RTCPeerConnection object's [[IsClosed]] slot is true.
failed The previous state doesn't apply and any RTCIceTransports are in the "failed" state.
disconnected None of the previous states apply and any RTCIceTransports are in the "disconnected" state.
new None of the previous states apply and all RTCIceTransports are in the "new" or "closed" state, or there are no transports.
checking None of the previous states apply and any RTCIceTransports are in the "new" or "checking" state.
completed None of the previous states apply and all RTCIceTransports are in the "completed" or "closed" state.
connected None of the previous states apply and all RTCIceTransports are in the "connected", "completed" or "closed" state.

Note that if an RTCIceTransport is discarded as a result of signaling (e.g. RTCP mux or bundling), or created as a result of signaling (e.g. adding a new media description), the state may advance directly from one state to another.

4.4 RTCPeerConnection Interface

The [JSEP] specification, as a whole, describes the details of how the RTCPeerConnection operates. References to specific subsections of [JSEP] are provided as appropriate.

4.4.1 Operation

Calling new RTCPeerConnection(configuration) creates an RTCPeerConnection object.

configuration.iceServers contains information used to find and access the servers used by ICE. The application can supply multiple servers of each type, and any TURN server MAY also be used as a STUN server for the purposes of gathering server reflexive candidates.

An RTCPeerConnection object has a signaling state, a connection state, an ICE gathering state, and an ICE connection state. These are initialized when the object is created.

The ICE protocol implementation of an RTCPeerConnection is represented by an ICE agent [ICE]. Certain RTCPeerConnection methods involve interactions with the ICE Agent, namely addIceCandidate, setConfiguration, setLocalDescription, setRemoteDescription and close. These interactions are described in the relevant sections in this document and in [JSEP]. The ICE Agent also provides indications to the user agent when the state of its internal representation of an RTCIceTransport changes, as described in § 5.6 RTCIceTransport Interface.

The task source for the tasks listed in this section is the networking task source.

Note

The state of the SDP negotiation is represented by the signaling state and the internal variables [[CurrentLocalDescription]], [[CurrentRemoteDescription]], [[PendingLocalDescription]] and [[PendingRemoteDescription]]. These are only set inside the setLocalDescription and setRemoteDescription operations, and modified by the addIceCandidate operation and the surface a candidate procedure. In each case, all the modifications to all the five variables are completed before the procedures fire any events or invoke any callbacks, so the modifications are made visible at a single point in time.

As one of the unloading document cleanup steps, run the following steps:

  1. Let window be document's relevant global object.

  2. For each RTCPeerConnection object connection whose relevant global object is window, close the connection with connection and the value true.

4.4.1.1 Constructor

When the RTCPeerConnection.constructor() is invoked, the user agent MUST run the following steps:

  1. If any of the steps enumerated below fails for a reason not specified here, throw an UnknownError with the message attribute set to an appropriate description.

  2. Let connection be a newly created RTCPeerConnection object.

  3. Let connection have a [[DocumentOrigin]] internal slot, initialized to the current settings object's origin.

  4. Let configuration be the method's first argument.
  5. If the certificates value in configuration is non-empty, run the following steps for each certificate in certificates:

    1. If the value of certificate.expires is less than the current time, throw an InvalidAccessError.

    2. If certificate.[[Origin]] is not same origin with connection.[[DocumentOrigin]], throw an InvalidAccessError.

    3. Store certificate.

  6. Else, generate one or more new RTCCertificate instances with this RTCPeerConnection instance and store them. This MAY happen asynchronously and the value of certificates remains undefined for the subsequent steps. As noted in Section 4.3.2.3 of [RTCWEB-SECURITY], WebRTC utilizes self-signed rather than Public Key Infrastructure (PKI) certificates, so that the expiration check is to ensure that keys are not used indefinitely and additional certificate checks are unnecessary.

  7. Initialize connection's ICE Agent.

  8. If the value of configuration.iceTransportPolicy is undefined, set it to "all".

  9. If the value of configuration.bundlePolicy is undefined, set it to "balanced".

  10. If the value of configuration.rtcpMuxPolicy is undefined, set it to "require".

  11. Let connection have a [[Configuration]] internal slot. Set the configuration specified by configuration.

  12. Let connection have an [[IsClosed]] internal slot, initialized to false.

  13. Let connection have a [[NegotiationNeeded]] internal slot, initialized to false.

  14. Let connection have an [[SctpTransport]] internal slot, initialized to null.

  15. Let connection have an [[Operations]] internal slot, representing an operations chain, initialized to an empty list.

  16. Let connection have a [[UpdateNegotiationNeededFlagOnEmptyChain]] internal slot, initialized to false.

  17. Let connection have an [[LastCreatedOffer]] internal slot, initialized to "".

  18. Let connection have an [[LastCreatedAnswer]] internal slot, initialized to "".

  19. Let connection have an [[EarlyCandidates]] internal slot, initialized to an empty list.

  20. Set connection's signaling state to "stable".

  21. Set connection's ICE connection state to "new".

  22. Set connection's ICE gathering state to "new".

  23. Set connection's connection state to "new".

  24. Let connection have a [[PendingLocalDescription]] internal slot, initialized to null.

  25. Let connection have a [[CurrentLocalDescription]] internal slot, initialized to null.

  26. Let connection have a [[PendingRemoteDescription]] internal slot, initialized to null.

  27. Let connection have a [[CurrentRemoteDescription]] internal slot, initialized to null.

  28. Let connection have a [[LocalIceCredentialsToReplace]] internal slot, initialized to an empty set.

  29. Return connection.

4.4.1.2 Chain an asynchronous operation

An RTCPeerConnection object has an operations chain, [[Operations]], which ensures that only one asynchronous operation in the chain executes concurrently. If subsequent calls are made while the returned promise of a previous call is still not settled, they are added to the chain and executed when all the previous calls have finished executing and their promises have settled.

To chain an operation to an RTCPeerConnection object's operations chain, run the following steps:

  1. Let connection be the RTCPeerConnection object.

  2. If connection.[[IsClosed]] is true, return a promise rejected with a newly created InvalidStateError.

  3. Let operation be the operation to be chained.

  4. Let p be a new promise.

  5. Append operation to [[Operations]].

  6. If the length of [[Operations]] is exactly 1, execute operation.

  7. Upon fulfillment or rejection of the promise returned by the operation, run the following steps:

    1. If connection.[[IsClosed]] is true, abort these steps.

    2. If the promise returned by operation was fulfilled with a value, fulfill p with that value.

    3. If the promise returned by operation was rejected with a value, reject p with that value.

    4. Upon fulfillment or rejection of p, execute the following steps:

      1. If connection.[[IsClosed]] is true, abort these steps.

      2. Remove the first element of [[Operations]].

      3. If [[Operations]] is non-empty, execute the operation represented by the first element of [[Operations]], and abort these steps.

      4. If connection.[[UpdateNegotiationNeededFlagOnEmptyChain]] is false, abort these steps.

      5. Set connection.[[UpdateNegotiationNeededFlagOnEmptyChain]] to false.

      6. Update the negotiation-needed flag for connection.

  8. Return p.

4.4.1.3 Update the connection state

An RTCPeerConnection object has an aggregated connection state. Whenever the state of an RTCDtlsTransport changes or when the [[IsClosed]] slot turns true, the user agent MUST update the connection state by queueing a task that runs the following steps:

  1. Let connection be this RTCPeerConnection object.

  2. Let newState be the value of deriving a new state value as described by the RTCPeerConnectionState enum.

  3. If connection's connection state is equal to newState, abort these steps.

  4. Let connection's connection state be newState.

  5. Fire an event named connectionstatechange at connection.

4.4.1.4 Update the ICE gathering state

To update the ICE gathering state of an RTCPeerConnection instance connection, the user agent MUST queue a task that runs the following steps:

  1. If connection.[[IsClosed]] is true, abort these steps.

  2. Let newState be the value of deriving a new state value as described by the RTCIceGatheringState enum.

  3. If connection's ICE gathering state is equal to newState, abort these steps.

  4. Set connection's ICE gathering state to newState.

  5. Fire an event named icegatheringstatechange at connection.

  6. If newState is "complete", fire an event named icecandidate using the RTCPeerConnectionIceEvent interface with the candidate attribute set to null at connection.

    Note
    The null candidate event is fired to ensure legacy compatibility. New code should monitor the gathering state of RTCIceTransport and/or RTCPeerConnection.
4.4.1.5 Set the RTCSessionDescription

To set a local RTCSessionDescription description on an RTCPeerConnection object connection, run the set an RTCSessionDescription algorithm with remote set to false.

To set a remote RTCSessionDescription description on an RTCPeerConnection object connection, run the set an RTCSessionDescription algorithm with remote set to true.

To set an RTCSessionDescription description on an RTCPeerConnection object connection, given a remote boolean, run the following steps:

  1. Let p be a new promise.

  2. If description.type is "rollback" and connection's signaling state is either "stable", "have-local-pranswer", or "have-remote-pranswer", then reject p with a newly created InvalidStateError and abort these steps.

  3. Let jsepSetOfTransceivers be a shallow copy of connection's set of transceivers.

  4. In parallel, start the process to apply description as described in [JSEP] (section 5.5. and section 5.6.), with these additional restrictions:

    1. Use jsepSetOfTransceivers as the source of truth with regard to what "RtpTransceivers" exist, and their [[JsepMid]] internal slot as their "mid property".

    2. If remote is true, validate back-to-back offers as if answers were applied in between, by running the check for subsequent offers as if it were in stable state.

    3. If applying description leads to modifying a transceiver transceiver, and transceiver.[[Sender]].[[SendEncodings]] is non-empty, and not equal to the encodings that would result from processing description, the process of applying description fails. This specification does not allow remotely initiated RID renegotiation.

    4. If the process to apply description fails for any reason, then the user agent MUST queue a task that runs the following steps:

      1. If connection.[[IsClosed]] is true, then abort these steps.

      2. If description.type is invalid for the current signaling state of connection as described in [JSEP] (section 5.5. and section 5.6.), then reject p with a newly created InvalidStateError and abort these steps.

      3. If the content of description is not valid SDP syntax, then reject p with an RTCError (with errorDetail set to "sdp-syntax-error" and the sdpLineNumber attribute set to the line number in the SDP where the syntax error was detected) and abort these steps.

      4. If remote is true, the connection's RTCRtcpMuxPolicy is require and the description does not use RTCP mux, then reject p with a newly created InvalidAccessError and abort these steps.

      5. If the description attempted to renegotiate RIDs, as described above, then reject p with a newly created InvalidAccessError and abort these steps.

      6. If the content of description is invalid, then reject p with a newly created InvalidAccessError and abort these steps.

      7. For all other errors, reject p with a newly created OperationError.

    5. If description is applied successfully, the user agent MUST queue a task that runs the following steps:

      1. If connection.[[IsClosed]] is true, then abort these steps.

      2. If remote is true and description is of type "offer", then if any addTrack() methods succeeded during the process to apply description, abort these steps and start the process over as if they had succeeded prior, to include the extra transceiver(s) in the process.

      3. If description is of type "offer" and the signaling state of connection is "stable" then for each transceiver in connection's set of transceivers, run the following steps:

        1. Set transceiver.[[Sender]].[[LastStableStateSenderTransport]] to transceiver.[[Sender]].[[SenderTransport]].

        2. Set transceiver.[[Receiver]].[[LastStableStateReceiverTransport]] to transceiver.[[Receiver]].[[ReceiverTransport]].

        3. Set transceiver.[[Receiver]].[[LastStableStateAssociatedRemoteMediaStreams]] to transceiver.[[Receiver]].[[AssociatedRemoteMediaStreams]].

        4. Set transceiver.[[Receiver]].[[LastStableStateReceiveCodecs]] to transceiver.[[Receiver]].[[ReceiveCodecs]].

      4. If remote is false, then run one of the following steps:

        1. If description is of type "offer", set connection.[[PendingLocalDescription]] to a new RTCSessionDescription object constructed from description, set connection's signaling state to "have-local-offer", and release early candidates.

        2. If description is of type "answer", then this completes an offer answer negotiation. Set connection.[[CurrentLocalDescription]] to a new RTCSessionDescription object constructed from description, and set connection.[[CurrentRemoteDescription]] to connection.[[PendingRemoteDescription]]. Set both connection.[[PendingRemoteDescription]] and connection.[[PendingLocalDescription]] to null. Set both connection.[[LastCreatedOffer]] and connection.[[LastCreatedAnswer]] to "", set connection's signaling state to "stable", and release early candidates. Finally, if none of the ICE credentials in connection.[[LocalIceCredentialsToReplace]] are present in description, then set connection.[[LocalIceCredentialsToReplace]] to an empty set.

        3. If description is of type "pranswer", then set connection.[[PendingLocalDescription]] to a new RTCSessionDescription object constructed from description, set connection's signaling state to "have-local-pranswer", and release early candidates.

      5. Otherwise, (if remote is true) run one of the following steps:

        1. If description is of type "offer", set connection.[[PendingRemoteDescription]] attribute to a new RTCSessionDescription object constructed from description, and set connection's signaling state to "have-remote-offer".

        2. If description is of type "answer", then this completes an offer answer negotiation. Set connection.[[CurrentRemoteDescription]] to a new RTCSessionDescription object constructed from description, and set connection.[[CurrentLocalDescription]] to connection.[[PendingLocalDescription]]. Set both connection.[[PendingRemoteDescription]] and connection.[[PendingLocalDescription]] to null. Set both connection.[[LastCreatedOffer]] and connection.[[LastCreatedAnswer]] to "", and set connection's signaling state to "stable". Finally, if none of the ICE credentials in connection.[[LocalIceCredentialsToReplace]] are present in the newly set connection.[[CurrentLocalDescription]], then set connection.[[LocalIceCredentialsToReplace]] to an empty set.

        3. If description is of type "pranswer", then set connection.[[PendingRemoteDescription]] to a new RTCSessionDescription object constructed from description and set connection's signaling state to "have-remote-pranswer".

      6. If description is of type "answer", and it initiates the closure of an existing SCTP association, as defined in [SCTP-SDP], Sections 10.3 and 10.4, set the value of connection.[[SctpTransport]] to null.

      7. Let trackEventInits, muteTracks, addList, removeList and errorList be empty lists.

      8. If description is of type "answer" or "pranswer", then run the following steps:

        1. If description initiates the establishment of a new SCTP association, as defined in [SCTP-SDP], Sections 10.3 and 10.4, create an RTCSctpTransport with an initial state of "connecting" and assign the result to the [[SctpTransport]] slot. Otherwise, if an SCTP association is established, but the max-message-size SDP attribute is updated, update the data max message size of connection.[[SctpTransport]].

        2. If description negotiates the DTLS role of the SCTP transport, then for each RTCDataChannel, channel, with a null id, run the following step:

          1. Give channel a new ID generated according to [RTCWEB-DATA-PROTOCOL]. If no available ID could be generated, set channel.[[ReadyState]] to "closed", and add channnel to errorList.
      9. If description is not of type "rollback", then run the following steps:

        1. If remote is false, then run the following steps for each media description in description:

          1. If the media description was not yet associated with an RTCRtpTransceiver object then run the following steps:

            1. Let transceiver be the RTCRtpTransceiver used to create the media description.

            2. Set transceiver.[[Mid]] to transceiver.[[JsepMid]].

            3. If transceiver.[[Stopped]] is true, abort these sub steps.

            4. If the media description is indicated as using an existing media transport according to [BUNDLE], let transport be the RTCDtlsTransport object representing the RTP/RTCP component of that transport.

            5. Otherwise, let transport be a newly created RTCDtlsTransport object with a new underlying RTCIceTransport.

            6. Set transceiver.[[Sender]].[[SenderTransport]] to transport.

            7. Set transceiver.[[Receiver]].[[ReceiverTransport]] to transport.

          2. Let transceiver be the RTCRtpTransceiver associated with the media description.

          3. If transceiver.[[Stopped]] is true, abort these sub steps.

          4. Let direction be an RTCRtpTransceiverDirection value representing the direction from the media description.

          5. If direction is "sendrecv" or "recvonly", set transceiver.[[Receptive]] to true, otherwise set it to false.

          6. Set transceiver.[[Receiver]].[[ReceiveCodecs]] to the codecs that description negotiates for receiving and which the user agent is currently prepared to receive.

            Note

            If the direction is "sendonly" or "inactive", the receiver is not prepared to receive anything, and the list will be empty.

          7. If description is of type "answer" or "pranswer", then run the following steps:

            1. Set transceiver.[[Sender]].[[SendCodecs]] to the codecs that description negotiates for sending and which the user agent is currently capable of sending, and set transceiver.[[Sender]].[[LastReturnedParameters]] to null.

            2. If direction is "sendonly" or "inactive", and transceiver.[[FiredDirection]] is either "sendrecv" or "recvonly", then run the following steps:

              1. Set the associated remote streams given transceiver.[[Receiver]], an empty list, another empty list, and removeList.

              2. process the removal of a remote track for the media description, given transceiver and muteTracks.

            3. Set transceiver.[[CurrentDirection]] and transceiver.[[FiredDirection]] to direction.

        2. Otherwise, (if remote is true) run the following steps for each media description in description:

          1. If the description is of type "offer" and contains a request to receive simulcast, use the order of the rid values specified in the simulcast attribute to create an RTCRtpEncodingParameters dictionary for each of the simulcast layers, populating the rid member according to the corresponding rid value, and let sendEncodings be the list containing the created dictionaries. Otherwise, let sendEncodings be an empty list.

          2. Let supportedEncodings be the maximum number of encodings that the implementation can support. If the length of sendEncodings is greater than supportedEncodings, truncate sendEncodings so that its length is supportedEncodings.
          3. If sendEncodings is non-empty, set each encoding's scaleResolutionDownBy to 2^(length of sendEncodings - encoding index - 1).
          4. As described by [JSEP] (section 5.10.), attempt to find an existing RTCRtpTransceiver object, transceiver, to represent the media description.

          5. If a suitable transceiver was found (transceiver is set) and sendEncodings is non-empty, set transceiver.[[Sender]].[[SendEncodings]] to sendEncodings, and set transceiver.[[Sender]].[[LastReturnedParameters]] to null.

          6. If no suitable transceiver was found (transceiver is unset), run the following steps:

            1. Create an RTCRtpSender, sender, from the media description using sendEncodings.

            2. Create an RTCRtpReceiver, receiver, from the media description.

            3. Create an RTCRtpTransceiver with sender, receiver and an RTCRtpTransceiverDirection value of "recvonly", and let transceiver be the result.

            4. Add transceiver to the connection's set of transceivers.

          7. If description is of type "answer" or "pranswer", and transceiver. [[Sender]].[[SendEncodings]] .length is greater than 1, then run the following steps:

            1. If description indicates that simulcast is not supported or desired, then remove all dictionaries in transceiver.[[Sender]].[[SendEncodings]] except the first one and abort these sub steps.

            2. If description rejects any of the offered layers, then remove the dictionaries that correspond to rejected layers from transceiver.[[Sender]].[[SendEncodings]].

            3. Update the paused status as indicated by [MMUSIC-SIMULCAST] of each simulcast layer by setting the active member on the corresponding dictionaries in transceiver.[[Sender]].[[SendEncodings]] to true for unpaused or to false for paused.

          8. Set transceiver.[[Mid]] to transceiver.[[JsepMid]].

          9. Let direction be an RTCRtpTransceiverDirection value representing the direction from the media description, but with the send and receive directions reversed to represent this peer's point of view. If the media description is rejected, set direction to "inactive".

          10. If direction is "sendrecv" or "recvonly", let msids be a list of the MSIDs that the media description indicates transceiver.[[Receiver]].[[ReceiverTrack]] is to be associated with. Otherwise, let msids be an empty list.

            Note
            msids will be an empty list here if media description is rejected.
          11. Process remote tracks with transceiver, direction, msids, addList, removeList, and trackEventInits.

          12. Set transceiver.[[Receiver]].[[ReceiveCodecs]] to the codecs that description negotiates for receiving and which the user agent is currently prepared to receive.

          13. If description is of type "answer" or "pranswer", then run the following steps:

            1. Set transceiver.[[Sender]].[[SendCodecs]] to the codecs that description negotiates for sending and which the user agent is currently capable of sending.

            2. Set transceiver.[[CurrentDirection]] and transceiver.[[Direction]]s to direction.

            3. Let transport be the RTCDtlsTransport object representing the RTP/RTCP component of the media transport used by transceiver's associated media description, according to [BUNDLE].

            4. Set transceiver.[[Sender]].[[SenderTransport]] to transport.

            5. Set transceiver.[[Receiver]].[[ReceiverTransport]] to transport.

            6. Set the [[IceRole]] of transport according to the rules of [RFC8445].

              Note
              The rules of [RFC8445] that apply here are: This ensures that [[IceRole]] always has a value after the first offer is processed.
          14. If the media description is rejected, and transceiver.[[Stopped]] is false, then stop the RTCRtpTransceiver transceiver.

      10. Otherwise, (if description is of type "rollback") run the following steps:

        1. For each transceiver in the connection's set of transceivers run the following steps:

          1. If the transceiver was not associated with a media description prior to applying the RTCSessionDescription that is being rolled back, disassociate it and set both transceiver.[[JsepMid]] and transceiver.[[Mid]] to null.

          2. Set transceiver.[[Sender]].[[SenderTransport]] to transceiver.[[Sender]].[[LastStableStateSenderTransport]].

          3. Set transceiver.[[Receiver]].[[ReceiverTransport]] to transceiver.[[Receiver]].[[LastStableStateReceiverTransport]].

          4. Set transceiver.[[Receiver]].[[ReceiveCodecs]] to transceiver.[[Receiver]].[[LastStableStateReceiveCodecs]].

          5. If the signaling state of connection is "have-remote-offer", run the following sub steps:

            1. Let msids be a list of the ids of all MediaStream objects in transceiver.[[Receiver]].[[LastStableStateAssociatedRemoteMediaStreams]], or an empty list if there are none.

            2. Process remote tracks with transceiver, transceiver.[[CurrentDirection]], msids, addList, removeList, and trackEventInits.

          6. If the transceiver was created by applying the RTCSessionDescription that is being rolled back, and a track has never been attached to it via addTrack(), then stop the RTCRtpTransceiver transceiver, and remove it from connection's set of transceivers.

        2. Set connection.[[PendingLocalDescription]] and connection.[[PendingRemoteDescription]] to null, and set connection's signaling state to "stable".

      11. If description is of type "answer", then run the following steps:

        1. For each transceiver in the connection's set of transceivers run the following steps:

          1. If transceiver is stopped, associated with an m= section and the associated m= section is rejected in connection.[[CurrentLocalDescription]] or connection.[[CurrentRemoteDescription]], remove the transceiver from the connection's set of transceivers.

      12. If connection's signaling state is now "stable", run the following steps:

        1. For any transceiver that was removed from the set of transceivers in a previous step, if any of its transports (transceiver.[[Sender]].[[SenderTransport]] or transceiver.[[Receiver]].[[ReceiverTransport]]) are still not closed and they're no longer referenced by a non-stopped transceiver, close the RTCDtlsTransports and their associated RTCIceTransports. This results in events firing on these objects in a queued task.

        2. Clear the negotiation-needed flag and update the negotiation-needed flag.

      13. If connection's signaling state changed above, fire an event named signalingstatechange at connection.

      14. For each channel in errorList, fire an event named error using the RTCErrorEvent interface with the errorDetail attribute set to "data-channel-failure" at channel.

      15. For each track in muteTracks, set the muted state of track to the value true.

      16. For each stream and track pair in removeList, remove the track track from stream.

      17. For each stream and track pair in addList, add the track track to stream.

      18. For each entry entry in trackEventInits, fire an event named track using the RTCTrackEvent interface with its receiver attribute initialized to entry.receiver, its track attribute initialized to entry.track, its streams attribute initialized to entry.streams and its transceiver attribute initialized to entry.transceiver at the connection object.

      19. Resolve p with undefined.

  5. Return p.

4.4.1.6 Set the configuration

To set a configuration, run the following steps:

  1. Let configuration be the RTCConfiguration dictionary to be processed.

  2. Let connection be the target RTCPeerConnection object.

  3. If configuration.certificates is set, run the following steps:

    1. If the length of configuration.certificates is different from the length of connection.[[Configuration]].certificates, throw an InvalidModificationError.

    2. Let index be initialized to 0.

    3. Let size be initialized to the length of configuration.certificates.

    4. While index is less than size, run the following steps:

      1. If the ECMAScript object represented by the value of configuration.certificates at index is not the same as the ECMAScript object represented by the value of connection.[[Configuration]].certificates at index, throw an InvalidModificationError.

      2. Increment index by 1.

  4. If the value of configuration.bundlePolicy is set and its value differs from the connection's bundle policy, throw an InvalidModificationError.

  5. If the value of configuration.rtcpMuxPolicy is set and its value differs from the connection's rtcpMux policy, throw an InvalidModificationError.

  6. If the value of configuration.iceCandidatePoolSize is set and its value differs from the connection's previously set iceCandidatePoolSize, and setLocalDescription has already been called, throw an InvalidModificationError.

  7. Set the ICE Agent's ICE transports setting to the value of configuration.iceTransportPolicy. As defined in [JSEP] (section 4.1.16.), if the new ICE transports setting changes the existing setting, no action will be taken until the next gathering phase. If a script wants this to happen immediately, it should do an ICE restart.

  8. Set the ICE Agent's prefetched ICE candidate pool size as defined in [JSEP] (section 3.5.4. and section 4.1.1.) to the value of configuration.iceCandidatePoolSize. If the new ICE candidate pool size changes the existing setting, this may result in immediate gathering of new pooled candidates, or discarding of existing pooled candidates, as defined in [JSEP] (section 4.1.16.).

  9. Let validatedServers be an empty list.

  10. If configuration.iceServers is defined, then run the following steps for each element:

    1. Let server be the current list element.

    2. Let urls be server.urls.

    3. If urls is a string, set urls to a list consisting of just that string.

    4. If urls is empty, throw a SyntaxError.

    5. For each url in urls run the following steps:

      1. Parse the url using the generic URI syntax defined in [RFC3986] and obtain the scheme name. If the parsing based on the syntax defined in [RFC3986] fails, throw a SyntaxError. If the scheme name is not implemented by the browser throw a NotSupportedError. If scheme name is turn or turns, and parsing the url using the syntax defined in [RFC7065] fails, throw a SyntaxError. If scheme name is stun or stuns, and parsing the url using the syntax defined in [RFC7064] fails, throw a SyntaxError.

      2. If scheme name is turn or turns, and either of server.username or server.credential are omitted, then throw an InvalidAccessError.

      3. If scheme name is turn or turns, and server.credentialType is "password", and server.credential is not a DOMString, then throw an InvalidAccessError.

    6. Append server to validatedServers.

  11. Set the ICE Agent's ICE servers list to validatedServers.

    As defined in [JSEP] (section 4.1.16.), if a new list of servers replaces the ICE Agent's existing ICE servers list, no action will be taken until the next gathering phase. If a script wants this to happen immediately, it should do an ICE restart. However, if the ICE candidate pool has a nonzero size, any existing pooled candidates will be discarded, and new candidates will be gathered from the new servers.

  12. Store configuration in the [[Configuration]] internal slot.

4.4.2 Interface Definition

The RTCPeerConnection interface presented in this section is extended by several partial interfaces throughout this specification. Notably, the RTP Media API section, which adds the APIs to send and receive MediaStreamTrack objects.

WebIDL[Exposed=Window]
interface RTCPeerConnection : EventTarget  {
  constructor(optional RTCConfiguration configuration = {});
  Promise<RTCSessionDescriptionInit> createOffer(optional RTCOfferOptions options = {});
  Promise<RTCSessionDescriptionInit> createAnswer(optional RTCAnswerOptions options = {});
  Promise<void> setLocalDescription(optional RTCLocalSessionDescriptionInit description = {});
  readonly attribute RTCSessionDescription? localDescription;
  readonly attribute RTCSessionDescription? currentLocalDescription;
  readonly attribute RTCSessionDescription? pendingLocalDescription;
  Promise<void> setRemoteDescription(RTCSessionDescriptionInit description);
  readonly attribute RTCSessionDescription? remoteDescription;
  readonly attribute RTCSessionDescription? currentRemoteDescription;
  readonly attribute RTCSessionDescription? pendingRemoteDescription;
  Promise<void> addIceCandidate(optional RTCIceCandidateInit candidate = {});
  readonly attribute RTCSignalingState signalingState;
  readonly attribute RTCIceGatheringState iceGatheringState;
  readonly attribute RTCIceConnectionState iceConnectionState;
  readonly attribute RTCPeerConnectionState connectionState;
  readonly attribute boolean? canTrickleIceCandidates;
  void restartIce();
  RTCConfiguration getConfiguration();
  void setConfiguration(optional RTCConfiguration configuration = {});
  void close();
  attribute EventHandler onnegotiationneeded;
  attribute EventHandler onicecandidate;
  attribute EventHandler onicecandidateerror;
  attribute EventHandler onsignalingstatechange;
  attribute EventHandler oniceconnectionstatechange;
  attribute EventHandler onicegatheringstatechange;
  attribute EventHandler onconnectionstatechange;

  // Legacy Interface Extensions
  // Supporting the methods in this section is optional.
  // If these methods are supported
  // they must be implemented as defined
  // in section "Legacy Interface Extensions"
  Promise<void> createOffer(RTCSessionDescriptionCallback successCallback,
                            RTCPeerConnectionErrorCallback failureCallback,
                            optional RTCOfferOptions options = {});
  Promise<void> setLocalDescription(optional RTCLocalSessionDescriptionInit description = {},
                                    VoidFunction successCallback,
                                    RTCPeerConnectionErrorCallback failureCallback);
  Promise<void> createAnswer(RTCSessionDescriptionCallback successCallback,
                             RTCPeerConnectionErrorCallback failureCallback);
  Promise<void> setRemoteDescription(RTCSessionDescriptionInit description,
                                     VoidFunction successCallback,
                                     RTCPeerConnectionErrorCallback failureCallback);
  Promise<void> addIceCandidate(RTCIceCandidateInit candidate,
                                VoidFunction successCallback,
                                RTCPeerConnectionErrorCallback failureCallback);
};
Attributes
localDescription of type RTCSessionDescription, readonly, nullable

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

Note that [[CurrentLocalDescription]].sdp and [[PendingLocalDescription]].sdp need not be string-wise identical to the 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 [[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 [[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 [[PendingRemoteDescription]] if it is not null and otherwise it MUST return [[CurrentRemoteDescription]].

Note that [[CurrentRemoteDescription]].sdp and [[PendingRemoteDescription]].sdp need not be string-wise identical to the 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 [[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 addIceCandidate() since the offer or answer was created.

pendingRemoteDescription of type RTCSessionDescription, readonly, nullable

The pendingRemoteDescription attribute MUST return [[PendingRemoteDescription]].

It represents a remote description that is in the process of being negotiated, complete with any remote candidates that have been supplied via 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 object's signaling state.

iceGatheringState of type RTCIceGatheringState, readonly

The iceGatheringState attribute MUST return the ICE gathering state of the RTCPeerConnection instance.

iceConnectionState of type RTCIceConnectionState, readonly

The iceConnectionState attribute MUST return the ICE connection state of the RTCPeerConnection instance.

connectionState of type RTCPeerConnectionState, readonly

The connectionState attribute MUST return the connection state of the RTCPeerConnection instance.

canTrickleIceCandidates of type boolean, readonly, nullable

The canTrickleIceCandidates attribute indicates whether the remote peer is able to accept trickled ICE candidates [TRICKLE-ICE]. The value is determined based on whether a remote description indicates support for trickle ICE, as defined in [JSEP] (section 4.1.15.). Prior to the completion of setRemoteDescription, this value is null.

onnegotiationneeded of type EventHandler
The event type of this event handler is negotiationneeded.
onicecandidate of type EventHandler
The event type of this event handler is icecandidate.
onicecandidateerror of type EventHandler
The event type of this event handler is icecandidateerror.
onsignalingstatechange of type EventHandler
The event type of this event handler is signalingstatechange.
oniceconnectionstatechange of type EventHandler
The event type of this event handler is iceconnectionstatechange
onicegatheringstatechange of type EventHandler
The event type of this event handler is icegatheringstatechange.
onconnectionstatechange of type EventHandler
The event type of this event handler is 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 MediaStreamTracks 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 [JSEP], except the user agent MUST treat a stopping transceiver as stopped for the purposes of JSEP 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 usernameFragment, password and ICE options (as defined in [ICE], Section 14) and may also contain any local candidates that have been gathered by the agent.

The 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.(This is a fingerprinting vector.)

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.[[IsClosed]] is true, return a promise rejected with a newly 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's signaling state is neither "stable" nor "have-local-offer", return a promise rejected with a newly 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 [JSEP] (section 4.1.6.).

  3. If this inspection failed for any reason, reject p with a newly 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.[[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.

    Note
    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 RTCRtpTransceivers, generate an SDP offer, sdpString, as described in [JSEP] (section 5.2.).

    1. As described in [BUNDLE] (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 is said to be the value of the RTCRtpTransceiver.[[PreferredCodecs]] with the following filtering applied (or said not to be set if [[PreferredCodecs]] is empty):

      1. If the direction is "sendrecv", exclude any codecs not included in the intersection of RTCRtpSender.getCapabilities(kind).codecs and RTCRtpReceiver.getCapabilities(kind).codecs.

      2. If the direction is "sendonly", exclude any codecs not included in RTCRtpSender.getCapabilities(kind).codecs.

      3. If the direction is "recvonly", exclude any codecs not included in RTCRtpReceiver.getCapabilities(kind).codecs.

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

    3. If the length of the [[SendEncodings]] slot of the RTCRtpSender is larger than 1, then for each encoding given in [[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 encodings field. No RID restrictions are set.

      Note

      [SDP-SIMULCAST] 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 type member initialized to the string "offer" and its sdp member initialized to sdpString.

  5. Set the [[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 MediaStreamTracks 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 [JSEP].

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

The 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 [JSEP] (section 4.1.8.1.), by setting the type to "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.[[IsClosed]] is true, return a promise rejected with a newly 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's signaling state is neither "have-remote-offer" nor "have-local-pranswer", return a promise rejected with a newly 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 [JSEP] (section 4.1.7.).

  3. If this inspection failed for any reason, reject p with a newly 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.[[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.

    Note
    This may be necessary if, for example, createAnswer was called when an RTCRtpTransceiver's direction was "recvonly", but while performing the in-parallel steps to create an answer, the direction was changed to "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 RTCRtpTransceivers, generate an SDP answer, sdpString, as described in [JSEP] (section 5.3.).

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

      1. If the direction is "sendrecv", exclude any codecs not included in the intersection of RTCRtpSender.getCapabilities(kind).codecs and RTCRtpReceiver.getCapabilities(kind).codecs.

      2. If the direction is "sendonly", exclude any codecs not included in RTCRtpSender.getCapabilities(kind).codecs.

      3. If the direction is "recvonly", exclude any codecs not included in RTCRtpReceiver.getCapabilities(kind).codecs.

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

    2. If the length of the [[SendEncodings]] slot of the RTCRtpSender is larger than 1, then for each encoding given in [[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 encodings field. No RID restrictions are set.

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

  5. Set the [[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 [JSEP] (section 5.4.), 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.sdp.

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

    1. Let type be description.type if present, or "offer" if not present and connection's signaling state is either "stable", "have-local-offer", or "have-remote-pranswer"; otherwise "answer".

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

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

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

      1. Set sdp to the value of connection.[[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 reacting to p with a fulfillment step that sets the local RTCSessionDescription indicated by its first argument.

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

      1. Set sdp to the value of connection.[[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 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 RTCSessionDescription indicated by {type, answer.sdp}.

    6. Return the result of setting the local RTCSessionDescription indicated by {type, sdp}.

Note

As noted in [JSEP] (section 5.9.), 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.type is "offer" and is invalid for the current signaling state of connection as described in [JSEP] (section 5.5. and section 5.6.), then run the following sub steps:

      1. Let p be the result of setting the local RTCSessionDescription indicated by {type: "rollback"}.

      2. Return the result of reacting to p with a fulfillment step that sets the remote RTCSessionDescription description, and abort these steps.

    2. Return the result of setting the remote RTCSessionDescription 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 candidate member. The only members of the argument used by this method are candidate, sdpMid, sdpMLineIndex, and 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.candidate is not an empty string and both candidate.sdpMid and candidate.sdpMLineIndex are null, return a promise rejected with a newly created TypeError.

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

    1. If remoteDescription is null return a promise rejected with a newly created InvalidStateError.

    2. If candidate.sdpMid is not null, run the following steps:

      1. If candidate.sdpMid is not equal to the mid of any media description in remoteDescription, return a promise rejected with a newly created OperationError.

    3. Else, if candidate.sdpMLineIndex is not null, run the following steps:

      1. If candidate.sdpMLineIndex is equal to or larger than the number of media descriptions in remoteDescription, return a promise rejected with a newly created OperationError.

    4. If either candidate.sdpMid or candidate.sdpMLineIndex indicate a media description in remoteDescription whose associated transceiver is stopped, return a promise resolved with undefined.

    5. If candidate.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 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 [JSEP] (section 4.1.17.). Use candidate.usernameFragment to identify the ICE generation; if usernameFragment is null, process the candidate for the most recent ICE generation. If candidate.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.sdpMid and candidate.sdpMLineIndex are null, then this applies to all media descriptions.

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

        1. If connection.[[IsClosed]] is true, then abort these steps.

        2. Reject p with a newly 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.[[IsClosed]] is true, then abort these steps.

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

        3. If connection.[[CurrentRemoteDescription]] is not null, and represents the ICE generation for which candidate was processed, add candidate to connection.[[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 iceTransportPolicy member of the RTCConfiguration is relay, candidates requiring external resolution, such as mDNS candidates and DNS candidates, MUST be prohibited.

Note

Due to WebIDL processing, 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 [ICE].

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.[[LocalIceCredentialsToReplace]], and populate it with all ICE credentials (ice-ufrag and ice-pwd as defined in section 15.4 of [ICE]) found in connection.[[CurrentLocalDescription]], as well as all ICE credentials found in connection.[[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 [[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 [JSEP] (section 3.5.1.), 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.[[IsClosed]] is true, 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.[[IsClosed]] is true, abort these steps.

  2. Set connection.[[IsClosed]] to true.

  3. Set connection's signaling state to "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.[[Stopped]] is true, abort these sub steps.

    2. Stop the RTCRtpTransceiver with transceiver and disappear.

  5. Set the [[ReadyState]] slot of each of connection's RTCDataChannels to "closed".

    Note
    The RTCDataChannels will be closed abruptly and the closing procedure will not be invoked.
  6. If connection.[[SctpTransport]] is not null, tear down the underlying SCTP association by sending an SCTP ABORT chunk and set the [[SctpTransportState]] to "closed".

  7. Set the [[DtlsTransportState]] slot of each of connection's RTCDtlsTransports to "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 [[IceTransportState]] slot of each of connection's RTCIceTransports to "closed".

  10. Set connection's ICE connection state to "closed". This does not fire any event.

  11. Set connection's connection state to "closed". This does not fire any event.

4.4.3 Legacy Interface Extensions

Note
The IDL definition of these methods are documented in the main definition of the RTCPeerConnection interface since overloaded functions are not allowed to be defined in partial interfaces.

Supporting the methods in this section is optional. However, if these methods are supported it is mandatory to implement according to what is specified here.

Note
The addStream method that used to exist on RTCPeerConnection is easy to polyfill as:
RTCPeerConnection.prototype.addStream = function(stream) {
  stream.getTracks().forEach((track) => this.addTrack(track, stream));
};
4.4.3.1 Method extensions
Methods
createOffer

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

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

  2. Let failureCallback be the callback indicated by the method's second argument.

  3. Let options be the callback indicated by the method's third argument.

  4. Run the steps specified by RTCPeerConnection's createOffer() method with options as the sole argument, and let p be the resulting promise.

  5. Upon fulfillment of p with value offer, invoke successCallback with offer as the argument.

  6. Upon rejection of p with reason r, invoke failureCallback with r as the argument.

  7. Return a promise resolved with undefined.

setLocalDescription

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

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

  2. Let successCallback be the callback indicated by the method's second argument.

  3. Let failureCallback be the callback indicated by the method's third argument.

  4. Run the steps specified by RTCPeerConnection's setLocalDescription method with description as the sole argument, and let p be the resulting promise.

  5. Upon fulfillment of p, invoke successCallback with undefined as the argument.

  6. Upon rejection of p with reason r, invoke failureCallback with r as the argument.

  7. Return a promise resolved with undefined.

createAnswer
Note
The legacy createAnswer method does not take an RTCAnswerOptions parameter, since no known legacy createAnswer implementation ever supported it.

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

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

  2. Let failureCallback be the callback indicated by the method's second argument.

  3. Run the steps specified by RTCPeerConnection's createAnswer() method with no arguments, and let p be the resulting promise.

  4. Upon fulfillment of p with value answer, invoke successCallback with answer as the argument.

  5. Upon rejection of p with reason r, invoke failureCallback with r as the argument.

  6. Return a promise resolved with undefined.

setRemoteDescription

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

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

  2. Let successCallback be the callback indicated by the method's second argument.

  3. Let failureCallback be the callback indicated by the method's third argument.

  4. Run the steps specified by RTCPeerConnection's setRemoteDescription method with description as the sole argument, and let p be the resulting promise.

  5. Upon fulfillment of p, invoke successCallback with undefined as the argument.

  6. Upon rejection of p with reason r, invoke failureCallback with r as the argument.

  7. Return a promise resolved with undefined.

addIceCandidate

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

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

  2. Let successCallback be the callback indicated by the method's second argument.

  3. Let failureCallback be the callback indicated by the method's third argument.

  4. Run the steps specified by RTCPeerConnection's addIceCandidate() method with candidate as the sole argument, and let p be the resulting promise.

  5. Upon fulfillment of p, invoke successCallback with undefined as the argument.

  6. Upon rejection of p with reason r, invoke failureCallback with r as the argument.

  7. Return a promise resolved with undefined.

Callback Definitions

These callbacks are only used on the legacy APIs.

RTCPeerConnectionErrorCallback
WebIDLcallback RTCPeerConnectionErrorCallback = void (DOMException error);
Callback RTCPeerConnectionErrorCallback Parameters
error of type DOMException
An error object encapsulating information about what went wrong.
RTCSessionDescriptionCallback
WebIDLcallback RTCSessionDescriptionCallback = void (RTCSessionDescriptionInit description);
Callback RTCSessionDescriptionCallback Parameters
description of type RTCSessionDescriptionInit
The object containing the SDP [SDP].
4.4.3.2 Legacy configuration extensions

This section describes a set of legacy extensions that may be used to influence how an offer is created, in addition to the media added to the RTCPeerConnection. Developers are encouraged to use the RTCRtpTransceiver API instead.

When createOffer is called with any of the legacy options specified in this section, run the followings steps instead of the regular createOffer steps:

  1. Let options be the methods first argument.

  2. Let connection be the current RTCPeerConnection object.

  3. For each offerToReceive<Kind> member in options with kind, kind, run the following steps:

    1. If the value of the dictionary member is false,
      1. For each non-stopped "sendrecv" transceiver of transceiver kind kind, set transceiver.[[Direction]] to "sendonly".

      2. For each non-stopped "recvonly" transceiver of transceiver kind kind, set transceiver.[[Direction]] to "inactive".

      Continue with the next option, if any.

    2. If connection has any non-stopped "sendrecv" or "recvonly" transceivers of transceiver kind kind, continue with the next option, if any.

    3. Let transceiver be the result of invoking the equivalent of connection.addTransceiver(kind), except that this operation MUST NOT update the negotiation-needed flag.

    4. If transceiver is unset because the previous operation threw an error, abort these steps.

    5. Set transceiver.[[Direction]] to "recvonly".

  4. Run the steps specified by createOffer to create the offer.

WebIDLpartial dictionary RTCOfferOptions {
  boolean offerToReceiveAudio;
  boolean offerToReceiveVideo;
};
Attributes
offerToReceiveAudio of type boolean

This setting provides additional control over the directionality of audio. For example, it can be used to ensure that audio can be received, regardless if audio is sent or not.

offerToReceiveVideo of type boolean

This setting provides additional control over the directionality of video. For example, it can be used to ensure that video can be received, regardless if video is sent or not.

4.4.4 Garbage collection

An RTCPeerConnection object MUST not be garbage collected as long as any event can cause an event handler to be triggered on the object. When the object's [[IsClosed]] internal slot is true, no such event handler can be triggered and it is therefore safe to garbage collect the object.

All RTCDataChannel and MediaStreamTrack objects that are connected to an RTCPeerConnection have a strong reference to the RTCPeerConnection object.

4.5 Error Handling

4.5.1 General Principles

All methods that return promises are governed by the standard error handling rules of promises. Methods that do not return promises may throw exceptions to indicate errors.

4.6 Session Description Model

4.6.1 RTCSdpType

The RTCSdpType enum describes the type of an RTCSessionDescriptionInit, RTCLocalSessionDescriptionInit, or RTCSessionDescription instance.

WebIDLenum RTCSdpType {
  "offer",
  "pranswer",
  "answer",
  "rollback"
};
Enumeration description
offer

An RTCSdpType of "offer" indicates that a description MUST be treated as an [SDP] offer.

pranswer

An RTCSdpType of "pranswer" indicates that a description MUST be treated as an [SDP] answer, but not a final answer. A description used as an SDP pranswer may be applied as a response to an SDP offer, or an update to a previously sent SDP pranswer.

answer

An RTCSdpType of "answer" indicates that a description MUST be treated as an [SDP] final answer, and the offer-answer exchange MUST be considered complete. A description used as an SDP answer may be applied as a response to an SDP offer or as an update to a previously sent SDP pranswer.

rollback

An RTCSdpType of "rollback" indicates that a description MUST be treated as canceling the current SDP negotiation and moving the SDP [SDP] offer back to what it was in the previous stable state. Note the local or remote SDP descriptions in the previous stable state could be null if there has not yet been a successful offer-answer negotiation. An "answer" or "pranswer" cannot be rolled back.

4.6.2 RTCSessionDescription Class

The RTCSessionDescription class is used by RTCPeerConnection to expose local and remote session descriptions.

WebIDL[Exposed=Window]
interface RTCSessionDescription {
  constructor(RTCSessionDescriptionInit descriptionInitDict);
  readonly attribute RTCSdpType type;
  readonly attribute DOMString sdp;
  [Default] object toJSON();
};
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 RTCSessionDescription.
sdp of type DOMString, readonly, defaulting to ""
The string representation of the SDP [SDP].
Methods
toJSON()
When called, run [WEBIDL]'s default toJSON steps.
WebIDLdictionary RTCSessionDescriptionInit {
  required RTCSdpType type;
  DOMString sdp = "";
};
Dictionary RTCSessionDescriptionInit Members
type of type RTCSdpType, required
The type of this description.
sdp of type DOMString
The string representation of the SDP [SDP]; if type is "rollback", this member is unused.
WebIDLdictionary RTCLocalSessionDescriptionInit {
  RTCSdpType type;
  DOMString sdp = "";
};
Dictionary RTCLocalSessionDescriptionInit Members
type of type RTCSdpType
The type of this description. If not present, then setLocalDescription will infer the type based on the RTCPeerConnection's signaling state.
sdp of type DOMString
The string representation of the SDP [SDP]; if type is "rollback", this member is unused.

4.7 Session Negotiation Model

Many changes to state of an RTCPeerConnection will require communication with the remote side via the signaling channel, in order to have the desired effect. The app can be kept informed as to when it needs to do signaling, by listening to the negotiationneeded event. This event is fired according to the state of the connection's negotiation-needed flag, represented by a [[NegotiationNeeded]] internal slot.

4.7.1 Setting Negotiation-Needed

This section is non-normative.

If an operation is performed on an RTCPeerConnection that requires signaling, the connection will be marked as needing negotiation. Examples of such operations include adding or stopping an RTCRtpTransceiver, or adding the first RTCDataChannel.

Internal changes within the implementation can also result in the connection being marked as needing negotiation.

Note that the exact procedures for updating the negotiation-needed flag are specified below.

4.7.2 Clearing Negotiation-Needed

This section is non-normative.

The negotiation-needed flag is cleared when an RTCSessionDescription of type "answer" is applied, and the supplied description matches the state of the RTCRtpTransceivers and RTCDataChannels that currently exist on the RTCPeerConnection. Specifically, this means that all non-stopped transceivers have an associated section in the local description with matching properties, and, if any data channels have been created, a data section exists in the local description.

Note that the exact procedures for updating the negotiation-needed flag are specified below.

4.7.3 Updating the Negotiation-Needed flag

The process below occurs where referenced elsewhere in this document. It also may occur as a result of internal changes within the implementation that affect negotiation. If such changes occur, the user agent MUST update the negotiation-needed flag.

To update the negotiation-needed flag for connection, run the following steps:

  1. If the length of connection.[[Operations]] is not 0, then set connection.[[UpdateNegotiationNeededFlagOnEmptyChain]] to true, and abort these steps.

  2. Queue a task to run the following steps:

    1. If connection.[[IsClosed]] is true, abort these steps.

    2. If the length of connection.[[Operations]] is not 0, then set connection.[[UpdateNegotiationNeededFlagOnEmptyChain]] to true, and abort these steps.

    3. If connection's signaling state is not "stable", abort these steps.

      Note

      The negotiation-needed flag will be updated once the state transitions to "stable", as part of the steps for setting an RTCSessionDescription.

    4. If the result of checking if negotiation is needed is false, clear the negotiation-needed flag by setting connection.[[NegotiationNeeded]] to false, and abort these steps.

    5. If connection.[[NegotiationNeeded]] is already true, abort these steps.

    6. Set connection.[[NegotiationNeeded]] to true.

    7. Fire an event named negotiationneeded at connection.

    Note

    The task queueing prevents negotiationneeded from firing prematurely, in the common situation where multiple modifications to connection are being made at once.

    Additionally, we avoid racing with negotiation methods by only firing negotiationneeded when the operations chain is empty.

To check if negotiation is needed for connection, perform the following checks:

  1. If any implementation-specific negotiation is required, as described at the start of this section, return true.

  2. If connection.[[LocalIceCredentialsToReplace]] is not empty, return true.

  3. Let description be connection.[[CurrentLocalDescription]].

  4. If connection has created any RTCDataChannels, and no m= section in description has been negotiated yet for data, return true.

  5. For each transceiver in connection's set of transceivers, perform the following checks:

    1. If transceiver.[[Stopping]] is true and transceiver.[[Stopped]] is false, return true.

    2. If transceiver isn't stopped and isn't yet associated with an m= section in description, return true.

    3. If transceiver isn't stopped and is associated with an m= section in description then perform the following checks:

      1. If transceiver.[[Direction]] is "sendrecv" or "sendonly", and the associated m= section in description either doesn't contain a single a=msid line, or the number of MSIDs from the a=msid lines in this m= section, or the MSID values themselves, differ from what is in transceiver.sender.[[AssociatedMediaStreamIds]], return true.

      2. If description is of type "offer", and the direction of the associated m= section in neither connection.[[CurrentLocalDescription]] nor connection.[[CurrentRemoteDescription]] matches transceiver.[[Direction]], return true. In this step, when the direction is compared with a direction found in [[CurrentRemoteDescription]], the description's direction must be reversed to represent the peer's point of view.

      3. If description is of type "answer", and the direction of the associated m= section in the description does not match transceiver.[[Direction]] intersected with the offered direction (as described in [JSEP] (section 5.3.1.)), return true.

    4. If transceiver is stopped and is associated with an m= section, but the associated m= section is not yet rejected in connection.[[CurrentLocalDescription]] or connection.[[CurrentRemoteDescription]], return true.

  6. If all the preceding checks were performed and true was not returned, nothing remains to be negotiated; return false.

4.8 Interfaces for Interactive Connectivity Establishment

4.8.1 RTCIceCandidate Interface

This interface describes an ICE candidate, described in [ICE] Section 2. Other than candidate, sdpMid, sdpMLineIndex, and usernameFragment, the remaining attributes are derived from parsing the candidate member in candidateInitDict, if it is well formed.

WebIDL[Exposed=Window]
interface RTCIceCandidate {
  constructor(optional RTCIceCandidateInit candidateInitDict = {});
  readonly attribute DOMString candidate;
  readonly attribute DOMString? sdpMid;
  readonly attribute unsigned short? sdpMLineIndex;
  readonly attribute DOMString? foundation;
  readonly attribute RTCIceComponent? component;
  readonly attribute unsigned long? priority;
  readonly attribute DOMString? address;
  readonly attribute RTCIceProtocol? protocol;
  readonly attribute unsigned short? port;
  readonly attribute RTCIceCandidateType? type;
  readonly attribute RTCIceTcpCandidateType? tcpType;
  readonly attribute DOMString? relatedAddress;
  readonly attribute unsigned short? relatedPort;
  readonly attribute DOMString? usernameFragment;
  RTCIceCandidateInit toJSON();
};
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 sdpMid and sdpMLineIndex members of candidateInitDict are null, 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 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.
Note

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

To maintain backward compatibility, any error on parsing the candidate attribute is ignored. In such case, the candidate attribute holds the raw 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 [ICE].

candidate of type DOMString, readonly
This carries the candidate-attribute as defined in section 15.1 of [ICE]. 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 RTCIceTransports.
component of type RTCIceComponent, readonly, nullable
The assigned network component of the candidate ("rtp" or "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 [[SelectedCandidatePair]].remote. By default, the user agent MUST leave the address attribute as null for any exposed remote candidate. Once a RTCPeerConnection instance learns on an address by the web application using 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.

Note

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.(This is a fingerprinting vector.)

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 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 [RTCWEB-IP-HANDLING].

protocol of type RTCIceProtocol, readonly, nullable
The protocol of the candidate ("udp"/"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 "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 [ICE].
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.
WebIDLdictionary RTCIceCandidateInit {
  DOMString candidate = "";
  DOMString? sdpMid = null;
  unsigned short? sdpMLineIndex = null;
  DOMString? usernameFragment = null;
};
Dictionary RTCIceCandidateInit Members
candidate of type DOMString, defaulting to ""
This carries the candidate-attribute as defined in section 15.1 of [ICE]. 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 [ICE].
4.8.1.1 candidate-attribute Grammar

The candidate-attribute grammar is used to parse the candidate member of candidateInitDict in the RTCIceCandidate() constructor.

The primary grammar for candidate-attribute is defined in section 15.1 of [ICE]. In addition, the browser MUST support the grammar extension for ICE TCP as defined in section 4.5 of [RFC6544].

The browser MAY support other grammar extensions for candidate-attribute as defined in other RFCs.

4.8.1.2 RTCIceProtocol Enum

The RTCIceProtocol represents the protocol of the ICE candidate.

WebIDLenum RTCIceProtocol {
  "udp",
  "tcp"
};
Enumeration description
udp A UDP candidate, as described in [ICE].
tcp A TCP candidate, as described in [RFC6544].
4.8.1.3 RTCIceTcpCandidateType Enum

The RTCIceTcpCandidateType represents the type of the ICE TCP candidate, as defined in [RFC6544].

WebIDLenum RTCIceTcpCandidateType {
  "active",
  "passive",
  "so"
};
Enumeration description
active An "active" TCP candidate is one for which the transport will attempt to open an outbound connection but will not receive incoming connection requests.
passive A "passive" TCP candidate is one for which the transport will receive incoming connection attempts but not attempt a connection.
so An "so" candidate is one for which the transport will attempt to open a connection simultaneously with its peer.
Note

The user agent will typically only gather active ICE TCP candidates.

4.8.1.4 RTCIceCandidateType Enum

The RTCIceCandidateType represents the type of the ICE candidate, as defined in [ICE] section 15.1.

WebIDLenum RTCIceCandidateType {
  "host",
  "srflx",
  "prflx",
  "relay"
};
Enumeration description
host A host candidate, as defined in Section 4.1.1.1 of [ICE].
srflx A server reflexive candidate, as defined in Section 4.1.1.2 of [ICE].
prflx A peer reflexive candidate, as defined in Section 4.1.1.2 of [ICE].
relay A relay candidate, as defined in Section 7.1.3.2.1 of [ICE].

4.8.2 RTCPeerConnectionIceEvent

The icecandidate event of the RTCPeerConnection uses the RTCPeerConnectionIceEvent interface.

When firing an RTCPeerConnectionIceEvent event that contains an RTCIceCandidate object, it MUST include values for both sdpMid and sdpMLineIndex. If the RTCIceCandidate is of type "srflx" or type "relay", the url property of the event MUST be set to the URL of the ICE server from which the candidate was obtained.

Note
The icecandidate event is used for three different types of indications:
WebIDL[Exposed=Window]
interface RTCPeerConnectionIceEvent : Event {
  constructor(DOMString type, optional RTCPeerConnectionIceEventInit eventInitDict = {});
  readonly attribute RTCIceCandidate? candidate;
  readonly attribute DOMString? url;
};
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.

Note

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.

WebIDLdictionary RTCPeerConnectionIceEventInit : EventInit {
  RTCIceCandidate? candidate;
  DOMString? url;
};
Dictionary RTCPeerConnectionIceEventInit Members
candidate of type RTCIceCandidate, nullable

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

4.8.3 RTCPeerConnectionIceErrorEvent

The icecandidateerror event of the RTCPeerConnection uses the RTCPeerConnectionIceErrorEvent interface.

WebIDL[Exposed=Window]
interface RTCPeerConnectionIceErrorEvent : Event {
  constructor(DOMString type, RTCPeerConnectionIceErrorEventInit eventInitDict);
  readonly attribute DOMString? address;
  readonly attribute unsigned short? port;
  readonly attribute DOMString url;
  readonly attribute unsigned short errorCode;
  readonly attribute USVString errorText;
};
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 "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.

WebIDLdictionary RTCPeerConnectionIceErrorEventInit : EventInit {
  DOMString? address;
  unsigned short? port;
  DOMString url;
  required unsigned short errorCode;
  USVString statusText;
};
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.

statusText of type USVString

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

4.9 Certificate Management

The certificates that RTCPeerConnection instances use to authenticate with peers use the RTCCertificate interface. These objects can be explicitly generated by applications using the generateCertificate method and can be provided in the RTCConfiguration when constructing a new RTCPeerConnection instance.

The explicit certificate management functions provided here are optional. If an application does not provide the certificates configuration option when constructing an RTCPeerConnection a new set of certificates MUST be generated by the user agent. That set MUST include an ECDSA certificate with a private key on the P-256 curve and a signature with a SHA-256 hash.

WebIDLpartial interface RTCPeerConnection {
  static Promise<RTCCertificate>
      generateCertificate(AlgorithmIdentifier keygenAlgorithm);
};

Methods

generateCertificate, static

The generateCertificate function causes the user agent to create an X.509 certificate [X509V3] and corresponding private key. A handle to information is provided in the form of the RTCCertificate interface. The returned RTCCertificate can be used to control the certificate that is offered in the DTLS sessions established by RTCPeerConnection.

The keygenAlgorithm argument is used to control how the private key associated with the certificate is generated. The keygenAlgorithm argument uses the WebCrypto [WebCryptoAPI] AlgorithmIdentifier type.

The following values MUST be supported by a user agent: { name: "RSASSA-PKCS1-v1_5", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" }, and { name: "ECDSA", namedCurve: "P-256" }.

Note

It is expected that a user agent will have a small or even fixed set of values that it will accept.

The certificate produced by this process also contains a signature. The validity of this signature is only relevant for compatibility reasons. Only the public key and the resulting certificate fingerprint are used by RTCPeerConnection, but it is more likely that a certificate will be accepted if the certificate is well formed. The browser selects the algorithm used to sign the certificate; a browser SHOULD select SHA-256 [FIPS-180-4] if a hash algorithm is needed.

The resulting certificate MUST NOT include information that can be linked to a user or user agent. Randomized values for distinguished name and serial number SHOULD be used.

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

  1. Let keygenAlgorithm be the first argument to generateCertificate.

  2. Let expires be a DOMTimeStamp value of 2592000000.

    Note

    This means the certificate will by default expire in 30 days from the time of the generateCertificate call.

  3. If keygenAlgorithm is an object, run the following steps:

    1. Let certificateExpiration be the result of converting the ECMAScript object represented by keygenAlgorithm to an RTCCertificateExpiration dictionary.

    2. If the conversion fails with an error, return a promise that is rejected with error.

    3. If certificateExpiration.expires is not undefined, set expires to certificateExpiration.expires.

    4. If expires is greater than 31536000000, set expires to 31536000000.

      Note

      This means the certificate cannot be valid for longer than 365 days from the time of the generateCertificate call.

      A user agent MAY further cap the value of expires.

  4. Let normalizedKeygenAlgorithm be the result of normalizing an algorithm with an operation name of generateKey and a supportedAlgorithms value specific to production of certificates for RTCPeerConnection.

  5. If the above normalization step fails with an error, return a promise that is rejected with error.

  6. If the normalizedKeygenAlgorithm parameter identifies an algorithm that the user agent cannot or will not use to generate a certificate for RTCPeerConnection, return a promise that is rejected with a DOMException of type NotSupportedError. In particular, normalizedKeygenAlgorithm MUST be an asymmetric algorithm that can be used to produce a signature used to authenticate DTLS connections.

  7. Let p be a new promise.

  8. Run the following steps in parallel:

    1. Perform the generate key operation specified by normalizedKeygenAlgorithm using keygenAlgorithm.

    2. Let generatedKeyingMaterial and generatedKeyCertificate be the private keying material and certificate generated by the above step.

    3. Let certificate be a new RTCCertificate object.

    4. Set certificate.[[Expires]] to the current time plus expires value.

    5. Set certificate.[[Origin]] to the current settings object's origin.

    6. Store the generatedKeyingMaterial in a secure module, and let handle be a reference identifier to it.

    7. Set certificate.[[KeyingMaterialHandle]] to handle.

    8. Set certificate.[[Certificate]] to generatedCertificate.

    9. Resolve p with certificate.

  9. Return p.

4.9.1 RTCCertificateExpiration Dictionary

RTCCertificateExpiration is used to set an expiration date on certificates generated by generateCertificate.

WebIDLdictionary RTCCertificateExpiration {
  [EnforceRange] DOMTimeStamp expires;
};
expires, of type DOMTimeStamp

An optional expires attribute MAY be added to the definition of the algorithm that is passed to generateCertificate. If this parameter is present it indicates the maximum time that the RTCCertificate is valid for relative to the current time.

4.9.2 RTCCertificate Interface

The RTCCertificate interface represents a certificate used to authenticate WebRTC communications. In addition to the visible properties, internal slots contain a handle to the generated private keying materal ([[KeyingMaterialHandle]]), a certificate ([[Certificate]]) that RTCPeerConnection uses to authenticate with a peer, and the origin ([[Origin]]) that created the object.

WebIDL[Exposed=Window, Serializable]
interface RTCCertificate {
  readonly attribute DOMTimeStamp expires;
  sequence<RTCDtlsFingerprint> getFingerprints();
};
Attributes
expires of type DOMTimeStamp, 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.

For the purposes of this API, the [[Certificate]] slot contains unstructured binary data. No mechanism is provided for applications to access the [[KeyingMaterialHandle]] internal slot or the keying material it references. Implementations MUST support applications storing and retrieving RTCCertificate objects from persistent storage, in a manner that also preserves the keying material referenced by [[KeyingMaterialHandle]]. Implementations SHOULD store the sensitive keying material in a secure module safe from same-process memory attacks. This allows the private key to be stored and used, but not easily read using a memory attack.

RTCCertificate objects are serializable objects [HTML]. Their serialization steps, given value and serialized, are:

  1. Set serialized.[[Expires]] to the value of value.expires attribute.
  2. Set serialized.[[Certificate]] to a copy of the unstructured binary data in value.[[Certificate]].
  3. Set serialized.[[Origin]] to a copy of the unstructured binary data in value.[[Origin]].
  4. Set serialized.[[KeyingMaterialHandle]] to a serialization of the handle in value.[[KeyingMaterialHandle]] (not the private keying material itself).

Their deserialization steps, given serialized and value, are:

  1. Initialize value.expires attribute to contain serialized.[[Expires]].
  2. Set value.[[Certificate]] to a copy of serialized.[[Certificate]].
  3. Set value.[[Origin]] to a copy of serialized.[[Origin]].
  4. Set value.[[KeyingMaterialHandle]] to the private keying material handle resulting from deserializing serialized.[[KeyingMaterialHandle]].
Note

Supporting structured cloning in this manner allows RTCCertificate instances to be persisted to stores. It also allows instances to be passed to other origins using APIs like postMessage() [html]. However, the object cannot be used by any other origin than the one that originally created it.

5. RTP Media API

The RTP media API lets a web application send and receive MediaStreamTracks over a peer-to-peer connection. Tracks, when added to an RTCPeerConnection, result in signaling; when this signaling is forwarded to a remote peer, it causes corresponding tracks to be created on the remote side.

Note

There is not an exact 1:1 correspondence between tracks sent by one RTCPeerConnection and received by the other. For one, IDs of tracks sent have no mapping to the IDs of tracks received. Also, replaceTrack changes the track sent by an RTCRtpSender without creating a new track on the receiver side; the corresponding RTCRtpReceiver will only have a single track, potentially representing multiple sources of media stitched together. Both addTransceiver and replaceTrack can be used to cause the same track to be sent multiple times, which will be observed on the receiver side as multiple receivers each with its own separate track. Thus it's more accurate to think of a 1:1 relationship between an RTCRtpSender on one side and an RTCRtpReceiver's track on the other side, matching senders and receivers using the RTCRtpTransceiver's mid if necessary.

When sending media, the sender may need to rescale or resample the media to meet various requirements including the envelope negotiated by SDP.

Following the rules in [JSEP] (section 3.6.), the video MAY be downscaled in order to fit the SDP constraints. The media MUST NOT be upscaled to create fake data that did not occur in the input source, the media MUST NOT be cropped except as needed to satisfy constraints on pixel counts, and the aspect ratio MUST NOT be changed.

Note

The WebRTC Working Group is seeking implementation feedback on the need and timeline for a more complex handling of this situation. Some possible designs have been discussed in GitHub issue 1283.

When video is rescaled, for example for certain combinations of width or height and scaleResolutionDownBy values, situations when the resulting width or height is not an integer may occur. In such situations the user agent MUST use the integer part of the result. What to transmit if the integer part of the scaled width or height is zero is implementation-specific.

The actual encoding and transmission of MediaStreamTracks is managed through objects called RTCRtpSenders. Similarly, the reception and decoding of MediaStreamTracks is managed through objects called RTCRtpReceivers. Each RTCRtpSender is associated with at most one track, and each track to be received is associated with exactly one RTCRtpReceiver.

The encoding and transmission of each MediaStreamTrack SHOULD be made such that its characteristics (width, height and frameRate for video tracks; volume, sampleSize, sampleRate and channelCount for audio tracks) are to a reasonable degree retained by the track created on the remote side. There are situations when this does not apply, there may for example be resource constraints at either endpoint or in the network or there may be RTCRtpSender settings applied that instruct the implementation to act differently.

An RTCPeerConnection object contains a set of RTCRtpTransceivers, representing the paired senders and receivers with some shared state. This set is initialized to the empty set when the RTCPeerConnection object is created. RTCRtpSenders and RTCRtpReceivers are always created at the same time as an RTCRtpTransceiver, which they will remain attached to for their lifetime. RTCRtpTransceivers are created implicitly when the application attaches a MediaStreamTrack to an RTCPeerConnection via the addTrack() method, or explicitly when the application uses the addTransceiver method. They are also created when a remote description is applied that includes a new media description. Additionally, when a remote description is applied that indicates the remote endpoint has media to send, the relevant MediaStreamTrack and RTCRtpReceiver are surfaced to the application via the track event.

In order for an RTCRtpTransceiver to send and/or receive media with another endpoint this must be negotiated with SDP such that both endpoints have an RTCRtpTransceiver object that is associated with the same media description.

When creating an offer, enough media descriptions will be generated to cover all transceivers on that end. When this offer is set as the local description, any disassociated transceivers get associated with media descriptions in the offer.

When an offer is set as the remote description, any media descriptions in it not yet associated with a transceiver get associated with a new or existing transceiver. In this case, only disassociated transceivers that were created via the addTrack() method may be associated. Disassociated transceivers created via the addTransceiver() method, however, won't get associated even if media descriptions are available in the remote offer. Instead, new transceivers will be created and associated if there aren't enough addTrack()-created transceivers. This sets addTrack()-created and addTransceiver()-created transceivers apart in a critical way that is not observable from inspecting their attributes.

When creating an answer, only media media descriptions that were present in the offer may be listed in the answer. As a consequence, any transceivers that were not associated when setting the remote offer remain disassociated after setting the local answer. This can be remedied by the answerer creating a follow-up offer, initiating another offer/answer exchange, or in the case of using addTrack()-created transceivers, making sure that enough media descriptions are offered in the initial exchange.

5.1 RTCPeerConnection Interface Extensions

The RTP media API extends the RTCPeerConnection interface as described below.

WebIDLpartial interface RTCPeerConnection {
  sequence<RTCRtpSender> getSenders();
  sequence<RTCRtpReceiver> getReceivers();
  sequence<RTCRtpTransceiver> getTransceivers();
  RTCRtpSender addTrack(MediaStreamTrack track, MediaStream... streams);
  void removeTrack(RTCRtpSender sender);
  RTCRtpTransceiver addTransceiver((MediaStreamTrack or DOMString) trackOrKind,
                                   optional RTCRtpTransceiverInit init = {});
  attribute EventHandler ontrack;
};

Attributes

ontrack of type EventHandler

The event type of this event handler is track.

Methods

getSenders

Returns a sequence of RTCRtpSender objects representing the RTP senders that belong to non-stopped RTCRtpTransceiver objects currently attached to this RTCPeerConnection object.

When the getSenders method is invoked, the user agent MUST return the result of executing the CollectSenders algorithm.

We define the CollectSenders algorithm as follows:

  1. Let transceivers be the result of executing the CollectTransceivers algorithm.
  2. Let senders be a new empty sequence.
  3. For each transceiver in transceivers,
    1. If transceiver.[[Stopped]] is false add transceiver.[[Sender]] to senders.
  4. Return senders.
getReceivers

Returns a sequence of RTCRtpReceiver objects representing the RTP receivers that belong to non-stopped RTCRtpTransceiver objects currently attached to this RTCPeerConnection object.

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

  1. Let transceivers be the result of executing the CollectTransceivers algorithm.
  2. Let receivers be a new empty sequence.
  3. For each transceiver in transceivers,
    1. If transceiver.[[Stopped]] is false add transceiver.[[Receiver]] to receivers.
  4. Return receivers.
getTransceivers

Returns a sequence of RTCRtpTransceiver objects representing the RTP transceivers that are currently attached to this RTCPeerConnection object.

The getTransceivers method MUST return the result of executing the CollectTransceivers algorithm.

We define the CollectTransceivers algorithm as follows:

  1. Let transceivers be a new sequence consisting of all RTCRtpTransceiver objects in this RTCPeerConnection object's set of transceivers, in insertion order.
  2. Return transceivers.
addTrack

Adds a new track to the RTCPeerConnection, and indicates that it is contained in the specified MediaStreams.

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

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

  2. Let track be the MediaStreamTrack object indicated by the method's first argument.

  3. Let kind be track.kind.

  4. Let streams be a list of MediaStream objects constructed from the method's remaining arguments, or an empty list if the method was called with a single argument.

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

  6. Let senders be the result of executing the CollectSenders algorithm. If an RTCRtpSender for track already exists in senders, throw an InvalidAccessError.

  7. The steps below describe how to determine if an existing sender can be reused. Doing so will cause future calls to createOffer and createAnswer to mark the corresponding media description as sendrecv or sendonly and add the MSID of the sender's streams, as defined in [JSEP] (section 5.2.2. and section 5.3.2.).

    If any RTCRtpSender object in senders matches all the following criteria, let sender be that object, or null otherwise:

  8. If sender is not null, run the following steps to use that sender:

    1. Set sender.[[SenderTrack]] to track.

    2. Set sender.[[AssociatedMediaStreamIds]] to an empty set.

    3. For each stream in streams, add stream.id to [[AssociatedMediaStreamIds]] if it's not already there.

    4. Let transceiver be the RTCRtpTransceiver associated with sender.

    5. If transceiver.[[Direction]] is "recvonly", set transceiver.[[Direction]] to "sendrecv".

    6. If transceiver.[[Direction]] is "inactive", set transceiver.[[Direction]] to "sendonly".

  9. If sender is null, run the following steps:

    1. Create an RTCRtpSender with track, kind and streams, and let sender be the result.

    2. Create an RTCRtpReceiver with kind, and let receiver be the result.

    3. Create an RTCRtpTransceiver with sender, receiver and an RTCRtpTransceiverDirection value of "sendrecv", and let transceiver be the result.

    4. Add transceiver to connection's set of transceivers.

  10. A track could have contents that are inaccessible to the application. This can be due to anything that would make a track CORS cross-origin. These tracks can be supplied to the addTrack() method, and have an RTCRtpSender created for them, but content MUST NOT be transmitted. Silence (audio), black frames (video) or equivalently absent content is sent in place of track content.

    Note that this property can change over time.

  11. Update the negotiation-needed flag for connection.

  12. Return sender.

removeTrack

Stops sending media from sender. The RTCRtpSender will still appear in getSenders. Doing so will cause future calls to createOffer to mark the media description for the corresponding transceiver as "recvonly" or "inactive", as defined in [JSEP] (section 5.2.2.).

When the other peer stops sending a track in this manner, the track is removed from any remote MediaStreams that were initially revealed in the track event, and if the MediaStreamTrack is not already muted, a mute event is fired at the track.

Note
The same effect as removeTrack() can be achieved by setting the RTCRtpTransceiver.direction attribute of the corresponding transceiver and invoking RTCRtpSender.replaceTrack(null) on the sender. One minor difference is that replaceTrack() is asynchronous and removeTrack() is synchronous.

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

  1. Let sender be the argument to removeTrack.

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

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

  4. If sender was not created by connection, throw an InvalidAccessError.

  5. Let senders be the result of executing the CollectSenders algorithm.

  6. If sender is not in senders (which indicates its transceiver was stopped or removed due to setting an RTCSessionDescription of type "rollback"), then abort these steps.

  7. If sender.[[SenderTrack]] is null, abort these steps.

  8. Set sender.[[SenderTrack]] to null.

  9. Let transceiver be the RTCRtpTransceiver object corresponding to sender.

  10. If transceiver.[[Direction]] is "sendrecv", set transceiver.[[Direction]] to "recvonly".

  11. If transceiver.[[Direction]] is "sendonly", set transceiver.[[Direction]] to "inactive".

  12. Update the negotiation-needed flag for connection.

addTransceiver

Create a new RTCRtpTransceiver and add it to the set of transceivers.

Adding a transceiver will cause future calls to createOffer to add a media description for the corresponding transceiver, as defined in [JSEP] (section 5.2.2.).

The initial value of mid is null. Setting a new RTCSessionDescription may change it to a non-null value, as defined in [JSEP] (section 5.5. and section 5.6.) and setting an RTCSessionDescription.

The sendEncodings argument can be used to specify the number of offered simulcast encodings, and optionally their RIDs and encoding parameters.

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

  1. Let init be the second argument.

  2. Let streams be init.streams.

  3. Let sendEncodings be init.sendEncodings.

  4. Let direction be init.direction.

  5. If the first argument is a string, let it be kind and run the following steps:

    1. If kind is not a legal MediaStreamTrack kind, throw a TypeError.

    2. Let track be null.

  6. If the first argument is a MediaStreamTrack, let it be track and let kind be track.kind.

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

  8. Validate sendEncodings by running the following steps:
    1. Verify that each rid value in sendEncodings conforms to the grammar specified in Section 10 of [MMUSIC-RID]. If one of the RIDs does not meet these requirements, throw a TypeError.

    2. If any RTCRtpEncodingParameters dictionary in sendEncodings contains a read-only parameter other than rid, throw an InvalidAccessError.

    3. Verify that each scaleResolutionDownBy value in sendEncodings is greater than or equal to 1.0. If one of the scaleResolutionDownBy values does not meet this requirement, throw a RangeError.

    4. Let maxN be the maximum number of total simultaneous encodings the user agent may support for this kind, at minimum 1.This should be an optimistic number since the codec to be used is not known yet.

    5. If sendEncodings contains any encoding whose scaleResolutionDownBy attribute is defined, set any undefined scaleResolutionDownBy of the other encodings to 1.0.

    6. If the number of RTCRtpEncodingParameters stored in sendEncodings exceeds maxN, then trim sendEncodings from the tail until its length is maxN.

    7. If the scaleResolutionDownBy attribues of sendEncodings are still undefined, initialize each encoding's scaleResolutionDownBy to 2^(length of sendEncodings - encoding index - 1). This results in smaller-to-larger resolutions where the last encoding has no scaling applied to it, e.g. 4:2:1 if the length is 3.
    8. If the number of RTCRtpEncodingParameters now stored in sendEncodings is 1, then remove any rid member from the lone entry.

      Note
      Providing a single, default RTCRtpEncodingParameters in sendEncodings allows the application to subsequently set encoding parameters using setParameters, even when simulcast isn't used.
  9. Create an RTCRtpSender with track, kind, streams and sendEncodings and let sender be the result.

    If sendEncodings is set, then subsequent calls to createOffer will be configured to send multiple RTP encodings as defined in [JSEP] (section 5.2.2. and section 5.2.1.). When setRemoteDescription is called with a corresponding remote description that is able to receive multiple RTP encodings as defined in [JSEP] (section 3.7.), the RTCRtpSender may send multiple RTP encodings and the parameters retrieved via the transceiver's sender.getParameters() will reflect the encodings negotiated.

  10. Create an RTCRtpReceiver with kind and let receiver be the result.

  11. Create an RTCRtpTransceiver with sender, receiver and direction, and let transceiver be the result.

  12. Add transceiver to connection's set of transceivers.

  13. Update the negotiation-needed flag for connection.

  14. Return transceiver.

WebIDLdictionary RTCRtpTransceiverInit {
  RTCRtpTransceiverDirection direction = "sendrecv";
  sequence<MediaStream> streams = [];
  sequence<RTCRtpEncodingParameters> sendEncodings = [];
};

Dictionary RTCRtpTransceiverInit Members

direction of type RTCRtpTransceiverDirection, defaulting to "sendrecv"
The direction of the RTCRtpTransceiver.
streams of type sequence<MediaStream>

When the remote PeerConnection's track event fires corresponding to the RTCRtpReceiver being added, these are the streams that will be put in the event.

sendEncodings of type sequence<RTCRtpEncodingParameters>

A sequence containing parameters for sending RTP encodings of media.

WebIDLenum RTCRtpTransceiverDirection {
  "sendrecv",
  "sendonly",
  "recvonly",
  "inactive",
  "stopped"
};
RTCRtpTransceiverDirection Enumeration description
sendrecv The RTCRtpTransceiver's RTCRtpSender sender will offer to send RTP, and will send RTP if the remote peer accepts and sender.getParameters().encodings[i].active is true for any value of i. The RTCRtpTransceiver's RTCRtpReceiver will offer to receive RTP, and will receive RTP if the remote peer accepts.
sendonly The RTCRtpTransceiver's RTCRtpSender sender will offer to send RTP, and will send RTP if the remote peer accepts and sender.getParameters().encodings[i].active is true for any value of i. The RTCRtpTransceiver's RTCRtpReceiver will not offer to receive RTP, and will not receive RTP.
recvonly The RTCRtpTransceiver's RTCRtpSender will not offer to send RTP, and will not send RTP. The RTCRtpTransceiver's RTCRtpReceiver will offer to receive RTP, and will receive RTP if the remote peer accepts.
inactive The RTCRtpTransceiver's RTCRtpSender will not offer to send RTP, and will not send RTP. The RTCRtpTransceiver's RTCRtpReceiver will not offer to receive RTP, and will not receive RTP.
stopped The RTCRtpTransceiver will neither send nor receive RTP. It will generate a zero port in the offer. In answers, its RTCRtpSender will not offer to send RTP, and its RTCRtpReceiver will not offer to receive RTP. This is a terminal state.

5.1.1 Processing Remote MediaStreamTracks

An application can reject incoming media descriptions by setting the transceiver's direction to either "inactive" to turn off both directions temporarily, or to "sendonly" to reject only the incoming side. To permanently reject an m-line in a manner that makes it available for reuse, the application would need to call RTCRtpTransceiver.stop() and subsequently initiate negotiation from its end.

To process remote tracks given an RTCRtpTransceiver transceiver, direction, msids, addList, removeList, and trackEventInits, run the following steps:

  1. Set the associated remote streams with transceiver.[[Receiver]], msids, addList, and removeList.

  2. If direction is "sendrecv" or "recvonly" and transceiver.[[FiredDirection]] is neither "sendrecv" nor "recvonly", or the previous step increased the length of addList, process the addition of a remote track with transceiver and trackEventInits.

  3. If direction is "sendonly" or "inactive", set transceiver.[[Receptive]] to false.

  4. If direction is "sendonly" or "inactive", and transceiver.[[FiredDirection]] is either "sendrecv" or "recvonly", process the removal of a remote track for the media description, with transceiver and muteTracks.

  5. Set transceiver.[[FiredDirection]] to direction.

To process the addition of a remote track given an RTCRtpTransceiver transceiver and trackEventInits, run the following steps:

  1. Let receiver be transceiver.[[Receiver]].

  2. Let track be receiver.[[ReceiverTrack]].

  3. Let streams be receiver.[[AssociatedRemoteMediaStreams]].

  4. Create a new RTCTrackEventInit dictionary with receiver, track, streams and transceiver as members and add it to trackEventInits.

To process the removal of a remote track with an RTCRtpTransceiver transceiver and muteTracks, run the following steps:

  1. Let receiver be transceiver.[[Receiver]].

  2. Let track be receiver.[[ReceiverTrack]].

  3. If track.muted is false, add track to muteTracks.

To set the associated remote streams given RTCRtpReceiver receiver, msids, addList, and removeList, run the following steps:

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

  2. For each MSID in msids, unless a MediaStream object has previously been created with that id for this connection, create a MediaStream object with that id.

  3. Let streams be a list of the MediaStream objects created for this connection with the ids corresponding to msids.

  4. Let track be receiver.[[ReceiverTrack]].

  5. For each stream in receiver.[[AssociatedRemoteMediaStreams]] that is not present in streams, add stream and track as a pair to removeList.

  6. For each stream in streams that is not present in receiver.[[AssociatedRemoteMediaStreams]], add stream and track as a pair to addList.

  7. Set receiver.[[AssociatedRemoteMediaStreams]] to streams.

5.2 RTCRtpSender Interface

The RTCRtpSender interface allows an application to control how a given MediaStreamTrack is encoded and transmitted to a remote peer. When setParameters is called on an RTCRtpSender object, the encoding is changed appropriately.

To create an RTCRtpSender with a MediaStreamTrack, track, a string, kind, a list of MediaStream objects, streams, and optionally a list of RTCRtpEncodingParameters objects, sendEncodings, run the following steps:

  1. Let sender be a new RTCRtpSender object.

  2. Let sender have a [[SenderTrack]] internal slot initialized to track.

  3. Let sender have a [[SenderTransport]] internal slot initialized to null.

  4. Let sender have a [[LastStableStateSenderTransport]] internal slot initialized to null.

  5. Let sender have a [[Dtmf]] internal slot initialized to null.

  6. If kind is "audio" then create an RTCDTMFSender dtmf and set the [[Dtmf]] internal slot to dtmf.

  7. Let sender have an [[AssociatedMediaStreamIds]] internal slot, representing a list of Ids of MediaStream objects that this sender is to be associated with. The [[AssociatedMediaStreamIds]] slot is used when sender is represented in SDP as described in [JSEP] (section 5.2.1.).

  8. Set sender.[[AssociatedMediaStreamIds]] to an empty set.

  9. For each stream in streams, add stream.id to [[AssociatedMediaStreamIds]] if it's not already there.

  10. Let sender have a [[SendEncodings]] internal slot, representing a list of RTCRtpEncodingParameters dictionaries.

  11. If sendEncodings is given as input to this algorithm, and is non-empty, set the [[SendEncodings]] slot to sendEncodings. Otherwise, set it to a list containing a single RTCRtpEncodingParameters with active set to true.

  12. Let sender have a [[SendCodecs]] internal slot, representing a list of RTCRtpCodecParameters dictionaries, and initialized to an empty list.

  13. Let sender have a [[LastReturnedParameters]] internal slot, which will be used to match getParameters and setParameters transactions.

  14. Return sender.

WebIDL[Exposed=Window]
interface RTCRtpSender {
  readonly attribute MediaStreamTrack? track;
  readonly attribute RTCDtlsTransport? transport;
  static RTCRtpCapabilities? getCapabilities(DOMString kind);
  Promise<void> setParameters(RTCRtpSendParameters parameters);
  RTCRtpSendParameters getParameters();
  Promise<void> replaceTrack(MediaStreamTrack? withTrack);
  void setStreams(MediaStream... streams);
  Promise<RTCStatsReport> getStats();
};

Attributes

track of type MediaStreamTrack, readonly, nullable

The track attribute is the track that is associated with this RTCRtpSender object. If track is ended, or if the track's output is disabled, i.e. the track is disabled and/or muted, the RTCRtpSender MUST send black frames (video) and MUST NOT send (audio). In the case of video, the RTCRtpSender SHOULD send one black frame per second. If track is null then the RTCRtpSender does not send. On getting, the attribute MUST return the value of the [[SenderTrack]] slot.

transport of type RTCDtlsTransport, readonly, nullable

The transport attribute is the transport over which media from track is sent in the form of RTP packets. Prior to construction of the RTCDtlsTransport object, the transport attribute will be null. When bundling is used, multiple RTCRtpSender objects will share one transport and will all send RTP and RTCP over the same transport.

On getting, the attribute MUST return the value of the [[SenderTransport]] slot.

Methods

getCapabilities, static

The getCapabilities() method returns the most optimistic view of the capabilities of the system for sending media of the given kind. It does not reserve any resources, ports, or other state but is meant to provide a way to discover the types of capabilities of the browser including which codecs may be supported. User agents MUST support kind values of "audio" and "video". If the system has no capabilities corresponding to the value of the kind argument, getCapabilities returns null.

These capabilities provide generally persistent cross-origin information on the device and thus increases the fingerprinting surface of the application. In privacy-sensitive contexts, browsers can consider mitigations such as reporting only a common subset of the capabilities.(This is a fingerprinting vector.)

setParameters

The setParameters method updates how track is encoded and transmitted to a remote peer.

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

  1. Let parameters be the method's first argument.
  2. Let sender be the RTCRtpSender object on which setParameters is invoked.
  3. Let transceiver be the RTCRtpTransceiver object associated with sender (i.e. sender is transceiver.[[Sender]]).
  4. If transceiver.[[Stopped]] is true, return a promise rejected with a newly created InvalidStateError.
  5. If sender.[[LastReturnedParameters]] is null, return a promise rejected with a newly created InvalidStateError.
  6. Validate parameters by running the following steps:
    1. Let encodings be parameters.encodings.
    2. Let codecs be parameters.codecs.
    3. Let N be the number of RTCRtpEncodingParameters stored in sender.[[SendEncodings]].
    4. If any of the following conditions are met, return a promise rejected with a newly created InvalidModificationError:
      1. encodings.length is different from N.
      2. encodings has been re-ordered.
      3. Any parameter in parameters is marked as a Read-only parameter (such as RID) and has a value that is different from the corresponding parameter value in sender.[[LastReturnedParameters]]. Note that this also applies to transactionId.
    5. Verify that each scaleResolutionDownBy value in encodings is greater than or equal to 1.0. If one of the scaleResolutionDownBy values does not meet this requirement, return a promise rejected with a newly created RangeError.

  7. Let p be a new promise.
  8. In parallel, configure the media stack to use parameters to transmit sender.[[SenderTrack]].
    1. If the media stack is successfully configured with parameters, queue a task to run the following steps:
      1. Set sender.[[LastReturnedParameters]] to null.
      2. Set sender.[[SendEncodings]] to parameters.encodings.
      3. Resolve p with undefined.
    2. If any error occurred while configuring the media stack, queue a task to run the following steps:
      1. If an error occurred due to hardware resources not being available, reject p with a newly created RTCError whose errorDetail is set to "hardware-encoder-not-available" and abort these steps.
      2. If an error occurred due to a hardware encoder not supporting parameters, reject p with a newly created RTCError whose errorDetail is set to "hardware-encoder-error" and abort these steps.
      3. For all other errors, reject p with a newly created OperationError.
  9. Return p.

setParameters does not cause SDP renegotiation and can only be used to change what the media stack is sending or receiving within the envelope negotiated by Offer/Answer. The attributes in the RTCRtpSendParameters dictionary are designed to not enable this, so attributes like cname that cannot be changed are read-only. Other things, like bitrate, are controlled using limits such as maxBitrate, where the user agent needs to ensure it does not exceed the maximum bitrate specified by maxBitrate, while at the same time making sure it satisfies constraints on bitrate specified in other places such as the SDP.

getParameters

The getParameters() method returns the RTCRtpSender object's current parameters for how track is encoded and transmitted to a remote RTCRtpReceiver.

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

  1. Let sender be the RTCRtpSender object on which the getter was invoked.

  2. If sender.[[LastReturnedParameters]] is not null, return sender.[[LastReturnedParameters]], and abort these steps.

  3. Let result be a new RTCRtpSendParameters dictionary constructed as follows:

  4. Set sender.[[LastReturnedParameters]] to result.

  5. Queue a task that sets sender.[[LastReturnedParameters]] to null.

  6. Return result.

getParameters may be used with setParameters to change the parameters in the following way:

async function updateParameters() {
  try {
    const params = sender.getParameters();
    // ... make changes to parameters
    params.encodings[0].active = false;
    await sender.setParameters(params);
  } catch (err) {
    console.error(err);
  }
}

After a completed call to setParameters, subsequent calls to getParameters will return the modified set of parameters.

replaceTrack

Attempts to replace the RTCRtpSender's current track with another track provided (or with a null track), without renegotiation.

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

  1. Let sender be the RTCRtpSender object on which replaceTrack is invoked.

  2. Let transceiver be the RTCRtpTransceiver object associated with sender.

  3. Let connection be the RTCPeerConnection object associated with sender.

  4. Let withTrack be the argument to this method.

  5. If withTrack is non-null and withTrack.kind differs from the transceiver kind of transceiver, return a promise rejected with a newly created TypeError.

  6. Return the result of chaining the following steps to connection's operations chain:

    1. If transceiver.[[Stopped]] is true, return a promise rejected with a newly created InvalidStateError.

    2. Let p be a new promise.

    3. Let sending be true if transceiver.[[CurrentDirection]] is "sendrecv" or "sendonly", and false otherwise.

    4. Run the following steps in parallel:

      1. If sending is true, and withTrack is null, have the sender stop sending.

      2. If sending is true, and withTrack is not null, determine if withTrack can be sent immediately by the sender without violating the sender's already-negotiated envelope, and if it cannot, then reject p with a newly created InvalidModificationError, and abort these steps.

      3. If sending is true, and withTrack is not null, have the sender switch seamlessly to transmitting withTrack instead of the sender's existing track.

      4. Queue a task that runs the following steps:

        1. If connection.[[IsClosed]] is true, abort these steps.

        2. Set sender.[[SenderTrack]] to withTrack.

        3. Resolve p with undefined.

    5. Return p.

Note

Changing dimensions and/or frame rates might not require negotiation. Cases that may require negotiation include:

  1. Changing a resolution to a value outside of the negotiated imageattr bounds, as described in [RFC6236].
  2. Changing a frame rate to a value that causes the block rate for the codec to be exceeded.
  3. A video track differing in raw vs. pre-encoded format.
  4. An audio track having a different number of channels.
  5. Sources that also encode (typically hardware encoders) might be unable to produce the negotiated codec; similarly, software sources might not implement the codec that was negotiated for an encoding source.
setStreams

Sets the MediaStreams to be associated with this sender's track.

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

  1. Let sender be the RTCRtpSender object on which this method was invoked.

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

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

  4. Let streams be a list of MediaStream objects constructed from the method's arguments, or an empty list if the method was called without arguments.

  5. Set sender.[[AssociatedMediaStreamIds]] to an empty set.

  6. For each stream in streams, add stream.id to [[AssociatedMediaStreamIds]] if it's not already there.

  7. Update the negotiation-needed flag for connection.

getStats

Gathers stats for this sender only and reports the result asynchronously.

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

  1. Let selector be the RTCRtpSender object on which the method was invoked.

  2. Let p be a new promise, and run the following steps in parallel:

    1. Gather the stats indicated by selector according to the stats selection algorithm.

    2. Resolve p with the resulting RTCStatsReport object, containing the gathered stats.

  3. Return p.

5.2.1 RTCRtpParameters Dictionary

WebIDLdictionary RTCRtpParameters {
  required sequence<RTCRtpHeaderExtensionParameters> headerExtensions;
  required RTCRtcpParameters rtcp;
  required sequence<RTCRtpCodecParameters> codecs;
};
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 mimeType attribute indicating retransmission via audio/rtx or video/rtx, and an sdpFmtpLine attribute (providing the "apt" and "rtx-time" parameters). Read-only parameter.

5.2.2 RTCRtpSendParameters Dictionary

WebIDLdictionary RTCRtpSendParameters : RTCRtpParameters {
  required DOMString transactionId;
  required sequence<RTCRtpEncodingParameters> encodings;
};
Dictionary RTCRtpSendParameters Members
transactionId of type DOMString, required

A unique identifier for the last set of parameters applied. Ensures that setParameters can only be called based on a previous 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.

5.2.3 RTCRtpReceiveParameters Dictionary

WebIDLdictionary RTCRtpReceiveParameters : RTCRtpParameters {
};

5.2.4 RTCRtpCodingParameters Dictionary

WebIDLdictionary RTCRtpCodingParameters {
  DOMString rid;
};
Dictionary RTCRtpCodingParameters Members
rid of type DOMString

If set, this RTP encoding will be sent with the RID header extension as defined by [JSEP] (section 5.2.1.). The RID is not modifiable via setParameters. It can only be set or modified in addTransceiver on the sending side. Read-only parameter.

5.2.5 RTCRtpDecodingParameters Dictionary

WebIDLdictionary RTCRtpDecodingParameters : RTCRtpCodingParameters {};

5.2.6 RTCRtpEncodingParameters Dictionary

WebIDLdictionary RTCRtpEncodingParameters : RTCRtpCodingParameters {
  boolean active = true;
  unsigned long maxBitrate;
  double scaleResolutionDownBy;
};
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.

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.

Note

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.

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 by a factor of two to the power of the layer's number, in 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. scaleResolutionDownBy will be 1.0).

5.2.7 RTCRtcpParameters Dictionary

WebIDLdictionary RTCRtcpParameters {
  DOMString cname;
  boolean reducedSize;
};
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.

5.2.8 RTCRtpHeaderExtensionParameters Dictionary

WebIDLdictionary RTCRtpHeaderExtensionParameters {
  required DOMString uri;
  required unsigned short id;
  boolean encrypted = false;
};
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.

Note

The RTCRtpHeaderExtensionParameters dictionary enables an application to determine whether a header extension is configured for use within an RTCRtpSender or RTCRtpReceiver. For an RTCRtpTransceiver transceiver, an application can determine the "direction" parameter (defined in Section 5 of [RFC5285]) of a header extension as follows without having to parse SDP:

  1. sendonly: The header extension is only included in transceiver.sender.getParameters().headerExtensions.
  2. recvonly: The header extension is only included in transceiver.receiver.getParameters().headerExtensions.
  3. sendrecv: The header extension is included in both transceiver.sender.getParameters().headerExtensions and transceiver.receiver.getParameters().headerExtensions.
  4. inactive: The header extension is included in neither transceiver.sender.getParameters().headerExtensions nor transceiver.receiver.getParameters().headerExtensions.

5.2.9 RTCRtpCodecParameters Dictionary

WebIDLdictionary RTCRtpCodecParameters {
  required octet payloadType;
  required DOMString mimeType;
  required unsigned long clockRate;
  unsigned short channels;
  DOMString sdpFmtpLine;
};
Dictionary RTCRtpCodecParameters Members
payloadType of type octet, required

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

mimeType of type DOMString, required

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

clockRate of type unsigned long, required

The codec clock rate expressed in Hertz. Read-only parameter.

channels of type unsigned short

When present, indicates the number of channels (mono=1, stereo=2). Read-only parameter.

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 [JSEP] (section 5.8.). For an RTCRtpSender, these parameters come from the remote description, and for an RTCRtpReceiver, they come from the local description. Read-only parameter.

5.2.10 RTCRtpCapabilities Dictionary

WebIDLdictionary RTCRtpCapabilities {
  required sequence<RTCRtpCodecCapability> codecs;
  required sequence<RTCRtpHeaderExtensionCapability> headerExtensions;
};
Dictionary RTCRtpCapabilities Members
codecs of type sequence<RTCRtpCodecCapability>, required

Supported media codecs as well as entries for RTX, RED and FEC mechanisms. There will only be a single entry in codecs for retransmission via RTX, with sdpFmtpLine not present.

headerExtensions of type sequence<RTCRtpHeaderExtensionCapability>, required

Supported RTP header extensions.

5.2.11 RTCRtpCodecCapability Dictionary

WebIDLdictionary RTCRtpCodecCapability {
  required DOMString mimeType;
  required unsigned long clockRate;
  unsigned short channels;
  DOMString sdpFmtpLine;
};
Dictionary RTCRtpCodecCapability Members

The RTCRtpCodecCapability dictionary provides information about codec capabilities. Only capability combinations that would utilize distinct payload types in a generated SDP offer are 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.
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.

5.2.12 RTCRtpHeaderExtensionCapability Dictionary

WebIDLdictionary RTCRtpHeaderExtensionCapability {
  DOMString uri;
};
Dictionary RTCRtpHeaderExtensionCapability Members
uri of type DOMString

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

5.3 RTCRtpReceiver Interface

The RTCRtpReceiver interface allows an application to inspect the receipt of a MediaStreamTrack.

To create an RTCRtpReceiver with a string, kind, run the following steps:

  1. Let receiver be a new RTCRtpReceiver object.

  2. Let track be a new MediaStreamTrack object [GETUSERMEDIA]. The source of track is a remote source provided by receiver. Note that the track.id is generated by the user agent and does not map to any track IDs on the remote side.

  3. Initialize track.kind to kind.

  4. Initialize track.label to the result of concatenating the string "remote " with kind.

  5. Initialize track.readyState to live.

  6. Initialize track.muted to true. See the MediaStreamTrack section about how the muted attribute reflects if a MediaStreamTrack is receiving media data or not.

  7. Let receiver have a [[ReceiverTrack]] internal slot initialized to track.

  8. Let receiver have a [[ReceiverTransport]] internal slot initialized to null.

  9. Let receiver have a [[LastStableStateReceiverTransport]] internal slot initialized to null.

  10. Let receiver have an [[AssociatedRemoteMediaStreams]] internal slot, representing a list of MediaStream objects that the MediaStreamTrack object of this receiver is associated with, and initialized to an empty list.

  11. Let receiver have a [[LastStableStateAssociatedRemoteMediaStreams]] internal slot and initialize it to an empty list.

  12. Let receiver have a [[ReceiveCodecs]] internal slot, representing a list of RTCRtpCodecParameters dictionaries, and initialized to an empty list.

  13. Let receiver have a [[LastStableStateReceiveCodecs]] internal slot and initialize it to an empty list.

  14. Return receiver.

WebIDL[Exposed=Window]
interface RTCRtpReceiver {
  readonly attribute MediaStreamTrack track;
  readonly attribute RTCDtlsTransport? transport;
  static RTCRtpCapabilities? getCapabilities(DOMString kind);
  RTCRtpReceiveParameters getParameters();
  sequence<RTCRtpContributingSource> getContributingSources();
  sequence<RTCRtpSynchronizationSource> getSynchronizationSources();
  Promise<RTCStatsReport> getStats();
};

Attributes

track of type MediaStreamTrack, readonly

The track attribute is the track that is associated with this RTCRtpReceiver object receiver.

Note that track.stop() is final, although clones are not affected. Since receiver.track.stop() does not implicitly stop receiver, Receiver Reports continue to be sent. On getting, the attribute MUST return the value of the [[ReceiverTrack]] slot.

transport of type RTCDtlsTransport, readonly, nullable

The transport attribute is the transport over which media for the receiver's track is received in the form of RTP packets. Prior to construction of the RTCDtlsTransport object, the transport attribute will be null. When bundling is used, multiple RTCRtpReceiver objects will share one transport and will all receive RTP and RTCP over the same transport.

On getting, the attribute MUST return the value of the [[ReceiverTransport]] slot.

Methods

getCapabilities, static

The getCapabilities() method returns the most optimistic view of the capabilities of the system for receiving media of the given kind. It does not reserve any resources, ports, or other state but is meant to provide a way to discover the types of capabilities of the browser including which codecs may be supported. User agents MUST support kind values of "audio" and "video". If the system has no capabilities corresponding to the value of the kind argument, getCapabilities returns null.

These capabilities provide generally persistent cross-origin information on the device and thus increases the fingerprinting surface of the application. In privacy-sensitive contexts, browsers can consider mitigations such as reporting only a common subset of the capabilities.(This is a fingerprinting vector.)

getParameters

The getParameters() method returns the RTCRtpReceiver object's current parameters for how track is decoded.

When getParameters is called, the RTCRtpReceiveParameters dictionary is constructed as follows:

  • The headerExtensions sequence is populated based on the header extensions that the receiver is currently prepared to receive.
  • codecs is set to the value of the [[ReceiveCodecs]] internal slot.

    Note
    Both the local and remote description may affect this list of codecs. For example, if three codecs are offered, the receiver will be prepared to receive each of them and will return them all from getParameters. But if the remote endpoint only answers with two, the absent codec will no longer be returned by getParameters as the receiver no longer needs to be prepared to receive it.
  • rtcp.reducedSize is set to true if the receiver is currently prepared to receive reduced-size RTCP packets, and false otherwise. rtcp.cname is left out.
getContributingSources

Returns an RTCRtpContributingSource for each unique CSRC identifier received by this RTCRtpReceiver in the last 10 seconds, in descending timestamp order.

getSynchronizationSources

Returns an RTCRtpSynchronizationSource for each unique SSRC identifier received by this RTCRtpReceiver in the last 10 seconds, in descending timestamp order.

getStats

Gathers stats for this receiver only and reports the result asynchronously.

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

  1. Let selector be the RTCRtpReceiver object on which the method was invoked.

  2. Let p be a new promise, and run the following steps in parallel:

    1. Gather the stats indicated by selector according to the stats selection algorithm.

    2. Resolve p with the resulting RTCStatsReport object, containing the gathered stats.

  3. Return p.

The RTCRtpContributingSource and RTCRtpSynchronizationSource dictionaries contain information about a given contributing source (CSRC) or synchronization source (SSRC) respectively. When an audio or video frame from one or more RTP packets is delivered to the RTCRtpReceiver's MediaStreamTrack, the user agent MUST queue a task to update the relevant information for the RTCRtpContributingSource and RTCRtpSynchronizationSource dictionaries based on the content of those packets. The information relevant to the RTCRtpSynchronizationSource dictionary corresponding to the SSRC identifier, is updated each time, and if an RTP packet contains CSRC identifiers, then the information relevant to the RTCRtpContributingSource dictionaries corresponding to those CSRC identifiers is also updated. The user agent MUST process RTP packets in order of ascending RTP timestamps. The user agent MUST keep information from RTP packets delivered to the RTCRtpReceiver's MediaStreamTrack in the previous 10 seconds.

Note
Even if the MediaStreamTrack is not attached to any sink for playout, getSynchronizationSources and getContributingSources returns up-to-date information as long as the track is not ended; sinks are not a prerequisite for decoding RTP packets.
Note
As stated in the conformance section, requirements phrased as algorithms may be implemented in any manner so long as the end result is equivalent. So, an implementation does not need to literally queue a task for every frame, as long as the end result is that within a single event loop task execution, all returned RTCRtpSynchronizationSource and RTCRtpContributingSource dictionaries for a particular RTCRtpReceiver contain information from a single point in the RTP stream.
WebIDLdictionary RTCRtpContributingSource {
  required DOMHighResTimeStamp timestamp;
  required unsigned long source;
  double audioLevel;
  required unsigned long rtpTimestamp;
};

Dictionary RTCRtpContributingSource Members

timestamp of type DOMHighResTimeStamp, required

The timestamp indicating the most recent time a frame from an RTP packet, originating from this source, was delivered to the RTCRtpReceiver's MediaStreamTrack. The timestamp is defined as Performance.timeOrigin + Performance.now() at that time.

source of type unsigned long, required

The CSRC or SSRC identifier of the contributing or synchronization source.

audioLevel of type double

Only present for audio receivers. This is a value between 0..1 (linear), where 1.0 represents 0 dBov, 0 represents silence, and 0.5 represents approximately 6 dBSPL change in the sound pressure level from 0 dBov.

For CSRCs, this MUST be converted from the level value defined in [RFC6465] if the RFC 6465 header extension is present, otherwise this member MUST be absent.

For SSRCs, this MUST be converted from the level value defined in [RFC6464]. If the RFC 6464 header extension is not present in the received packets (such as if the other endpoint is not a user agent or is a legacy endpoint), this value SHOULD be absent.

Both RFCs define the level as an integral value from 0 to 127 representing the audio level in negative decibels relative to the loudest signal that the system could possibly encode. Thus, 0 represents the loudest signal the system could possibly encode, and 127 represents silence.

To convert these values to the linear 0..1 range, a value of 127 is converted to 0, and all other values are converted using the equation: 10^(-rfc_level/20).

rtpTimestamp of type unsigned long, required

The last RTP timestamp, as defined in [RFC3550] Section 5.1, of the media played out at timestamp.

WebIDLdictionary RTCRtpSynchronizationSource : RTCRtpContributingSource {
  boolean voiceActivityFlag;
};

Dictionary RTCRtpSynchronizationSource Members

voiceActivityFlag of type boolean

Only present for audio receivers. Whether the last RTP packet, delivered from this source, contains voice activity (true) or not (false). If the RFC 6464 extension header was not present, or if the peer has signaled that it is not using the V bit by setting the "vad" extension attribute to "off", as described in [RFC6464], Section 4, voiceActivityFlag will be absent.

(Feature at Risk) Issue 1

voiceActivityFlag is marked as a feature at risk, since there is no clear commitment from implementers.

5.4 RTCRtpTransceiver Interface

The RTCRtpTransceiver interface represents a combination of an RTCRtpSender and an RTCRtpReceiver that share a common media stream "identification-tag". As defined in [JSEP] (section 3.4.1.), an RTCRtpTransceiver is said to be associated with a media description if its "mid" property is non-null and matches a media stream "identification-tag" in the media description; otherwise it is said to be disassociated with that media description.

Note

A RTCRtpTransceiver may become associated with a new pending description in JSEP while still being disassociated with the current description. This may happen in check if negotiation is needed.

The transceiver kind of an RTCRtpTransceiver is defined by the kind of the associated RTCRtpReceiver's MediaStreamTrack object.

To create an RTCRtpTransceiver with an RTCRtpReceiver object, receiver, RTCRtpSender object, sender, and an RTCRtpTransceiverDirection value, direction, run the following steps:

  1. Let transceiver be a new RTCRtpTransceiver object.

  2. Let transceiver have a [[Sender]] internal slot, initialized to sender.

  3. Let transceiver have a [[Receiver]] internal slot, initialized to receiver.

  4. Let transceiver have a [[Stopping]] internal slot, initialized to false.

  5. Let transceiver have a [[Stopped]] internal slot, initialized to false.

  6. Let transceiver have a [[Direction]] internal slot, initialized to direction.

  7. Let transceiver have a [[Receptive]] internal slot, initialized to false.

  8. Let transceiver have a [[CurrentDirection]] internal slot, initialized to null.

  9. Let transceiver have a [[FiredDirection]] internal slot, initialized to null.

  10. Let transceiver have a [[PreferredCodecs]] internal slot, initialized to an empty list.

  11. Let transceiver have a [[JsepMid]] internal slot, initialized to null. This is the "RtpTransceiver mid property" defined in [JSEP] (section 5.2.1. and section 5.3.1.), and is only modified there.

  12. Let transceiver have a [[Mid]] internal slot, initialized to null.

  13. Return transceiver.

Note
Creating a transceiver does not create the underlying RTCDtlsTransport and RTCIceTransport objects. This will only occur as part of the process of setting an RTCSessionDescription.
WebIDL[Exposed=Window]
interface RTCRtpTransceiver {
  readonly attribute DOMString? mid;
  [SameObject] readonly attribute RTCRtpSender sender;
  [SameObject] readonly attribute RTCRtpReceiver receiver;
  attribute RTCRtpTransceiverDirection direction;
  readonly attribute RTCRtpTransceiverDirection? currentDirection;
  void stop();
  void setCodecPreferences(sequence<RTCRtpCodecCapability> codecs);
};

Attributes

mid of type DOMString, readonly, nullable

The mid attribute is the media stream "identification-tag" negotiated and present in the local and remote descriptions. On getting, the attribute MUST return the value of the [[Mid]] slot.

sender of type RTCRtpSender, readonly

The sender attribute exposes the RTCRtpSender corresponding to the RTP media that may be sent with mid = [[Mid]]. On getting, the attribute MUST return the value of the [[Sender]] slot.

receiver of type RTCRtpReceiver, readonly

The receiver attribute is the RTCRtpReceiver corresponding to the RTP media that may be received with mid = [[Mid]]. On getting the attribute MUST return the value of the [[Receiver]] slot.

direction of type RTCRtpTransceiverDirection

As defined in [JSEP] (section 4.2.4.), the direction attribute indicates the preferred direction of this transceiver, which will be used in calls to createOffer and createAnswer. An update of directionality does not take effect immediately. Instead, future calls to createOffer and createAnswer mark the corresponding media description as sendrecv, sendonly, recvonly or inactive as defined in [JSEP] (section 5.2.2. and section 5.3.2.)

On getting, the user agent MUST run the following steps:

  1. Let transceiver be the RTCRtpTransceiver object on which the getter is invoked.

  2. If transceiver.[[Stopping]] is true, return "stopped".

  3. Otherwise, return the value of the [[Direction]] slot.

On setting, the user agent MUST run the following steps:

  1. Let transceiver be the RTCRtpTransceiver object on which the setter is invoked.

  2. Let connection be the RTCPeerConnection object associated with transceiver.

  3. If transceiver.[[Stopping]] is true, throw an InvalidStateError.

  4. Let newDirection be the argument to the setter.

  5. If newDirection is equal to transceiver.[[Direction]], abort these steps.

  6. If newDirection is equal to "stopped", throw a TypeError.

  7. Set transceiver.[[Direction]] to newDirection.

  8. Update the negotiation-needed flag for connection.

currentDirection of type RTCRtpTransceiverDirection, readonly, nullable

As defined in [JSEP] (section 4.2.5.), the currentDirection attribute indicates the current direction negotiated for this transceiver. The value of currentDirection is independent of the value of RTCRtpEncodingParameters.active since one cannot be deduced from the other. If this transceiver has never been represented in an offer/answer exchange, the value is null. If the transceiver is stopped, the value is "stopped".

On getting, the user agent MUST run the following steps:

  1. Let transceiver be the RTCRtpTransceiver object on which the getter is invoked.

  2. If transceiver.[[Stopped]] is true, return "stopped".

  3. Otherwise, return the value of the [[CurrentDirection]] slot.

Methods

stop

Irreversibly marks the transceiver as stopping, unless it is already stopped. This will immediately cause the transceiver's sender to no longer send, and its receiver to no longer receive. Calling stop() also updates the negotiation-needed flag for the RTCRtpTransceiver's associated RTCPeerConnection.

A stopping transceiver will cause future calls to createOffer to generate a zero port in the media description for the corresponding transceiver, as defined in [JSEP] (section 4.2.1.) (The user agent MUST treat a stopping transceiver as stopped for the purposes of JSEP only in this case). However, to avoid problems with [BUNDLE], a transceiver that is stopping, but not stopped, will not affect createAnswer.

A stopped transceiver will cause future calls to createOffer or createAnswer to generate a zero port in the media description for the corresponding transceiver, as defined in [JSEP] (section 4.2.1.).

The transceiver will remain in the stopping state, unless it becomes stopped by setRemoteDescription processing a rejected m-line in a remote offer or answer.

Note

A transceiver that is stopping but not stopped will always need negotiation. In practice, this means that calling stop() on a transceiver will cause the transceiver to become stopped eventually, provided negotiation is allowed to complete on both ends.

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

  1. Let transceiver be the RTCRtpTransceiver object on which the method is invoked.

  2. Let connection be the RTCPeerConnection object associated with transceiver.

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

  4. If transceiver.[[Stopping]] is true, abort these steps.

  5. Stop sending and receiving with transceiver.

  6. Update the negotiation-needed flag for connection.

The stop sending and receiving algorithm given a transceiver and, optionally, a disappear boolean defaulting to false, is as follows:

  1. Let sender be transceiver.[[Sender]].

  2. Let receiver be transceiver.[[Receiver]].

  3. Stop sending media with sender.

  4. Send an RTCP BYE for each RTP stream that was being sent by sender, as specified in [RFC3550].

  5. Stop receiving media with receiver.

  6. If disappear is false, execute the steps for receiver.[[ReceiverTrack]] to be ended. This fires an event.

  7. Set transceiver.[[Direction]] to "inactive".

  8. Set transceiver.[[Stopping]] to true.

The stop the RTCRtpTransceiver algorithm given a transceiver and, optionally, a disappear boolean defaulting to false, is as follows:

  1. If transceiver.[[Stopping]] is false, stop sending and receiving with transceiver and disappear.

  2. Set transceiver.[[Stopped]] to true.

  3. Set transceiver.[[Receptive]] to false.

  4. Set transceiver.[[CurrentDirection]] to null.

setCodecPreferences

The setCodecPreferences method overrides the default codec preferences used by the user agent. When generating a session description using either createOffer or createAnswer, the user agent MUST use the indicated codecs, in the order specified in the codecs argument, for the media section corresponding to this RTCRtpTransceiver.

This method allows applications to disable the negotiation of specific codecs (including RTX/RED/FEC). It also allows an application to cause a remote peer to prefer the codec that appears first in the list for sending.

Codec preferences remain in effect for all calls to createOffer and createAnswer that include this RTCRtpTransceiver until this method is called again. Setting codecs to an empty sequence resets codec preferences to any default value.

Note

Codecs have their payload types listed under each m= section in the SDP, defining the mapping between payload types and codecs. These payload types are referenced by the m=video or m=audio lines in the order of preference, and codecs that are not negotiated do not apear in this list as defined in section 5.2.1 of [JSEP]. A previously negotiated codec that is subsequently removed disappears from the m=video or m=audio line, and while its codec payload type is not to be reused in future offers or answers, its payload type may also be removed from the mapping of payload types in the SDP.

The codecs sequence passed into setCodecPreferences can only contain codecs that are returned by RTCRtpSender.getCapabilities(kind) or RTCRtpReceiver.getCapabilities(kind), where kind is the kind of the RTCRtpTransceiver on which the method is called. Additionally, the RTCRtpCodecCapability dictionary members cannot be modified. If codecs does not fulfill these requirements, the user agent MUST throw an InvalidModificationError.

Note

Due to a recommendation in [SDP], calls to createAnswer SHOULD use only the common subset of the codec preferences and the codecs that appear in the offer. For example, if codec preferences are "C, B, A", but only codecs "A, B" were offered, the answer should only contain codecs "B, A". However, [JSEP] (section 5.3.1.) allows adding codecs that were not in the offer, so implementations can behave differently.

When setCodecPreferences() in invoked, the user agent MUST run the following steps:

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

  2. Let codecs be the first argument.

  3. If codecs is an empty list, set transceiver.[[PreferredCodecs]] to codecs and abort these steps.

  4. Remove any duplicate values in codecs. Start at the back of the list such that the priority of the codecs is maintained; the index of the first occurrence of a codec within the list is the same before and after this step.

  5. Let kind be the transceiver's transceiver kind.

  6. If the intersection between codecs and RTCRtpSender.getCapabilities(kind).codecs or the intersection between codecs and RTCRtpReceiver.getCapabilities(kind).codecs only contains RTX, RED or FEC codecs or is an empty set, throw InvalidModificationError. This ensures that we always have something to offer, regardless of transceiver.direction.

  7. Let codecCapabilities be the union of RTCRtpSender.getCapabilities(kind).codecs and RTCRtpReceiver.getCapabilities(kind).codecs.

  8. For each codec in codecs,

    1. If codec is not in codecCapabilities, throw InvalidModificationError.
  9. Set transceiver.[[PreferredCodecs]] to codecs.

Note

If set, the offerer's codec preferences will decide the order of the codecs in the offer. If the answerer does not have any codec preferences then the same order will be used in the answer. However, if the answerer also has codec preferences, these preferences override the order in the answer. In this case, the offerer's preferences would affect which codecs were on offer but not the final order.

5.4.1 Simulcast functionality

Simulcast functionality is provided via the addTransceiver method of the RTCPeerConnection object and the setParameters method of the RTCRtpSender object.

The addTransceiver method establishes the simulcast envelope which includes the maximum number of simulcast streams that can be sent, as well as the ordering of the encodings. While characteristics of individual simulcast streams can be modified using the setParameters method, the simulcast envelope cannot be changed. One of the implications of this model is that the addTrack() method cannot provide simulcast functionality since it does not take sendEncodings as an argument, and therefore cannot configure an RTCRtpTransceiver to send simulcast.

Another implication is that the answerer cannot set the simulcast envelope directly. Upon calling the setRemoteDescription method of the RTCPeerConnection object, the simulcast envelope is configured on the RTCRtpTransceiver to contain the layers described by the specified RTCSessionDescription. Once the envelope is determined, layers cannot be removed. They can be marked as inactive by setting the active member to false effectively disabling the layer.

While setParameters cannot modify the simulcast envelope, it is still possible to control the number of streams that are sent and the characteristics of those streams. Using setParameters, simulcast streams can be made inactive by setting the active member to false, or can be reactivated by setting the active member to true. Using setParameters, stream characteristics can be changed by modifying attributes such as maxBitrate.

Note

Simulcast is frequently used to send multiple encodings to an SFU, which will then forward one of the simulcast streams to the end user. The user agent is therefore expected to allocate bandwidth between encodings in such a way that all simulcast streams are usable on their own; for instance, if two simulcast streams have the same maxBitrate, one would expect to see a similar bitrate on both streams. If bandwidth does not permit all simulcast streams to be sent in an usable form, the user agent is expected to stop sending some of the simulcast streams.

As defined in [JSEP] (section 3.7.), an offer from a user-agent will only contain a "send" description and no "recv" description on the a=simulcast line. Alternatives and restrictions (described in [MMUSIC-SIMULCAST]) are not supported.

This specification does not define how to configure reception of multiple RTP encodings using createOffer, createAnswer or addTransceiver. However when setRemoteDescription is called with a corresponding remote description that is able to send multiple RTP encodings as defined in [JSEP], and the browser supports receiving multiple RTP encodings, the RTCRtpReceiver may receive multiple RTP encodings and the parameters retrieved via the transceiver's receiver.getParameters() will reflect the encodings negotiated.

Note

An RTCRtpReceiver can receive multiple RTP streams in a scenario where a Selective Forwarding Unit (SFU) switches between simulcast streams it receives from user agents. If the SFU does not rewrite RTP headers so as to arrange the switched streams into a single RTP stream prior to forwarding, the RTCRtpReceiver will receive packets from distinct RTP streams, each with their own SSRC and sequence number space. While the SFU may only forward a single RTP stream at any given time, packets from multiple RTP streams can become intermingled at the receiver due to reordering. An RTCRtpReceiver equipped to receive multiple RTP streams will therefore need to be able to correctly order the received packets, recognize potential loss events and react to them. Correct operation in this scenario is non-trivial and therefore is optional for implementations of this specification.

5.4.1.1 Encoding Parameter Examples

This section is non-normative.

Examples of simulcast scenarios implemented with encoding parameters:

// Example of 3-layer spatial simulcast with all but the lowest resolution layer disabled
var encodings = [
  {rid: 'q', active: true, scaleResolutionDownBy: 4.0}
  {rid: 'h', active: false, scaleResolutionDownBy: 2.0},
  {rid: 'f', active: false},
];

5.4.2 "Hold" functionality

This section is non-normative.

Together, the direction attribute and the replaceTrack method enable developers to implement "hold" scenarios.

To send music to a peer and cease rendering received audio (music-on-hold):

async function playMusicOnHold() {
  try {
    // Assume we have an audio transceiver and a music track named musicTrack
    await audio.sender.replaceTrack(musicTrack);
    // Mute received audio
    audio.receiver.track.enabled = false;
    // Set the direction to send-only (requires negotiation)
    audio.direction = 'sendonly';
  } catch (err) {
    console.error(err);
  }
}

To respond to a remote peer's "sendonly" offer:

async function handleSendonlyOffer() {
  try {
    // Apply the sendonly offer first,
    // to ensure the receiver is ready for ICE candidates.
    await pc.setRemoteDescription(sendonlyOffer);
    // Stop sending audio
    await audio.sender.replaceTrack(null);
    // Align our direction to avoid further negotiation
    audio.direction = 'recvonly';
    // Call createAnswer and send a recvonly answer
    await doAnswer();
  } catch (err) {
    // handle signaling error
  }
}

To stop sending music and send audio captured from a microphone, as well to render received audio:

async function stopOnHoldMusic() {
  // Assume we have an audio transceiver and a microphone track named micTrack
  await audio.sender.replaceTrack(micTrack);
  // Unmute received audio
  audio.receiver.track.enabled = true;
  // Set the direction to sendrecv (requires negotiation)
  audio.direction = 'sendrecv';
}

To respond to being taken off hold by a remote peer:

async function onOffHold() {
  try {
    // Apply the sendrecv offer first, to ensure receiver is ready for ICE candidates.
    await pc.setRemoteDescription(sendrecvOffer);
    // Start sending audio
    await audio.sender.replaceTrack(micTrack);
    // Set the direction sendrecv (just in time for the answer)
    audio.direction = 'sendrecv';
    // Call createAnswer and send a sendrecv answer
    await doAnswer();
  } catch (err) {
    // handle signaling error
  }
}

5.5 RTCDtlsTransport Interface

The RTCDtlsTransport interface allows an application access to information about the Datagram Transport Layer Security (DTLS) transport over which RTP and RTCP packets are sent and received by RTCRtpSender and RTCRtpReceiver objects, as well other data such as SCTP packets sent and received by data channels. In particular, DTLS adds security to an underlying transport, and the RTCDtlsTransport interface allows access to information about the underlying transport and the security added. RTCDtlsTransport objects are constructed as a result of calls to setLocalDescription() and setRemoteDescription(). Each RTCDtlsTransport object represents the DTLS transport layer for the RTP or RTCP component of a specific RTCRtpTransceiver, or a group of RTCRtpTransceivers if such a group has been negotiated via [BUNDLE].

Note
A new DTLS association for an existing RTCRtpTransceiver will be represented by an existing RTCDtlsTransport object, whose state will be updated accordingly, as opposed to being represented by a new object.

An RTCDtlsTransport has a [[DtlsTransportState]] internal slot initialized to "new" and a [[RemoteCertificates]] slot initialized to an empty list.

When the underlying DTLS transport experiences an error, such as a certificate validation failure, or a fatal alert (see [RFC5246] section 7.2), the user agent MUST queue a task that runs the following steps:

  1. Let transport be the RTCDtlsTransport object to receive the state update and error notification.

  2. If the state of transport is already "failed", abort these steps.

  3. Set transport.[[DtlsTransportState]] to "failed".

  4. Fire an event named error using the RTCErrorEvent interface with its errorDetail attribute set to either "dtls-failure" or "fingerprint-failure", as appropriate, and other fields set as described under the RTCErrorDetailType enum description, at transport.

  5. Fire an event named statechange at transport.

When the underlying DTLS transport needs to update the state of the corresponding RTCDtlsTransport object for any other reason, the user agent MUST queue a task that runs the following steps:

  1. Let transport be the RTCDtlsTransport object to receive the state update.

  2. Let newState be the new state.

  3. Set transport.[[DtlsTransportState]] to newState.

  4. If newState is connected then let newRemoteCertificates be the certificate chain in use by the remote side, with each certificate encoded in binary Distinguished Encoding Rules (DER) [X690], and set transport.[[RemoteCertificates]] to newRemoteCertificates.

  5. Fire an event named statechange at transport.

WebIDL[Exposed=Window]
interface RTCDtlsTransport : EventTarget {
  [SameObject] readonly attribute RTCIceTransport iceTransport;
  readonly attribute RTCDtlsTransportState state;
  sequence<ArrayBuffer> getRemoteCertificates();
  attribute EventHandler onstatechange;
  attribute EventHandler onerror;
};

Attributes

iceTransport of type RTCIceTransport, readonly

The iceTransport attribute is the underlying transport that is used to send and receive packets. The underlying transport may not be shared between multiple active RTCDtlsTransport objects.

state of type RTCDtlsTransportState, readonly

The state attribute MUST, on getting, return the value of the [[DtlsTransportState]] slot.

onstatechange of type EventHandler
The event type of this event handler is statechange.
onerror of type EventHandler
The event type of this event handler is error.

Methods

getRemoteCertificates

Returns the value of [[RemoteCertificates]].

RTCDtlsTransportState Enum

WebIDLenum RTCDtlsTransportState {
  "new",
  "connecting",
  "connected",
  "closed",
  "failed"
};
Enumeration description
new DTLS has not started negotiating yet.
connecting DTLS is in the process of negotiating a secure connection and verifying the remote fingerprint.
connected DTLS has completed negotiation of a secure connection and verified the remote fingerprint.
closed The transport has been closed intentionally as the result of receipt of a close_notify alert, or calling close().
failed The transport has failed as the result of an error (such as receipt of an error alert or failure to validate the remote fingerprint).

5.5.1 RTCDtlsFingerprint Dictionary

The RTCDtlsFingerprint dictionary includes the hash function algorithm and certificate fingerprint as described in [RFC4572].

WebIDLdictionary RTCDtlsFingerprint {
  DOMString algorithm;
  DOMString value;
};
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.

5.6 RTCIceTransport Interface

The RTCIceTransport interface allows an application access to information about the ICE transport over which packets are sent and received. In particular, ICE manages peer-to-peer connections which involve state which the application may want to access. RTCIceTransport objects are constructed as a result of calls to setLocalDescription() and setRemoteDescription(). The underlying ICE state is managed by the ICE agent; as such, the state of an RTCIceTransport changes when the ICE Agent provides indications to the user agent as described below. Each RTCIceTransport object represents the ICE transport layer for the RTP or RTCP component of a specific RTCRtpTransceiver, or a group of RTCRtpTransceivers if such a group has been negotiated via [BUNDLE].

Note
An ICE restart for an existing RTCRtpTransceiver will be represented by an existing RTCIceTransport object, whose state will be updated accordingly, as opposed to being represented by a new object.

When the ICE Agent indicates that it began gathering a generation of candidates for an RTCIceTransport, the user agent MUST queue a task that runs the following steps:

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

  2. If connection.[[IsClosed]] is true, abort these steps.

  3. Let transport be the RTCIceTransport for which candidate gathering began.

  4. Set transport.[[IceGathererState]] to gathering.

  5. Fire an event named gatheringstatechange at transport.

  6. Update the ICE gathering state of connection.

When the ICE Agent is finished gathering a generation of candidates for an RTCIceTransport, and those candidates have been surfaced to the application, the user agent MUST queue a task that runs the following steps:

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

  2. If connection.[[IsClosed]] is true, abort these steps.

  3. Let transport be the RTCIceTransport for which candidate gathering finished.

  4. Let newCandidate be the result of creating an RTCIceCandidate with a new dictionary whose sdpMid and sdpMLineIndex are set to the values associated with this RTCIceTransport, usernameFragment is set to the username fragment of the generation of candidates for which gathering finished, and candidate is set to an empty string.

  5. Fire an event named icecandidate using the RTCPeerConnectionIceEvent interface with the candidate attribute set to newCandidate at connection.

  6. If another generation of candidates is still being gathered, abort these steps.

    Note
    This may occur if an ICE restart is initiated while the ICE agent is still gathering the previous generation of candidates.
  7. Set transport.[[IceGathererState]] to complete.

  8. Fire an event named gatheringstatechange at transport.

  9. Update the ICE gathering state of connection.

When the ICE Agent indicates that a new ICE candidate is available for an RTCIceTransport, either by taking one from the ICE candidate pool or gathering it from scratch, the user agent MUST queue a task that runs the following steps:

  1. Let candidate be the available ICE candidate.

  2. Let connection be the RTCPeerConnection object associated with this ICE Agent.

  3. If connection.[[IsClosed]] is true, abort these steps.

  4. If either connection.[[PendingLocalDescription]] or connection.[[CurrentLocalDescription]] are not null, and represent the ICE generation for which candidate was gathered, surface the candidate with candidate and connection, and abort these steps.

  5. Otherwise, append candidate to connection.[[EarlyCandidates]].

When the ICE Agent signals that the ICE role has changed due to an ICE binding request with a role collision per [RFC8445] section 7.3.1.1, the UA will queue a task to set the value of [[IceRole]] to the new value.

To release early candidates of a connection, run the following steps:

  1. For each candidate, candidate, in connection.