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.

dictionary RTCConfiguration {
             sequence<RTCIceServer>   iceServers;
             RTCIceTransportPolicy    iceTransportPolicy = "all";
             RTCBundlePolicy          bundlePolicy = "balanced";
             RTCRtcpMuxPolicy         rtcpMuxPolicy = "require";
             DOMString                peerIdentity;
             sequence<RTCCertificate> certificates;
             unsigned short           iceCandidatePoolSize = 0;
};

4.2.2 RTCIceCredentialType Enum

enum RTCIceCredentialType {
    "password",
    "token"
};

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.

dictionary RTCIceServer {
    required (DOMString or sequence<DOMString>) urls;
             DOMString                          username;
             DOMString                          credential;
             RTCIceCredentialType               credentialType = "password";
};

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 noted in [JSEP] (section 4.1.1.), if RTCIceTransportPolicy is specified, it causes the browser to only surface the permitted candidates to the application, and only use those candidates for connectivity checks.

enum RTCIceTransportPolicy {
    "public",
    "relay",
    "all"
};

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.

enum RTCBundlePolicy {
    "balanced",
    "max-compat",
    "max-bundle"
};

4.2.6 RTCRtcpMuxPolicy Enum

Defined in [JSEP] (section 4.1.1.). The following is a non-normative summary for convenience.

The RtcpMuxPolicy affects what ICE candidates are gathered to support non-multiplexed RTCP.

enum RTCRtcpMuxPolicy {
    "negotiate",
    "require"
};

4.2.7 Offer/Answer Options

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

dictionary RTCOfferAnswerOptions {
             boolean voiceActivityDetection = true;
};

dictionary RTCOfferOptions : RTCOfferAnswerOptions {
             boolean iceRestart = false;
};

dictionary RTCAnswerOptions : RTCOfferAnswerOptions {
};

4.3.1 Operation

Calling new RTCPeerConnection(configuration ) creates an RTCPeerConnection object.

The configuration has the information to find and access the servers used by ICE. There may be multiple servers of each type and any TURN server also acts as a STUN server.

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

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

1. Let connection be a newly created RTCPeerConnection object.

2. Set the configuration specified by the constructor's first argument.

3. Create an ICE Agent as defined in [ICE] and let connection's RTCPeerConnection ICE Agent be that ICE Agent. The ICE Agent will proceed with gathering as soon as the ICE transports setting is not set to none. At this point the ICE Agent does not know how many ICE components it needs (and hence the number of candidates to gather), but it can make a reasonable assumption such as 2. As the RTCPeerConnection object gets more information, the ICE Agent can adjust the number of components.

4. Set connection's signaling state to stable.

5. Set connection's ICE connection state to new.

6. Set connection's ICE gathering state to new.

7. Set connection's pendingLocalDescription, currentLocalDescription, pendingRemoteDescription and currentRemoteDescription to null.

8. Initialize an internal variable operations to represent a queue of operations with an empty array.

9. If the certificates value in the RTCConfiguration structure is non-empty, check that the expires on each value is in the future. If a certificate has expired, throw an InvalidAccessError exception and abort these steps; otherwise, store the certificates. If no certificates value was specified, one or more new RTCCertificate instances are generated for use with this RTCPeerConnection instance.

10. Return connection.

Once the RTCPeerConnection object has been initialized, for every call to createOffer, setLocalDescription, createAnswer, setRemoteDescription, and addIceCandidate, execute the following steps:

1. Let p be a new promise.

2. Append an object representing the current call being handled (i.e. function name and corresponding arguments) to the operations array.

3. If the length of the operations array is exactly 1, execute the object from the front of the queue.

4. Upon fulfillment or rejection of the promise returned by the function, fulfill or reject p with the corresponding value or reason. Upon fulfillment or rejection of p, execute the following steps:

   1. Remove the corresponding object from the operations array.

   2. If the array is non-empty, execute the first object queued.

5. Return p.

The general idea is to have only one among createOffer, setLocalDescription, createAnswer and setRemoteDescription and addIceCandidate executing at any given time. If subsequent calls are made while the returned promise of a previous call is still unsettled, they are added to a queue and executed when all the previous calls are executed and their promises are settled.

Additionally, during the lifetime of the RTCPeerConnection object, the following procedures are followed when an ICE event occurs:

1. If the RTCPeerConnection's ICE gathering state is new and the ICE transports setting is not set to none, the user agent MUST queue a task to start gathering ICE addresses and update the ICE gathering state to gathering.

2. If the ICE Agent has found one or more candidate pairs for each MediaStreamTrack that forms a valid connection, update the ICE connection state to connected.

3. When the ICE Agent finishes checking all candidate pairs, if at least one connection has been found for each media description, update the ICE connection state to completed, otherwise to failed.

When a new ICE candidate is available or when the ICE gathering process is done , the user agent MUST queue a task to run the following steps:

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

2. If connection's signaling state is closed, abort these steps.

3. If the intent of the ICE Agent is to notify the script that:

   • A new candidate is available.

     Add the candidate to connection's localDescription and create a RTCIceCandidate instance to represent the candidate. Let newCandidate be that object.

   • The gathering process is done.

     Update connection's ICE gathering state to completed and let newCandidate be null.

4. Fire an event named icecandidate with newCandidate at connection.

To update the ICE gathering state of an RTCPeerConnection instance connection to newState, the User Agent MUST queue a task that sets connection's iceGatheringState attribute to newState and fires a simple event named icegatheringstatechange at connection.

To update the ICE connection state of an RTCPeerConnection instance connection to newState, the User Agent MUST queue a task that sets connection's iceConnectionState attribute to newState and fires a simple event named icegatheringstatechange at connection.

To set an RTCSessionDescription description on an RTCPeerConnection object connection, run the following steps:

1. If connection's signaling state is closed, the user agent MUST return a promise rejected with an InvalidStateError.

2. Let p be a new promise.

3. In parallel, start the process to apply description as described in [JSEP] (section 5.4. and section 5.5.).

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

      1. If connection's signaling state is closed, then abort these steps.

      2. If elements of the SDP were modified in an invalid way as specified in [JSEP] (section 6.), then reject p with an InvalidModificationError and abort these steps.

      3. If the description's type is wrong for the current signaling state of connection, then reject p with a InvalidStateError and abort these steps.

         If the content of description is invalid, then reject p with an InvalidAccessError and abort these steps.

      4. If description cannot be applied at the media layer, but the User Agent recovered, possibly by rolling back to the previous configuration, then reject p with OperationError and abort these steps.

         This occurs, for example, when the version of description is older than the one currently being used.

      5. Otherwise, set connection's signaling state to closed.

      6. Fire a simple event named signalingstatechange at connection.

      7. Reject p with OperationError.

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

      1. If connection's signaling state is closed, then abort these steps.

      2. If description is set as a local description, and its content matches the state of all tracks and data channels, as defined below, clear the negotiation-needed flag.

         Issue 1

         NOTE: The principles of pending and current SDP were agreed by the WG but the details in the next steps have not yet been fully reviewed. TODO - review this.

      3. If description is set as a local description, then run one of the following steps:

         • If description is of type "offer", set connection's pendingLocalDescription attribute to description and signaling state to have-local-offer.

         • If description is of type "answer", then this completes an offer answer negotiation. Set connection's currentLocalDescription to description and currentRemoteDescription to the value of pendingRemoteDescription. Set both pendingRemoteDescription and pendingLocalDescription to null. Finally set connection's signaling state to stable

         • If description is of type "rollback", then this is a rollback. Set connection's pendingLocalDescription to null and signaling state to stable.

         • If description is of type "pranswer", then set connection's pendingLocalDescription to description and signaling state to have-local-pranswer.

      4. Otherwise, if description is set as a remote description, then run one of the following steps:

         • If description is of type "offer", set connection's pendingRemoteDescription attribute to description and signaling state to have-remote-offer.

         • If description is of type "answer", then this completes an offer answer negotiation. Set connection's currentRemoteDescription to description and currentLocalDescription to the value of pendingLocalDescription. Set both pendingRemoteDescription and pendingLocalDescription to null. Finally set connection's signaling state to stable

         • If description is of type "rollback", then this is a rollback. Set connection's pendingRemoteDescription to null and signaling state to stable.

         • If description is of type "pranswer", then set connection's pendingRemoteDescription to description and signaling state to have-remote-pranswer.

      5. If connection's signaling state changed above, fire a simple event named signalingstatechange at connection.

      6. If description is set as a local description, connection's ICE gathering state is new, and description contains media, then update connection's ICE gathering state to gathering.

      7. If the process to apply description resulted in an ICE restart [JSEP] (section 5.7. and section 5.8.), then run the following steps:

         1. If connection is not already gathering, update connection's ICE gathering state to gathering.

         2. If connection's ICE connection state is completed, update connection's ICE connection state to connected.

      8. If description is set as a remote description with new media descriptions [JSEP], the User Agent MUST dispatch a receiver for all new media descriptions.

      9. If connection's signaling state is now stable, and the negotiation-needed flag is set, the User Agent MUST queue a task to fire a simple event named negotiationneeded at connection and clear the negotiation-needed flag.

      10. Resolve p with undefined.

4. Return p.

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

4.3.2 Interface Definition

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

[ Constructor (optional RTCConfiguration configuration)]
interface RTCPeerConnection : EventTarget  {
    Promise<RTCSessionDescription> createOffer (optional RTCOfferOptions options);
    Promise<RTCSessionDescription> createAnswer (optional RTCAnswerOptions options);
    Promise<void>                  setLocalDescription (RTCSessionDescriptionInit 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 ((RTCIceCandidateInit or RTCIceCandidate) candidate);
    readonly        attribute RTCSignalingState         signalingState;
    readonly        attribute RTCIceGatheringState      iceGatheringState;
    readonly        attribute RTCIceConnectionState     iceConnectionState;
    readonly        attribute RTCPeerConnectionState    connectionState;
    readonly        attribute boolean?                  canTrickleIceCandidates;
    static readonly attribute FrozenArray<RTCIceServer> defaultIceServers;
    RTCConfiguration               getConfiguration ();
    void                           setConfiguration (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;
};

4.3.3 Legacy Interface Extensions

partial interface RTCPeerConnection {
    void createOffer (RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback, optional RTCOfferOptions options);
    void setLocalDescription (RTCSessionDescriptionInit description, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback);
    void createAnswer (RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback);
    void setRemoteDescription (RTCSessionDescriptionInit description, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback);
    void addIceCandidate ((RTCIceCandidateInit or RTCIceCandidate) candidate, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback);
    void getStats (MediaStreamTrack? selector, RTCStatsCallback successCallback, RTCPeerConnectionErrorCallback failureCallback);
};

4.3.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 signaling state is closed, 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 a RTCPeerConnection have a strong reference to the RTCPeerConnection object.

4.4.1 RTCSignalingState Enum

enum RTCSignalingState {
    "stable",
    "have-local-offer",
    "have-remote-offer",
    "have-local-pranswer",
    "have-remote-pranswer",
    "closed"
};

An example set of transitions might be:

Caller transition:

• new RTCPeerConnection(): stable
• setLocal(offer): have-local-offer
• setRemote(pranswer): have-remote-pranswer
• setRemote(answer): stable
• close(): closed

Callee transition:

• new RTCPeerConnection(): stable
• setRemote(offer): have-remote-offer
• setLocal(pranswer): have-local-pranswer
• setLocal(answer): stable
• close(): closed

4.4.2 RTCIceGatheringState Enum

enum RTCIceGatheringState {
    "new",
    "gathering",
    "complete"
};

4.4.3 RTCPeerConnectionState Enum

enum RTCPeerConnectionState {
    "new",
    "connecting",
    "connected",
    "disconnected",
    "failed"
};

4.4.4 RTCIceConnectionState Enum

enum RTCIceConnectionState {
    "new",
    "checking",
    "connected",
    "completed",
    "failed",
    "disconnected",
    "closed"
};

States take either the value of any component or all components, as outlined below:

• checking occurs if ANY component has received a candidate and can start checking
• connected occurs if ALL components have established a working connection
• completed occurs if ALL components have finalized the running of their ICE processes
• failed occurs if ANY component has given up trying to connect
• disconnected occurs if ANY component has failed liveness checks
• closed occurs only if RTCPeerConnection’s close() method has been called.

If a component is discarded as a result of signaling (e.g. RTCP mux or BUNDLE), the state may advance directly from checking to completed.

Some example transitions might be:

• new RTCPeerConnection(): new
• (new, remote candidates received): checking
• (checking, found usable connection): connected
• (checking, checks fail but gathering still in progress): disconnected
• (checking, gave up): failed
• (disconnected, new local candidates): checking
• (connected, finished all checks): completed
• (completed, lost connectivity): disconnected
• (any state, ICE restart occurs): new
• close(): closed

4.5.1 RTCPeerConnectionErrorCallback

callback RTCPeerConnectionErrorCallback = void (DOMException error);

4.5.2 RTCSessionDescriptionCallback

callback RTCSessionDescriptionCallback = void (RTCSessionDescription sdp);

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

Legacy-methods may only throw exceptions to indicate invalid state and other programming errors. For example, when a legacy-method is called when the RTCPeerConnection is in an invalid state or a state in which that particular method is not allowed to be executed, it will throw an exception. In all other cases, legacy methods MUST provide an error object to the error callback.

4.7.1 RTCSdpType

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

enum RTCSdpType {
    "offer",
    "pranswer",
    "answer",
    "rollback"
};

4.7.2 RTCSessionDescription Class

The RTCSessionDescription class is used by RTCPeerConnection to expose local and remote session descriptions. Attributes on this interface are mutable for legacy reasons.

dictionary RTCSessionDescriptionInit {
    required RTCSdpType type;
             DOMString  sdp;
};

[ Constructor (RTCSessionDescriptionInit descriptionInitDict)]
interface RTCSessionDescription {
                    attribute RTCSdpType type;
                    attribute DOMString  sdp;
    serializer = {attribute};
};

4.8.1 Setting Negotiation-Needed

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 a track, or adding the first data channel.

Internal changes within the implementation can also result in the connection being marked as needing negotiation. For example, if a MediaStreamTrack enters the ended state because its source device became unavailable.

4.8.2 Clearing Negotiation-Needed

The negotiation-needed flag is cleared when setLocalDescription is called (either for an offer or answer), and the supplied description matches the state of the tracks/datachannels that currenly exist on the RTCPeerConnection. Specifically, this means that all live tracks have an associated section in the local description with their MSID, all ended tracks have been removed from the local description, and, if any data channels have been created, a data section exists in the local description.

Note that setLocalDescription(answer) will clear the negotiation-needed flag only if the offer had a corresponding section for all the tracks/datachannels on the answerer side. Otherwise, a new offer by the answerer is still needed, and so the state is not cleared.

4.8.3 Firing An Event

When the RTCPeerConnection connection is marked as negotiation-needed, and it was not already marked as such:

• If the signaling state is stable, schedule a task to check the negotiation-needed flag and, if still set, fire a negotiationneeded event on connection.
• Otherwise, do nothing. If necessary, an event will be fired during setLocalDescription or setRemoteDescription processing, as described above.

4.9.1 RTCIceCandidate Interface

This interface describes an ICE candidate.

dictionary RTCIceCandidateInit {
    required DOMString      candidate;
             DOMString      sdpMid;
             unsigned short sdpMLineIndex;
};

[ Constructor (RTCIceCandidateInit candidateInitDict)]
interface RTCIceCandidate {
    readonly        attribute DOMString               candidate;
    readonly        attribute DOMString?              sdpMid;
    readonly        attribute unsigned short?         sdpMLineIndex;
    readonly        attribute DOMString               foundation;
    readonly        attribute unsigned long           priority;
    readonly        attribute DOMString               ip;
    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;
    serializer = {candidate, sdpMid, sdpMLineIndex};
};

enum RTCIceProtocol {
    "udp",
    "tcp"
};

enum RTCIceTcpCandidateType {
    "active",
    "passive",
    "so"
};

enum RTCIceCandidateType {
    "host",
    "srflx",
    "prflx",
    "relay"
};

4.9.2 RTCPeerConnectionIceEvent

The icecandidate event of the RTCPeerConnection uses the RTCPeerConnectionIceEvent interface.

Firing an RTCPeerConnectionIceEvent event named e with an RTCIceCandidate candidate means that an event with the name e, which does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated), and which uses the RTCPeerConnectionIceEvent interface with the candidate attribute set to the new ICE candidate, MUST be created and dispatched at the given target.

When firing an RTCPeerConnectionIceEvent event that contains a 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.

dictionary RTCPeerConnectionIceEventInit : EventInit {
             RTCIceCandidate candidate;
             DOMString       url;
};

[ Constructor (DOMString type, RTCPeerConnectionIceEventInit eventInitDict)]
interface RTCPeerConnectionIceEvent : Event {
    readonly        attribute RTCIceCandidate? candidate;
    readonly        attribute DOMString?       url;
};

4.9.3 RTCPeerConnectionIceErrorEvent

The icecandidateerror event of the RTCPeerConnection uses the RTCPeerConnectionIceErrorEvent interface.

dictionary RTCPeerConnectionIceErrorEventInit : EventInit {
             DOMString      hostCandidate;
             DOMString      url;
             unsigned short errorCode;
             USVString      statusText;
};

[ Constructor (DOMString type, RTCPeerConnectionIceErrorEventInit eventInitDict)]
interface RTCPeerConnectionIceErrorEvent : Event {
    readonly        attribute DOMString      hostCandidate;
    readonly        attribute DOMString      url;
    readonly        attribute unsigned short errorCode;
    readonly        attribute USVString      errorText;
};

4.10.1 RTCPriorityType Enum

enum RTCPriorityType {
    "very-low",
    "low",
    "medium",
    "high"
};

4.11.1 Methods

generateCertificate, static

The generateCertificate function causes the user agent to create and store 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 keygenAlgorithm value MUST be a valid argument to window.crypto.subtle.generateKey; that is, the value MUST produce a non-error result when normalized according to the WebCrypto algorithm normalization process [WebCryptoAPI] with an operation name of generateKey and a [[supportedAlgorithms]] value specific to production of certificates for RTCPeerConnection. If the algorithm normalization process produces an error, the call to generateCertificate MUST be rejected with that error.

Signatures produced by the generated key are used to authenticate the DTLS connection. The identified algorithm (as identified by the name of the normalized AlgorithmIdentifier) MUST be an asymmetric algorithm that can be used to produce a signature.

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.

An optional expires attribute MAY be added to the keygenAlgorithm parameter. If this contains a DOMTimeStamp value, it indicates the maximum time that the RTCCertificate is valid for relative to the current time. A user agent sets the expires attribute of the returned RTCCertificate to the current time plus the value of the expires attribute. However, a user agent MAY choose to limit the period over which an RTCCertificate is valid.

A user agent MUST reject a call to generateCertificate() with a DOMException of type NotSupportedError if the keygenAlgorithm parameter identifies an algorithm that the user agent cannot or will not use to generate a certificate for RTCPeerConnection.

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.

Parameter	Type	Nullable	Optional	Description
keygenAlgorithm	AlgorithmIdentifier	✘	✘

Return type: Promise<RTCCertificate>

4.11.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 ([[handle]]) and a certificate ([[certificate]]) that RTCPeerConnection uses to authenticate with a peer.

interface RTCCertificate {
    readonly        attribute DOMTimeStamp expires;
};

For the purposes of this API, the [[certificate]] slot contains unstructured binary data.

Note that a RTCCertificate might not directly hold private keying material, this might be stored in a secure module.

The RTCCertificate object can be stored and retrieved from persistent storage by an application. When a user agent is required to obtain a structured clone [HTML] of a RTCCertificate object, it performs the following steps:

1. Let input and memory be the corresponding inputs defined by the internal structured cloning algorithm, where input represents a RTCCertificate object to be cloned.
2. Let output be a newly constructed RTCCertificate object.
3. Copy the value of the expires attribute from input to output.
4. Let the [[certificate]] internal slot of output be set to the result of invoking the internal structured clone algorithm recursively on the corresponding internal slots of input, with the slot contents as the new "input" argument and memory as the new "memory" argument.
5. Let the [[handle]] internal slot of output refer to the same private keying material represented by the [[handle]] internal slot of input.

5.1.1 Attributes

ontrack of type EventHandler

The event type of this event handler is track.

5.1.2 Methods

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 the MediaStreamTrack track, is to be added.

2. If connection's signaling state is closed, throw an InvalidStateError exception and abort these steps.

3. If an RTCRtpSender for track already exists in connection's set of senders, throw an InvalidAccessError exception and abort these steps.

4. If an RTCRtpSender exists in connection's set of senders that has never been used to send (the corresponding media description has always had a direction of recvonly or inactive), then set that sender's track to track and return the sender.

   Doing so will cause future calls to createOffer and createAnswer to mark the corresponding media description as sendrecv or sendonly, as defined in [JSEP].

   .

5. If no such sender exists, create a new RTCRtpTransceiver with sender.track set to track, add it to connection's set of transceivers, and return sender to the caller.

6. A track could have contents that are inaccessible to the application. This can be due to being marked with a peerIdentity option or 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, unless they are also marked with peerIdentity and they meet the requirements for sending (see isolated streams and RTCPeerConnection).

   All other tracks that are not accessible to the application MUST NOT be sent to the peer, with silence (audio), black frames (video) or equivalently absent content being sent in place of track content.

   Note that this property can change over time.

7. Mark connection as needing negotiation.

Parameter	Type	Nullable	Optional	Description
track	MediaStreamTrack	✘	✘
streams	MediaStream	✘	✘

Return type: RTCRtpSender

addTransceiver

Create a new RTCRtpTransceiver and add it to the collection of transceivers that will be returned by getReceivers().

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

.

If a track is passed in, the value of the sender.track will be set to that track and the MSID and media type generated by createOffer will be that of the track.

If a kind is passed in, the value of the sender.track will be null and and media type generated by createOffer will be that of the kind. The MSID generated by createOffer (if necessary, such as when init.send == true) will be selected by the user agent and will not be related to any track. Future calls to sender.replaceTrack with a track of a different kind will fail. Future calls will not change the MSID associated with the transceiver.

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

RID values passed into init.sendEncodings must be composed only of case-sensitive alphanumeric characters (a-z, A-Z, 0-9) up to a maximum of 16 characters.

Parameter	Type	Nullable	Optional	Description
trackOrKind	(MediaStreamTrack or DOMString)	✘	✘
init	RTCRtpTransceiverInit	✘	✘

Return type: RTCRtpTransceiver

getReceivers

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

The getReceivers() method MUST return a new sequence that represents a snapshot of all the RTCRtpReceiver objects in this RTCPeerConnection object's set of receivers. The conversion from the receivers set to the sequence, to be returned, is user agent defined and the order does not have to be stable between calls.

No parameters.

Return type: sequence<RTCRtpReceiver>

getSenders

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

The getSenders() method MUST return a new sequence that represents a snapshot of all the RTCRtpSenders objects in this RTCPeerConnection object's set of senders. The conversion from the senders set to the sequence, to be returned, is user agent defined and the order does not have to be stable between calls.

No parameters.

Return type: sequence<RTCRtpSender>

getTransceivers

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

The getTransceivers() method MUST return a new sequence that represents a snapshot of all the RTCRtpTransceiver objects in this RTCPeerConnection object's set of transeceivers. The conversion from the transeceiver set to the sequence, to be returned, is user agent defined and the order does not have to be stable between calls.

No parameters.

Return type: sequence<RTCRtpTransceiver>

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

When the other peer stops sending a track in this manner, an ended event is fired at the MediaStreamTrack object.

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

1. Let connection be the RTCPeerConnection object on which the RTCRtpSender, sender, is to be stopped.

2. If connection's signaling state is closed, throw an InvalidStateError exception.

3. If sender is stopped or not in connection's set of senders, then abort these steps.

4. Stop sender.

5. Mark connection as needing negotiation.

Parameter	Type	Nullable	Optional	Description
sender	RTCRtpSender	✘	✘

Return type: void

5.1.3 Dictionary RTCRtpTransceiverInit Members

receive of type boolean, defaulting to true

If true, indicates that the RTCRtpTransceiver's RTCRtpReceiver will offer to receive RTP and receive RTP if the remote peer accepts. If false, indicates that the RTCRtpReceiver will not offer to receive RTP and will not receive RTP (the direction of the media description generated by createOffer will be sendonly or inactive).

send of type boolean, defaulting to true

If true, indicates that the RTCRtpTransceiver's RTCRtpSender will offer to send RTP and send RTP if the remote peer accepts. If false, indicates that the RTCRtpSender will not offer to send RTP and will not send RTP (the direction of the media description generated by createOffer will be recvonly or inactive).

sendEncodings of type sequence<RTCRtpEncodingParameters>

A sequence containing parameters for sending RTP encodings of media.

streams of type sequence<MediaStream>

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

5.1.4 Processing Remote MediaStreamTracks

Rejection of incoming MediaStreamTrack objects can be done by the application, after receiving the track, by stopping it.

To dispatch a receiver for an incoming media description [JSEP], the user agent MUST run the following steps:

1. Let connection be the RTCPeerConnection expecting this media.

2. If connection's signaling state is closed, abort these steps.

3. Let streams be a list of MediaStream objects that the sender indicated the sent MediaStreamTrack being a part of. The information needed to collect these objects is part of the media description.

4. Run the following steps to create a track representing the incoming media description:

   1. Create a MediaStreamTrack object track to represent the media description.

   2. Initialize track.kind attribute to audio or video depending on the media type of the media description.

   3. Initialize track.id attribute to the media description track id.

   4. Initialize track.label attribute to remote audio or remote video depending on the media type of the media description.

   5. Initialize track.readyState attribute to live.

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

5. Add track to all MediaStream objects in streams.

   Note

   This will result in an addtrack event being fired at each MediaStream as described in [GETUSERMEDIA].

6. Create a new RTCRtpReceiver object receiver for track, and add it to connection's set of receivers.

7. Fire an event named track with transceiver, track, and streams at the connection object.

When an RTCPeerConnection finds that a track from the remote peer has been removed, the user agent MUST follow these steps:

1. Let connection be the RTCPeerConnection associated with the track being removed.

2. Let track be the MediaStreamTrack object that represents the track being removed, if any. If there isn't one, then abort these steps.

3. By definition, track is now ended.

   Note

   A task is thus queued to update track and fire an event.

4. Queue a task to run the following substeps:

   1. If connection's signaling state is closed, abort these steps.

   2. Remove the RTCRtpReceiver associated with track from connection's set of receivers.

5.2.1 Attributes

rtcpTransport of type RTCDtlsTransport, readonly , nullable

The rtcpTransport attribute is the transport over which RTCP is sent and received. When BUNDLE is used, many RTCRtpSender objects will share one rtcpTransport and will all send and receive RTCP over the same transport. When RTCP mux is used, rtcpTransport will be null, and both RTP and RTCP traffic will flow over the transport described by transport.

track of type MediaStreamTrack, readonly

The track attribute is the track that is associated with this RTCRtpSender object.

transport of type RTCDtlsTransport, readonly

The transport attribute is the transport over which media from track is sent in the form of RTP packets. When BUNDLE is used, many RTCRtpSender objects will share one transport and will all send RTP over the same transport. When RTCP mux is used, rtcpTransport will be null, and both RTP and RTCP traffic will flow over the transport described by transport.

5.2.2 Methods

getCapabilities, static

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

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.

Parameter	Type	Nullable	Optional	Description
kind	DOMString	✘	✘

Return type: RTCRtpCapabilities

getParameters

The getParameters method returns the RTCRtpSender object's current parameters for how track is encoded and transmitted to a remote RTCRtpReceiver. It may used with setParameters to change the parameters in the follwing way:

Example 2

var params = sender.getParameters();
// ... make changes to RTCRtpParameters
params.encodings[0].active = false;
sender.setParameters(params)

No parameters.

Return type: RTCRtpParameters

replaceTrack

Attempts to replace the track being sent with another track provided, without renegotiation.

To avoid track identifiers changing on the remote receiving end when a track is replaced, the sender MUST retain the original track identifier and stream associations and use these in subsequent negotiations.

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 connection be the RTCPeerConnection object that created sender.

3. If sender is stopped, return a promise rejected with an InvalidStateError.

4. Let withTrack be the argument to this method.

5. If withTrack.kind differs from the sender.track.kind, return a promise rejected with a TypeError.

6. Let localDescription be connection's pendingLocalDescription if not null, otherwise connection's currentLocalDescription.

7. If sender is not represented in localDescription, then set sender's track attribute to withTrack, and resolve p with undefined.

8. Let p be a new promise.

9. Run the following steps in parallel:

   1. Determine if negotiation is needed to transmit withTrack in place of the sender's existing track. Ignore which MediaStream the track resides in and the id attribute of the track in this determination. If negotiation is needed, then reject p with InvalidModificationError and abort these steps.

   2. Have the sender switch seamlessly to transmitting withTrack in place of what it is sending, without negotiating.

   3. Queue a task that sets sender's track attribute to withTrack, and resolves p with undefined.

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

Parameter	Type	Nullable	Optional	Description
withTrack	MediaStreamTrack	✘	✘

Return type: Promise<void>

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 sender be the RTCRtpSender object on which replaceTrack is invoked.
2. Let p be a new promise.
3. Return p, performing the next steps in parallel.
4. If any parameter in the parameters argument, marked as a Read-only parameter, has a value that is different from the corresponding parameter value returned from getParameters(), abort these steps and return a promise rejected with RangeError. Note that this also applies to transactionId.
5. Set the RTPSender's internal transactionId slot to a previously unused value.
6. Resolve p with undefined.

If codecs are reordered, the new order indicates the preference for sending, with the first codec being the codec with highest preference. If a codec is removed, that codec will not be used to send. The effect of reordering or removing codecs lasts until the codecs are renegotiated. After the codecs are renegotiated, they are set to the value negotiated, and setParameters needs to be called again to re-apply codec preferences.

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

Parameter	Type	Nullable	Optional	Description
parameters	RTCRtpParameters	✘	✔

Return type: Promise<void>

5.2.3 Dictionary RTCRtpParameters Members

codecs of type sequence<RTCRtpCodecParameters>

A sequence containing the codecs that an RTCRtpSender will choose from in order to send media.

degradationPreference of type RTCDegradationPreference, defaulting to "balanced"

When bandwidth is constrained and the RtpSender needs to choose between degrading resolution or degrading framerate, degradationPreference indicates which is preferred.

encodings of type sequence<RTCRtpEncodingParameters>

A sequence containing parameters for RTP encodings of media.

headerExtensions of type sequence<RTCRtpHeaderExtensionParameters>

A sequence containing parameters for RTP header extensions.

rtcp of type RTCRtcpParameters

Parameters used for RTCP.

transactionId of type DOMString

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

5.2.4 Dictionary RTCRtpEncodingParameters Members

active of type boolean

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.

fec of type RTCRtpFecParameters

The parameters used for FEC, or unset if FEC is not being used.

maxBitrate of type unsigned long

Indicates the maximum bitrate that can be used to send this encoding. The encoding may also be further constrained by other limits (such as maxFramerate or per-transport or per-session bandwidth limits) below the maximum specified here. maxBitrate is 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.

maxFramerate of type unsigned long

Indicates the maximum framerate that can be used to send this encoding.

priority of type RTCPriorityType

Indicates the priority of this encoding. It is specified in [RTCWEB-TRANSPORT], Section 4.

rid of type DOMString

If set, this RTP encoding will be sent with the RID header extension as defined by [JSEP].

rtx of type RTCRtpRtxParameters

The parameters used for RTX, or unset if RTX is not being used.

scaleResolutionDownBy of type double, defaulting to 1.0

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

ssrc of type unsigned long

The SSRC of the RTP source stream of this encoding (non-RTX, non-FEC RTP stream). Read-only parameter.

5.2.5 Dictionary RTCRtpRtxParameters Members

ssrc of type unsigned long

The SSRC of the RTP stream for RTX. Read-only parameter.

5.2.6 Dictionary RTCRtpFecParameters Members

ssrc of type unsigned long

The SSRC of the RTP stream for FEC. Read-only parameter.

5.2.7 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 Dictionary RTCRtpHeaderExtensionParameters Members

encrypted of type boolean

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

id of type unsigned short

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

uri of type DOMString

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

5.2.9 Dictionary RTCRtpCodecParameters Members

channels of type unsigned short, defaulting to 1

The number of channels (mono=1, stereo=2).

clockRate of type unsigned long

The codec clock rate expressed in Hertz.

mimeType of type DOMString

The codec MIME type. Valid types are listed in [IANA-RTP-2].

payloadType of type unsigned short

The RTP payload type. This value can be set to control which codec should be used to send a given encoding.

sdpFmtpLine of type DOMString

The a=fmtp line in the SDP corresponding to the codec, as defined by [JSEP] (section 5.6.).

5.2.10 Dictionary RTCRtpCapabilities Members

codecs of type sequence<RTCRtpCodecCapability>

Supported codecs.

headerExtensions of type sequence<RTCRtpHeaderExtensionCapability>

Supported RTP header extensions.

5.2.11 Dictionary RTCRtpCodecCapability Members

mimeType of type DOMString

The codec MIME type. Valid types are listed in [IANA-RTP-2].

5.2.12 Dictionary RTCRtpHeaderExtensionCapability Members

uri of type DOMString

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

5.3.1 Attributes

rtcpTransport of type RTCDtlsTransport, readonly , nullable

The rtcpTransport attribute is the transport over which RTCP is sent and received. When BUNDLE is used, many RTCRtpReceiver objects will share one RTCRtpReceiver.rtcpTransport and will all send and receive RTCP over the same transport. When RTCP mux is used, rtcpTransport will be null, and both RTP and RTCP traffic will flow over transport.

track of type MediaStreamTrack, readonly

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

transport of type RTCDtlsTransport, readonly

The transport attribute is the transport over which media for the receiver's track is received in the form of RTP packets. When BUNDLE is used, many RTCRtpReceiver objects will share one transport and will all receive RTP over the same transport. When RTCP mux is used, rtcpTransport will be null, and both RTP and RTCP traffic will flow over transport.

5.3.2 Methods

getCapabilities, static

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

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.

Parameter	Type	Nullable	Optional	Description
kind	DOMString	✘	✘

Return type: RTCRtpCapabilities

getContributingSources

Returns an RTCRtpContributingSource for each unique CSRC or SSRC received by this RTCRtpReceiver in the last 10 seconds.

No parameters.

Return type: sequence<RTCRtpContributingSource>

5.3.3 Attributes

audioLevel of type byte, readonly , nullable

The audio level contained in the last RTP packet received from this source. If the source was set from an SSRC, this will be the level value defined in [RFC6464]. If an RFC 6464 extension header is not present, the browser will compute the value as if it had come from RFC 6464 and use that. If the source was set from a CSRC, this will be the level value defined in [RFC6465]. RFC 6464 and 6465 define the level as a integral value from 0 to 127 representing the audio level in negative decibels relative to the loudest signal that they system could possibly encode. Thus, 0 represents the loudest signal the system could possibly encode, and 127 represents silence.

source of type unsigned long, readonly

The CSRC or SSRC value of the contributing source.

timestamp of type DOMHighResTimeStamp, readonly

The timestamp of type DOMHighResTimeStamp [HIGHRES-TIME], indicating the time of reception of the most recent RTP packet containing the source. The timestamp is defined in [HIGHRES-TIME] and corresponds to a local clock.

voiceActivityFlag of type boolean, readonly , nullable

Whether the last RTP packet received from this source contains voice activity (true) or not (false). Since the "V" bit is supported in [RFC6464] but not [RFC6465], the voiceActivityFlag attribute will only be set for RTP packets received from peers enabling the client-mixer header extension with the "vad" extension set to "on".

5.4.1 Attributes

mid of type DOMString, readonly , nullable

The mid attribute is the mid negotatiated and present in the local and remote descriptions as defined in [JSEP] (section 5.2.1. and section 5.3.1.). Before negotiation is complete, the mid value may be null. After rollbacks, the value may change from a non-null value to null.

receiver of type RTCRtpReceiver, readonly

The receiver attribute is the RTCRtpReceiver corresponding to the RTP media that may be received with mid = mid.

sender of type RTCRtpSender, readonly

The sender attribute is the RTCRtpSender corresponding to the RTP media that may be sent with mid = mid.

stopped of type boolean, readonly

The stopped attribute indicates that the sender of this transceiver will no longer send, and that the receiver will no longer receive. It is true if either stop has been called or if setting the local or remote description has caused the RTCRtpReceiver to be stopped.

5.4.2 Methods

activateSender

The activateSender method activates the RTCRtpTransceiver.sender such that future calls to createOffer and createAnswer mark the corresponding media description as sendrecv or sendonly, as defined in [JSEP].

If the sender is not already active and the PeerConnection is in the stable state, this will set the negotiationneeded flag.

No parameters.

Return type: void

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. Note that calls to createAnswer will use only the common subset of these codecs and the codecs that appear in the offer.

This method allows applications to disable the negotiation of specific codecs. 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.

Parameter	Type	Nullable	Optional	Description
codecs	sequence<RTCRtpCodecCapability>	✘	✘

Return type: void

stop

The stop method stops the RTCRtpTransceiver. The sender of this transceiver will no longer send, and the receiver will no longer receive.

No parameters.

Return type: void

5.5.1 Attributes

onstatechange of type EventHandler

This event handler, of event handler event type statechange, MUST be fired any time the RTCDtlsTransport state changes.

state of type RTCDtlsTransportState, readonly

The state attribute MUST return the state of the transport.

transport of type RTCIceTransport, readonly

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

5.5.2 Methods

getRemoteCertificates

Returns the certificate chain in use by the remote side, with each certificate encoded in binary Distinguished Encoding Rules (DER) [X690]. getRemoteCertificates() will return an empty list prior to selection of the remote certificate, which will be completed by the time RTCDtlsTransportState transitions to "connected".

No parameters.

Return type: sequence<ArrayBuffer>

5.6.1 Attributes

component of type RTCIceComponent, readonly

The component attribute MUST return the ICE component of the transport. When RTP/RTCP mux is used, a single RTCIceTransport transports both RTP and RTCP and component is set to "RTP".

gatheringState of type RTCIceGatheringState, readonly

The gathering state attribute MUST return the gathering state of the transport.

ongatheringstatechange of type EventHandler

This event handler, of event handler event type gatheringstatechange, MUST be fired any time the RTCIceTransportgathering state changes.

onselectedcandidatepairchange of type EventHandler

This event handler, of event handler event type selectedcandidatepairchange, MUST be fired any time the RTCIceTransport's selected candidate pair changes.

onstatechange of type EventHandler

This event handler, of event handler event type statechange, MUST be fired any time the RTCIceTransport state changes.

role of type RTCIceRole, readonly

The role attribute MUST return the ICE role of the transport.

state of type RTCIceConnectionState, readonly

The state attribute MUST return the state of the transport.

5.6.2 Methods

getLocalCandidates

Returns a sequence describing the local ICE candidates gathered for this RTCIceTransport and sent in onicecandidate

No parameters.

Return type: sequence<RTCIceCandidate>

getLocalParameters

Returns the local ICE parameters received by this RTCIceTransport via setLocalDescription(), or null if the parameters have not yet been received.

No parameters.

Return type: RTCIceParameters, nullable

getRemoteCandidates

Returns a sequence describing the remote ICE candidates received by this RTCIceTransport via addIceCandidate()

No parameters.

Return type: sequence<RTCIceCandidate>

getRemoteParameters

Returns the remote ICE parameters received by this RTCIceTransport via setRemoteDescription() or null if the parameters have not yet been received.

No parameters.

Return type: RTCIceParameters, nullable

getSelectedCandidatePair

Returns the selected candidate pair on which packets are sent, or null if there is no such pair.

No parameters.

Return type: RTCIceCandidatePair, nullable

5.6.3 Dictionary RTCIceParameters Members

password of type DOMString

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

usernameFragment of type DOMString

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

5.6.4 Dictionary RTCIceCandidatePair Members

local of type RTCIceCandidate

The local ICE candidate.

remote of type RTCIceCandidate

The remote ICE candidate.

5.7.1 Constructors

RTCTrackEvent

readonly attribute RTCRtpReceiver receiver

Parameter	Type	Nullable	Optional	Description
type	DOMString	✘	✘
eventInitDict	RTCTrackEventInit	✘	✘

5.7.2 Attributes

receiver of type RTCRtpReceiver, readonly

The receiver attribute represents the RTCRtpReceiver object associated with the event.

streams of type FrozenArray<MediaStream>, readonly

The streams attribute returns an array of MediaStream objects representing the MediaStreams that this event's track is a part of.

track of type MediaStreamTrack, readonly

The track attribute represents the MediaStreamTrack object that is associated with the RTCRtpReceiver identified by receiver.

transceiver of type RTCRtpTransceiver, readonly

The transceiver attribute represents the RTCRtpTransceiver object associated with the event.

5.7.3 Dictionary RTCTrackEventInit Members

receiver of type RTCRtpReceiver, required

The receiver attribute represents the RTCRtpReceiver object associated with the event.

streams of type sequence<MediaStream>, defaulting to []

The streams attribute returns an array of MediaStream objects representing the MediaStreams that this event's track is a part of.

track of type MediaStreamTrack, required

The track attribute represents the MediaStreamTrack object that is associated with the RTCRtpReceiver identified by receiver.

transceiver of type RTCRtpTransceiver, required

The transceiver attribute represents the RTCRtpTransceiver object associated with the event.

6.1.1 Attributes

ondatachannel of type EventHandler

The event type of this event handler is datachannel.

sctp of type RTCSctpTransport, readonly , nullable

The SCTP transport over which SCTP data is sent and received. If SCTP has not been negotiated, the value is null.

6.1.2 Methods

createDataChannel

Creates a new RTCDataChannel object with the given label. The RTCDataChannelInit dictionary can be used to configure properties of the underlying channel such as data reliability.

When the createDataChannel() method is invoked, the user agent MUST run the following steps.

1. If the RTCPeerConnection object's signaling state is closed, throw an InvalidStateError exception and abort these steps.

2. Let channel be a newly created RTCDataChannel object.

3. Initialize channel's label attribute to the value of the first argument.

4. If the second (dictionary) argument is present, set channel's ordered, maxPacketLifeTime, maxRetransmits, protocol, negotiated and id attributes to the values of their corresponding dictionary members (if present in the dictionary).

5. If negotiated is false and label is longer than 65535 bytes long, throw a TypeError.
6. If negotiated is false and protocol is longer than 65535 bytes long, throw a TypeError.

7. If both the maxPacketLifeTime and maxRetransmits attributes are set (not null), then throw a SyntaxError exception and abort these steps.

8. If an attribute, either maxPacketLifeTime or maxRetransmits, has been set to indicate unreliable mode, and that value exceeds the maximum value supported by the user agent, the value MUST be set to the user agents maximum value.

9. If id attribute is uninitialized (not set via the dictionary), initialize it to a value generated by the user agent, according to the WebRTC DataChannel Protocol specification, and skip to the next step. Otherwise, if the value of the id attribute is taken by an existing RTCDataChannel, throw a ResourceInUse exception and abort these steps.

10. Return channel and continue the following steps in the background.

11. Create channel's associated underlying data transport and configure it according to the relevant properties of channel.

12. If channel was the first RTCDataChannel created on this connection, mark the connection as needing negotiation.

Parameter	Type	Nullable	Optional	Description
label	DOMString	✘	✘
dataChannelDict	RTCDataChannelInit	✘	✔

Return type: RTCDataChannel

6.1.3 RTCSctpTransport Interface

The RTCSctpTransport interface allows an application access to information about the SCTP data channels tied to a particular SCTP association.

interface RTCSctpTransport {
    readonly        attribute RTCDtlsTransport transport;
    readonly        attribute unsigned long    maxMessageSize;
};

6.2.1 Attributes

binaryType of type DOMString

The binaryType attribute MUST, on getting, return the value to which it was last set. On setting, the user agent MUST set the IDL attribute to the new value. When a RTCDataChannel object is created, the binaryType attribute MUST be initialized to the string "blob".

This attribute controls how binary data is exposed to scripts. See the [WEBSOCKETS-API] for more information.

bufferedAmount of type unsigned long, readonly

The bufferedAmount attribute MUST return the number of bytes of application data (UTF-8 text and binary data) that have been queued using send() but that, as of the last time the event loop started executing a task, had not yet been transmitted to the network. (This thus includes any text sent during the execution of the current task, regardless of whether the user agent is able to transmit text asynchronously with script execution.) This does not include framing overhead incurred by the protocol, or buffering done by the operating system or network hardware. If the channel is closed, this attribute's value will only increase with each call to the send() method (the attribute does not reset to zero once the channel closes).

bufferedAmountLowThreshold of type unsigned long

The bufferedAmountLowThreshold attribute sets the threshold at which the bufferedAmount is considered to be low. When the bufferedAmount decreases from above this threshold to equal or below it, the bufferedamountlow event fires. The bufferedAmountLowThreshold is initially zero on each new RTCDataChannel, but the application may change its value at any time.

id of type unsigned short, readonly

The id attribute returns the id for this RTCDataChannel. The id was either assigned by the user agent at channel creation time or selected by the script. The attribute MUST return the value to which it was set when the RTCDataChannel was created.

label of type DOMString, readonly

The label attribute represents a label that can be used to distinguish this RTCDataChannel object from other RTCDataChannel objects. Scripts are allowed to create multiple RTCDataChannel objects with the same label. The attribute MUST return the value to which it was set when the RTCDataChannel object was created.

maxPacketLifeTime of type unsigned short, readonly , nullable

The maxPacketLifeTime attribute returns the length of the time window (in milliseconds) during which transmissions and retransmissions may occur in unreliable mode, or null if unset. The attribute MUST be initialized to null by default and MUST return the value to which it was set when the RTCDataChannel was created.

maxRetransmits of type unsigned short, readonly , nullable

The maxRetransmits attribute returns the maximum number of retransmissions that are attempted in unreliable mode, or null if unset. The attribute MUST be initialized to null by default and MUST return the value to which it was set when the RTCDataChannel was created.

negotiated of type boolean, readonly

The negotiated attribute returns true if this RTCDataChannel was negotiated by the application, or false otherwise. The attribute MUST be initialized to false by default and MUST return the value to which it was set when the RTCDataChannel was created.

onbufferedamountlow of type EventHandler

The event type of this event handler is bufferedamountlow.

onclose of type EventHandler

The event type of this event handler is close.

onerror of type EventHandler

The event type of this event handler is error.

onmessage of type EventHandler

The event type of this event handler is message.

onopen of type EventHandler

The event type of this event handler is open.

ordered of type boolean, readonly

The ordered attribute returns true if the RTCDataChannel is ordered, and false if other of order delivery is allowed. The attribute MUST be initialized to true by default and MUST return the value to which it was set when the RTCDataChannel was created.

protocol of type DOMString, readonly

The protocol attribute returns the name of the sub-protocol used with this RTCDataChannel if any, or the empty string otherwise. The attribute MUST be initialized to the empty string by default and MUST return the value to which it was set when the RTCDataChannel was created.

readyState of type RTCDataChannelState, readonly

The readyState attribute represents the state of the RTCDataChannel object. It MUST return the value to which the user agent last set it (as defined by the processing model algorithms).

6.2.2 Methods

close

Closes the RTCDataChannel. It may be called regardless of whether the RTCDataChannel object was created by this peer or the remote peer.

When the RTCDataChannel close() method is called, the user agent MUST run the following steps:

1. Let channel be the RTCDataChannel object which is about to be closed.

2. If channel's readyState is closing or closed, then abort these steps.

3. Set channel's readyState attribute to closing.

4. If the closing procedure has not started yet, start it.

No parameters.

Return type: void

send

Run the steps described by the send() algorithm with argument type string object.

Parameter	Type	Nullable	Optional	Description
data	USVString	✘	✘

Return type: void

send

Run the steps described by the send() algorithm with argument type Blob object.

Parameter	Type	Nullable	Optional	Description
data	Blob	✘	✘

Return type: void

send

Run the steps described by the send() algorithm with argument type ArrayBuffer object.

Parameter	Type	Nullable	Optional	Description
data	ArrayBuffer	✘	✘

Return type: void

send

Run the steps described by the send() algorithm with argument type ArrayBufferView object.

Parameter	Type	Nullable	Optional	Description
data	ArrayBufferView	✘	✘

Return type: void

6.2.3 Dictionary RTCDataChannelInit Members

id of type unsigned short

Overrides the default selection of id for this channel.

maxPacketLifeTime of type unsigned short

Limits the time during which the channel will transmit or retransmit data if not acknowledged. This value may be clamped if it exceeds the maximum value supported by the user agent.

maxRetransmits of type unsigned short

Limits the number of times a channel will retransmit data if not successfully delivered. This value may be clamped if it exceeds the maximum value supported by the user agent..

negotiated of type boolean, defaulting to false

The default value of false tells the user agent to announce the channel in-band and instruct the other peer to dispatch a corresponding RTCDataChannel object. If set to true, it is up to the application to negotiate the channel and create a RTCDataChannel object with the same id at the other peer.

ordered of type boolean, defaulting to true

If set to false, data is allowed to be delivered out of order. The default value of true, guarantees that data will be delivered in order.

protocol of type DOMString, defaulting to ""

Subprotocol name used for this channel.