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 developed by the Media Capture Task Force.

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 Editors and active contributors of WebRTC 1.0 intend to publish a Candidate Recommendation soon. Consequently, this is a Request for Comments by the WebRTC Working Group to seek wide review of this document.

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

This document was published by the Web Real-Time Communications Working Group as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-webrtc@w3.org (subscribe, archives). All comments are welcome.

Publication as an Editor's Draft 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 5 February 2004 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 September 2015 W3C Process Document.

1. Introduction

This section is non-normative.

There are a number of facets to 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 Media Capture Task Force. 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, SHALL, and SHOULD are to be interpreted as described in [RFC2119].

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-1], as this specification uses that specification and terminology.

3. Terminology

The EventHandler interface, representing a callback used for event handlers, and the ErrorEvent interface are defined in [HTML5].

The concepts queue a task, fire a simple event and networking task source are defined in [HTML5].

The terms event, event handlers and event handler event types are defined in [HTML5].

The terms MediaStream, MediaStreamTrack, and MediaStreamConstraints are defined in [GETUSERMEDIA].

The term Blob is defined in [FILEAPI].

The term media description is defined in [RFC4566].

4. Peer-to-peer connections

4.1 Introduction

An RTCPeerConnection instance allows to establish peer to peer communications. Communications are coordinated via a signaling channel which is provided by unspecified means, but generally by a script in the page via the server, e.g. using XMLHttpRequest [XMLHttpRequest] or Web Sockets [ WEBSOCKETS-API].

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. 

dictionary RTCConfiguration {
    sequence<RTCIceServer>   iceServers;
    RTCIceTransportPolicy    iceTransportPolicy = "all";
    RTCBundlePolicy          bundlePolicy = "balanced";
    RTCRtcpMuxPolicy         rtcpMuxPolicy = "require";
    DOMString                peerIdentity;
    sequence<RTCCertificate> certificates;
    unsigned short           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, defaulting to "all"

Indicates which candidates the ICE Agent is allowed to use.

bundlePolicy of type RTCBundlePolicy, defaulting to "balanced"

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

rtcpMuxPolicy of type RTCRtcpMuxPolicy, defaulting to "require"

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

peerIdentity of type DOMString

Sets the target peer identity for the RTCPeerConnection. The RTCPeerConnection will not establish a connection to a remote peer unless it can be successfully authenticated with the provided name.

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.

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 unsigned short, 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 

enum RTCIceCredentialType {
    "password",
    "token"
};
Enumeration description
password The credential is a long-term authentication password, as described in [RFC5389], Section 10.2.
token The credential is an access token, as described in [ TRAM-TURN-THIRD-PARTY-AUTHZ], Section 6.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.

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

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:

Example 1
[
     { "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 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. 

enum RTCIceTransportPolicy {
    "relay",
    "all"
};
Enumeration description
relay The ICE Agent MUST only use media relay candidates such as candidates passing through a TURN server. This can be used to reduce leakage of IP addresses in certain use cases.
all The ICE Agent MAY use any type of candidates when this value is specified. This will not include addresses that have been filtered by the browser.

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"
};
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 RtcpMuxPolicy affects what ICE candidates are gathered to support non-multiplexed RTCP.

enum RTCRtcpMuxPolicy {
    "negotiate",
    "require"
};
Enumeration description (non-normative)
negotiate Gather ICE candidates for both RTP and RTCP candidates. If the remote-endpoint is capable of multiplexing RTCP, multiplex RTCP on the RTP candidates. If it is not, use both the RTP and RTCP candidates separately.
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.

dictionary RTCOfferAnswerOptions {
    boolean voiceActivityDetection = true;
};
Dictionary RTCOfferAnswerOptions Members
voiceActivityDetection of type boolean, defaulting to true

Many codecs and systems are capable of detecting "silence" and changing their behavior in this case by doing things such as not transmitting any media. In many cases, such as when dealing with emergency calling or sounds other than spoken voice, it is desirable to be able to turn off this behavior. This option allows the application to provide information about whether it wishes this type of processing enabled or disabled. 

dictionary RTCOfferOptions : RTCOfferAnswerOptions {
    boolean iceRestart = false;
};
Dictionary RTCOfferOptions Members
iceRestart of type boolean, defaulting to false

When the value of this dictionary member is true, the generated description will have ICE credentials that are different from the current credentials (as visible in the localDescription attribute's SDP). Applying the generated description will restart ICE.

When the value of this dictionary member is false, and the localDescription attribute has valid ICE credentials, the generated description will have the same ICE credentials as the current value from the localDescription attribute.

dictionary RTCAnswerOptions : RTCOfferAnswerOptions {
};

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

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

  1. Let connection be a newly created RTCPeerConnection object.

  2. Initialize connection's ICE Agent.

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

  4. Let connection have an [[isClosed]] internal slot, initialized to false.

  5. Let connection have a [[needNegotiation]] internal slot, initialized to false.

  6. Let connection have an [[operations]] internal slot, representing an operations queue, initialized to an empty list.

  7. Set connection's signaling state to stable.

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

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

  10. Set connection's connection state to new.

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

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

  13. Store the configuration, including the certificates, in a [[ configuration]] internal slot.

  14. Return connection.

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

To enqueue an operation, run the following steps:

  1. Let connection be the current RTCPeerConnection object.

  2. If connection's [[isClosed]] slot is true, return a promise rejected with an InvalidStateError.

  3. Let operation be the operation to be enqueued.

  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's [[isClosed]] slot 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's [[isClosed]] slot 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]].

  8. Return p.

An RTCPeerConnection object has an aggregated connection state. Whenever the state of an RTCDtlsTransport or RTCIceTransport 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 a simple event named connectionstatechange at connection.

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's [[isClosed]] slot 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 a simple event named icegatheringstatechange at connection.

  6. If newState is completed, fire an event named icecandidate with null at connection.

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

  1. If connection's [[isClosed]] slot is true, abort these steps.

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

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

  4. Set connection's ice connection state to newState.

  5. Fire a simple event named iceconnectionstatechange at connection.

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

  1. Let p be a new promise.

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

    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 [[isClosed]] slot is true, then abort these steps.

      2. If elements of the SDP were modified, then reject p with an InvalidModificationError and abort these steps.

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

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

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

      6. For all other errors, for example if description cannot be applied at the media layer, 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 [[isClosed]] slot is true, then abort these steps.

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

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

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

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

      6. If description is of type "rollback", then run the following steps:

        1. If the mid value of an RTCRtpTransceiver was set to a non-null value by the RTCSessionDescription that is being rolled back, set the mid value of that transceiver to null, as described by [JSEP] (section 4.1.7.2.).

        2. If an RTCRtpTransceiver was created by applying the RTCSessionDescription that is being rolled back, and a track has not been attached to it via addTrack, remove that transceiver from connection's set of transceivers, as described by [JSEP] (section 4.1.7.2.).

      7. If connection's signaling state is now stable, update the negotiation-needed flag. If connection's [[ needNegotiation]] slot was true both before and after this update, queue a task to check connection's [[needNegotiation]] slot and, if still true, fire a simple event named negotiationneeded at connection.

      8. Resolve p with undefined.

  3. 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 API section, which adds the APIs to send and receive MediaStreamTrack objects.

[Constructor(optional RTCConfiguration configuration)]
interface RTCPeerConnection : EventTarget {
    Promise<RTCSessionDescriptionInit> createOffer(optional RTCOfferOptions options);
    Promise<RTCSessionDescriptionInit> 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;
                    attribute EventHandler              onfingerprintfailure;
};
Constructors
RTCPeerConnection
See the RTCPeerConnection constructor algorithm.
Parameter Type Nullable Optional Description
configuration RTCConfiguration ✘ ✔
Attributes
localDescription of type RTCSessionDescription, readonly , nullable

The localDescription attribute MUST return pendingLocalDescription if it is not null and otherwise it MUST return currentLocalDescription .

currentLocalDescription of type RTCSessionDescription, readonly , nullable

The currentLocalDescription attribute represents the local RTCSessionDescription 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.

The currentLocalDescription attribute MUST return the last value that algorithms in this specification set it to, complete with any local candidates that have been generated by the ICE Agent since the offer or answer was created. Prior to being set, it returns null.

pendingLocalDescription of type RTCSessionDescription, readonly , nullable

The pendingLocalDescription attribute represents a local RTCSessionDescription 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. This attribute is updated by setLocalDescription .

The pendingLocalDescription attribute MUST return the last value that algorithms in this specification set it to, complete with any local candidates that have been generated by the ICE Agent since the offer or answer was created. Prior to being set, it returns null.

remoteDescription of type RTCSessionDescription, readonly , nullable

The remoteDescription attribute MUST return pendingRemoteDescription if it is not null and otherwise it MUST return currentRemoteDescription .

currentRemoteDescription of type RTCSessionDescription, readonly , nullable

The currentRemoteDescription attribute represents the last remote RTCSessionDescription 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.

The currentRemoteDescription attribute MUST return the value that algorithms in this specification set it to, complete with any remote candidates that have been supplied via addIceCandidate() since the offer or answer was created. Prior to being set, it returns null.

pendingRemoteDescription of type RTCSessionDescription, readonly , nullable

The pendingRemoteDescription attribute represents a remote RTCSessionDescription 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. This attribute is updated by setLocalDescription .

The pendingRemoteDescription attribute MUST return the value that algorithms in this specification set it to, completed with any remote candidates that have been supplied via addIceCandidate() since the offer or answer was created. Prior to being set, it returns 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.14.). Prior to the completion of setRemoteDescription, this value is null.

defaultIceServers of type FrozenArray<RTCIceServer>, static readonly

The defaultIceServers attribute provides a list of ICE servers that are configured into the browser. A browser might be configured to use local or private STUN or TURN servers. This method allows an application to learn about these servers and optionally use them.

This list is likely to be persisent and is the same across origins. It thus increases the fingerprinting surface of the browser. In privacy-sensitive contexts, browsers can consider mitigations such as only providing this data to "trusted" origins (or not providing it at all.)(This is a fingerprinting vector.)

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 .
onfingerprintfailure of type EventHandler
The event type of this event handler is fingerprintfailure .
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 options supported by this implementation, and any candidates that have been gathered by the ICE Agent. The options parameter may be supplied to provide additional control over the offer generated.

As an offer, the generated SDP will contain the full set of capabilities supported by the session (as opposed to an answer, which will include only a specific negotiated subset to use); for each SDP line, the generation of the SDP MUST follow the appropriate process for generating an offer. 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.

Session descriptions generated by createOffer MUST be immediately usable by setLocalDescription without causing an error as long as setLocalDescription is called reasonably soon. 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. Calling this method is needed to generate the ICE username fragment and password.

The value for certificates in the RTCConfiguration for the RTCPeerConnection is used to produce a set of certificate fingerprints. These certificate fingerprints are used in the construction of SDP and as input to requests for identity assertions.

If the RTCPeerConnection is configured to generate Identity assertions by calling setIdentityProvider , then the session description SHALL contain an appropriate assertion.

The SDP generation process 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's [[isClosed]] slot is true, return a promise rejected with an InvalidStateError.

  3. If connection is configured with an identity provider, and an identity assertion has not yet been generated using said identity provider, then begin the identity assertion request process if it has not already begun.

  4. Return the result of enqueuing the following steps:

    1. Let p be a new promise.

    2. In parallel, begin the steps to create an offer, given p.

    3. Return p.

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

  1. If the need for an identity assertion was identified when createOffer was invoked, wait for the identity assertion request process to complete.

  2. If the identity provider was unable to produce an identity assertion, reject p with a DOMException object whose name attribute has the value NotReadableError, and abort these steps.

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

  4. Inspect the system state to determine the currently available resources as necessary for generating the offer, as described in [JSEP] (section 4.1.5.).

  5. If this inspection failed for any reason, reject p with a DOMException object whose name attribute has the value OperationError, and abort these steps.

  6. Queue a task that runs the final steps to create an offer, given p.

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

  1. If connection's [[isClosed]] slot is true, then abort these steps.

  2. If connection was modified in such a way that additional inspection of the system state is necessary, then in parallel begin the steps to create an offer again, given 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 steps to create an offer in parallel, a video RTCRtpTransceiver was added, requiring additional inspection of video system resources.

  3. Given the information that was obtained from previous inspection and the current state of connection and its RTCRtpTransceiver s, generate an SDP offer, sdpString, as described in [JSEP] (section 5.2.).

  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. Resolve p with offer.

Parameter Type Nullable Optional Description
options RTCOfferOptions ✘ ✔
Return type: Promise<RTCSessionDescriptionInit>
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 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.

As an answer, the generated SDP will contain a specific 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.

Session descriptions generated by createAnswer MUST be immediately usable by setLocalDescription without causing an error as long as setLocalDescription is called reasonably soon. 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. Calling this method is needed to generate the ICE username fragment and password.

An answer can be marked as provisional, as described in [JSEP] (section 4.1.7.1.), by setting the type to pranswer.

If the RTCPeerConnection is configured to generate Identity assertions by calling setIdentityProvider , then the session description SHALL contain an appropriate assertion.

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's [[isClosed]] slot is true, return a promise rejected with an InvalidStateError.

  3. If connection is configured with an identity provider, and an identity assertion has not yet been generated using said identity provider, then begin the identity assertion request process if it has not already begun.

  4. Return the result of enqueuing the following steps:

    1. If connection's remoteDescription is null return a promise rejected with an InvalidStateError.

    2. Let p be a new promise.

    3. In parallel, begin the steps to create an answer, given p.

    4. Return p.

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

  1. If the need for an identity assertion was identified when createAnswer was invoked, wait for the identity assertion request process to complete.

  2. If the identity provider was unable to produce an identity assertion, reject p with a DOMException object whose name attribute has the value NotReadableError, and abort these steps.

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

  4. Inspect the system state to determine the currently available resources as necessary for generating the answer, as described in [JSEP] (section 4.1.6.).

  5. If this inspection failed for any reason, reject p with a DOMException object whose name attribute has the value OperationError, and abort these steps.

  6. 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's [[isClosed]] slot is true, then abort these steps.

  2. If connection was modified in such a way that additional inspection of the system state is necessary, then in parallel begin the steps to create an answer again, given 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 steps to create an answer in parallel, 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 RTCRtpTransceiver s, generate an SDP answer, sdpString, as described in [JSEP] (section 5.3.).

  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. Resolve p with answer.

Parameter Type Nullable Optional Description
options RTCAnswerOptions ✘ ✔
Return type: Promise<RTCSessionDescriptionInit>
setLocalDescription

The setLocalDescription method instructs the RTCPeerConnection to apply the supplied RTCSessionDescriptionInit 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.

When the method is invoked, the User Agent MUST return the result of setting the RTCSessionDescription indicated by the method's first argument.

Parameter Type Nullable Optional Description
description RTCSessionDescriptionInit ✘ ✘
Return type: Promise<void>
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 return the result of setting the RTCSessionDescription indicated by the method's first argument.

In addition, a remote description is processed to determine and verify the identity of the peer.

If an a=identity attribute is present in the session description, the browser validates the identity assertion..

If the "peerIdentity" configuration is applied to the RTCPeerConnection , this establishes a target peer identity of the provided value. Alternatively, if the RTCPeerConnection has previously authenticated the identity of the peer (that is, there is a current value for peerIdentity ), then this also establishes a target peer identity.

The target peer identity cannot be changed once set. Once set, if a different value is provided, the user agent MUST reject the returned promise with InvalidModificationError and abort this operation. The RTCPeerConnection MUST be closed if the validated peer identity does not match the target peer identity.

If there is no target peer identity, then setRemoteDescription does not await the completion of identity validation.

Parameter Type Nullable Optional Description
description RTCSessionDescriptionInit ✘ ✘
Return type: Promise<void>
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 candidate . The only members of the argument used by this method are candidate , sdpMid , sdpMLineIndex , and ufrag ; 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 is missing values for both sdpMid and sdpMLineIndex, return a promise rejected with a TypeError.

  4. Return the result of enqueuing the following steps:

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

    2. Let p be a new promise.

    3. 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 , reject p with a DOMException object whose name attribute has the value OperationError and stop processing any more steps.

    4. 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 , reject p with a DOMException object whose name attribute has the value OperationError and stop processing any more steps.

    5. If candidate.ufrag is not equal to any ufrag present in the corresponding media description of an applied remote description, reject p with an OperationError and abort these steps.

    6. In parallel, add the ICE candidate candidate as described in [JSEP] (section 4.1.16.). If candidate.candidate is an empty string, process candidate as an end-of-candidates indication for the corresponding media description and ICE candidate generation.

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

        1. If connection's [[ isClosed]] slot is true, then abort these steps.

        2. Reject p with a DOMException object whose name attribute has the value OperationError and abort these steps.

      2. If candidate is applied successfully, the User Agent MUST queue a task that runs the following steps:

        1. If connection's [[ isClosed]] slot is true, then abort these steps.

        2. Let remoteDescription be connection's pendingRemoteDescription if not null, otherwise connection's currentRemoteDescription .

        3. Add candidate to remoteDescription.

        4. Resolve p with undefined.

    7. Return p.

Parameter Type Nullable Optional Description
candidate (RTCIceCandidateInit or RTCIceCandidate) ✔ ✘
Return type: Promise<void>
getConfiguration

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

No parameters.
Return type: RTCConfiguration
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's [[isClosed]] slot is true, throw an InvalidStateError exception and abort these steps.

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.peerIdentity is set and its value differs from the target peer identity, throw an InvalidModificationError.
  4. If configuration.certificates is set and the set of certificates differs from the ones used when connection was constructed, throw an InvalidModificationError.
  5. If configuration.bundlePolicy is set and its value differs from the connection's bundle policy, throw an InvalidModificationError.
  6. If configuration.rtcpMuxPolicy is set and its value differs from the connection's rtcpMux policy, 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.15.), 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.15.).

  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. If server.urls is a string, let server.urls be a list consisting of just that string.

    3. For each url in server.urls parse url and obtain scheme name. If the scheme name is not implemented by the browser, or if parsing based on the syntax defined in [ RFC7064] and [RFC7065] fails, throw a SyntaxError and abort these steps.

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

    5. Append server to validatedServers.

    Let validatedServers be the ICE Agent's ICE servers list.

    As defined in [JSEP] (section 4.1.15.), 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.

  11. Store the configuration in the [[ configuration]] internal slot.

Parameter Type Nullable Optional Description
configuration RTCConfiguration ✘ ✘
Return type: void
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. If connection's [[isClosed]] slot is true, abort these steps.

  3. Destroy connection's ICE Agent, abruptly ending any active ICE processing and any active streaming, and releasing any relevant resources (e.g. TURN permissions).

  4. Set the state of each of connection's RTCIceTransport s to closed .

  5. Let senders be the result of executing the CollectSenders algorithm. For every RTCRtpSender sender in senders, set sender.transport.state and sender.transport.transport.state to "closed". If sender.rtcpTransport is set, set sender.rtcpTransport.state and sender.rtcpTransport.transport.state to "closed".

  6. Let receivers be the result of executing the CollectReceivers algorithm. For every RTCRtpReceiver receiver in receivers, set receiver.transport.state and receiver.transport.transport.state to "closed". If receiver.rtcpTransport is set, set receiver.rtcpTransport.state and receiver.rtcpTransport.transport.state to "closed".

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

    2. Let sender be transceiver.sender.

    3. Let receiver be transceiver.receiver.

    4. Stop sending media with sender.

    5. Stop receiving media with receiver.

    6. Set receiver.track.readyState to ended.

    7. Set transceiver.stopped to true.

  7. Set connection's [[isClosed]] slot to true.

No parameters.
Return type: void

4.3.3 Legacy Interface Extensions

Note
These methods are kept on RTCPeerConnection for legacy purposes. 
partial interface RTCPeerConnection {
    Promise<void> createOffer(RTCSessionDescriptionCallback successCallback,
                              RTCPeerConnectionErrorCallback failureCallback,
                              optional RTCOfferOptions options);
    Promise<void> setLocalDescription(RTCSessionDescriptionInit 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 or RTCIceCandidate) candidate,
                                  VoidFunction successCallback,
                                  RTCPeerConnectionErrorCallback failureCallback);
    Promise<void> getStats(MediaStreamTrack? selector,
                           RTCStatsCallback successCallback,
                           RTCPeerConnectionErrorCallback failureCallback);
};
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.

Parameter Type Nullable Optional Description
successCallback RTCSessionDescriptionCallback ✘ ✘
failureCallback RTCPeerConnectionErrorCallback ✘ ✘
options RTCOfferOptions ✘ ✔
Return type: Promise<void>
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.

Parameter Type Nullable Optional Description
description RTCSessionDescriptionInit ✘ ✘
successCallback VoidFunction ✘ ✘
failureCallback RTCPeerConnectionErrorCallback ✘ ✘
Return type: Promise<void>
createAnswer

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.

Parameter Type Nullable Optional Description
successCallback RTCSessionDescriptionCallback ✘ ✘
failureCallback RTCPeerConnectionErrorCallback ✘ ✘
Return type: Promise<void>
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.

Parameter Type Nullable Optional Description
description RTCSessionDescriptionInit ✘ ✘
successCallback VoidFunction ✘ ✘
failureCallback RTCPeerConnectionErrorCallback ✘ ✘
Return type: Promise<void>
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.

Parameter Type Nullable Optional Description
candidate (RTCIceCandidateInit or RTCIceCandidate) ✘ ✘
successCallback VoidFunction ✘ ✘
failureCallback RTCPeerConnectionErrorCallback ✘ ✘
Return type: Promise<void>
getStats

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

  1. Let selector 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 getStats() method with selector as the sole argument, and let p be the resulting promise.

  5. Upon fulfillment of p with value report, invoke successCallback with report 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.

Parameter Type Nullable Optional Description
selector MediaStreamTrack ✔ ✘
successCallback RTCStatsCallback ✘ ✘
failureCallback RTCPeerConnectionErrorCallback ✘ ✘
Return type: Promise<void>

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 [[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 a RTCPeerConnection have a strong reference to the RTCPeerConnection object.

4.4 State Definitions

4.4.1 RTCSignalingState Enum 

enum RTCSignalingState {
    "stable",
    "have-local-offer",
    "have-remote-offer",
    "have-local-pranswer",
    "have-remote-pranswer"
};
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.
signalling state transition diagram
Fig. 1 Non-normative signalling state transitions diagram

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
Callee transition:
  • new RTCPeerConnection(): stable
  • setRemote(offer): have-remote-offer
  • setLocal(pranswer): have-local-pranswer
  • setLocal(answer): stable

4.4.2 RTCIceGatheringState Enum 

enum RTCIceGatheringState {
    "new",
    "gathering",
    "complete"
};
Enumeration description
new Any of the RTCIceTransport s 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 RTCIceTransport s are in the gathering state.
complete At least one RTCIceTransport exists, and all RTCIceTransport s are in the completed gathering state.

4.4.3 RTCPeerConnectionState Enum 

enum RTCPeerConnectionState {
    "new",
    "connecting",
    "connected",
    "disconnected",
    "failed",
    "closed"
};
Enumeration description
new Any of the RTCIceTransport s or RTCDtlsTransport s are in the new state and none of the transports are in the connecting, checking, failed or disconnected state, or all transports are in the closed state.
connecting Any of the RTCIceTransport s or RTCDtlsTransport s are in the connecting or checking state and none of them is in the failed state.
connected All RTCIceTransport s and RTCDtlsTransport s are in the connected, completed or closed state and at least of them is in the connected or completed state.
disconnected Any of the RTCIceTransport s or RTCDtlsTransport s are in the disconnected state and none of them are in the failed or connecting or checking state.
failed Any of the RTCIceTransport s or RTCDtlsTransport s are in a failed state.
closed The RTCPeerConnection object's [[ isClosed]] slot is true.

4.4.4 RTCIceConnectionState Enum 

enum RTCIceConnectionState {
    "new",
    "checking",
    "connected",
    "completed",
    "failed",
    "disconnected",
    "closed"
};
Enumeration description
new Any of the RTCIceTransport s are in the new state and none of them are in the checking, failed or disconnected state, or all RTCIceTransport s are in the closed state.
checking Any of the RTCIceTransport s are in the checking state and none of them are in the failed or disconnected state.
connected All RTCIceTransport s are in the connected, completed or closed state and at least one of them is in the connected state.
completed All RTCIceTransport s are in the completed or closed state and at least one of them is in the completed state.
failed Any of the RTCIceTransport s are in the failed state.
disconnected Any of the RTCIceTransport s are in the disconnected state and none of them are in the failed state.
closed The RTCPeerConnection object's [[ isClosed]] slot is true.

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.5 Callback Definitions

These callbacks are only used on the legacy APIs.

4.5.1 RTCPeerConnectionErrorCallback 

callback RTCPeerConnectionErrorCallback = void (DOMException error);
Callback RTCPeerConnectionErrorCallback Parameters
error of type DOMException
An error object encapsulating information about what went wrong.

4.5.2 RTCSessionDescriptionCallback 

callback RTCSessionDescriptionCallback = void (RTCSessionDescriptionInit description);
Callback RTCSessionDescriptionCallback Parameters
description of type RTCSessionDescriptionInit
The object containing the SDP [SDP].

4.5.3 RTCStatsCallback 

callback RTCStatsCallback = void (RTCStatsReport report);
Callback RTCStatsCallback Parameters
report of type RTCStatsReport

A RTCStatsReport representing the gathered stats.

4.6 Error Handling

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 Session Description Model

4.7.1 RTCSdpType

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

enum 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 and answer 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.

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.

[Constructor(RTCSessionDescriptionInit descriptionInitDict)]
interface RTCSessionDescription {
    readonly attribute RTCSdpType type;
    readonly attribute DOMString  sdp;
    serializer = {attribute};
};
Constructors
RTCSessionDescription
The RTCSessionDescription() constructor takes a dictionary argument, descriptionInitDict, whose content is used to initialize the new RTCSessionDescription object. This constructor is deprecated; it exists for legacy compatibility reasons only.
Parameter Type Nullable Optional Description
descriptionInitDict RTCSessionDescriptionInit ✘ ✘
Attributes
type of type RTCSdpType, readonly
The type of this RTCSessionDescription.
sdp of type DOMString, readonly
The string representation of the SDP [SDP].
Serializer

Instances of this interface are serialized as a map with entries for each of the serializable attributes.

dictionary RTCSessionDescriptionInit {
    required RTCSdpType type;
             DOMString  sdp = "";
};
Dictionary RTCSessionDescriptionInit Members
type of type RTCSdpType, required
DOMString sdp
sdp of type DOMString
The string representation of the SDP [SDP]; if type is rollback, this member is unused.

4.8 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 [[needNegotiation]] internal slot.

4.8.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.8.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 RTCRtpTransceiver s and RTCDataChannel s 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.8.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 queue a task to update the negotiation-needed flag.

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

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

  2. If the result of checking if negotiation is needed is "false", clear the negotiation-needed flag by setting connection's [[ needNegotiation]] slot to false, and abort these steps.

  3. If connection's [[needNegotiation]] slot is already true, abort these steps.

  4. Set connection's [[needNegotiation]] slot to true.

  5. Queue a task to check connection's [[ needNegotiation]] slot and, if still true, fire a simple event named negotiationneeded at connection.

    Note

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

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

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

  • If connection has created any RTCDataChannel s, and no m= section has been negotiated yet for data, return "true".

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

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

4.9 Interfaces for Connectivity Establishment

4.9.1 RTCIceCandidate Interface

This interface describes an ICE candidate.

[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;
    readonly attribute DOMString               ufrag;
    serializer = {candidate, sdpMid, sdpMLineIndex, ufrag};
};
Constructors
RTCIceCandidate
The RTCIceCandidate() constructor takes a dictionary argument, candidateInitDict, whose content is used to initialize the new RTCIceCandidate object. When run, if both the sdpMid and sdpMLineIndex dictionary members are null, throw a TypeError.
Parameter Type Nullable Optional Description
candidateInitDict RTCIceCandidateInit ✘ ✘
Attributes
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, candidate is an empty string.
sdpMid of type DOMString, readonly , nullable
If not null, this contains the identifier of the "media stream identification" as defined in [RFC5888] for the media component this candidate is associated with.
sdpMLineIndex of type unsigned short, readonly , nullable
If not null, this indicates the index (starting at zero) of the media description in the SDP this candidate is associated with.
foundation of type DOMString, readonly, nullable
A unique identifier that allows ICE to correlate candidates that appear on multiple RTCIceTransport s.
priority of type unsigned long, readonly, nullable
The assigned priority of the candidate.
ip of type DOMString, readonly, nullable

The IP address of the candidate.

Note

The IP 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 IP 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 IP 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 IP 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 IP addresses exposed to the application itself, browsers can offer their users different policies regarding sharing local IP addresses, as defined in [ RTCWEB-IP-HANDLING].

protocol of type RTCIceProtocol, readonly, nullable
The protocol of the candidate (udp/tcp).
port of type unsigned short, readonly, nullable
The port of the candidate.
type of type RTCIceCandidateType, readonly, nullable
The type of the candidate.
tcpType of type RTCIceTcpCandidateType, readonly, nullable
If protocol is tcp, tcpType represents the type of TCP candidate. Otherwise, tcpType is null.
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.
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.
ufrag of type DOMString, readonly
This carries the ufrag as defined in section 15.4 of [ICE].
Serializer

Instances of this interface are serialized as a map with entries for the following attributes: candidate, sdpMid, sdpMLineIndex, ufrag.

dictionary RTCIceCandidateInit {
             DOMString       candidate = "";
             DOMString?      sdpMid = null;
             unsigned short? sdpMLineIndex = null;
    required DOMString       ufrag;
};
Dictionary RTCIceCandidateInit Members
candidate of type DOMString, defaulting to ""
sdpMid of type DOMString, nullable, defaulting to null
sdpMLineIndex of type unsigned short, nullable, defaulting to null
ufrag of type DOMString
4.9.1.1 RTCIceProtocol Enum

The RTCIceProtocol represents the protocol of the ICE candidate. 

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

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

enum 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.
4.9.1.3 RTCIceCandidateType Enum

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

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

[Constructor(DOMString type, optional RTCPeerConnectionIceEventInit eventInitDict)]
interface RTCPeerConnectionIceEvent : Event {
    readonly attribute RTCIceCandidate? candidate;
    readonly attribute DOMString?       url;
};
Constructors
RTCPeerConnectionIceEvent
Parameter Type Nullable Optional Description
type DOMString ✘ ✘
eventInitDict RTCPeerConnectionIceEventInit ✘ ✘
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.

dictionary 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

4.9.3 RTCPeerConnectionIceErrorEvent

The icecandidateerror event of the RTCPeerConnection uses the RTCPeerConnectionIceErrorEvent interface.

[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;
};
Constructors
RTCPeerConnectionIceErrorEvent
readonly attribute DOMString hostCandidate
Parameter Type Nullable Optional Description
type DOMString ✘ ✘
eventInitDict RTCPeerConnectionIceErrorEventInit ✘ ✘
Attributes
hostCandidate of type DOMString, readonly

The hostCandidate attribute is the local IP address and port 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 use of multiple interfaces has been prohibited for privacy reasons, this attribute will be set to 0.0.0.0:0 or [::]:0, as appropriate.

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.

dictionary RTCPeerConnectionIceErrorEventInit : EventInit {
    DOMString      hostCandidate;
    DOMString      url;
    unsigned short errorCode;
    USVString      statusText;
};
Dictionary RTCPeerConnectionIceErrorEventInit Members
hostCandidate of type DOMString
DOMString url
url of type DOMString
unsigned short errorCode
errorCode of type unsigned short
USVString statusText
statusText of type USVString

4.10 Priority and QoS Model

Many applications have multiple media flows of the same data type and often some of the flows are more important than others. WebRTC uses the priority and Quality of Service (QoS) framework described in [ RTCWEB-TRANSPORT] and [TSVWG-RTCWEB-QOS] to provide priority and DSCP marking for packets that will help provide QoS in some networking environments. The priority setting can be used to indicate the relative priority of various flows. The priority API allows the JavaScript applications to tell the browser whether a particular media flow is high, medium, low or of very low importance to the application by setting the priority property of RTCRtpEncodingParameters objects to one of the following values.

4.10.1 RTCPriorityType Enum 

enum RTCPriorityType {
    "very-low",
    "low",
    "medium",
    "high"
};
Enumeration description
very-low See [RTCWEB-TRANSPORT], Section 4.
low See [RTCWEB-TRANSPORT], Section 4.
medium See [RTCWEB-TRANSPORT], Section 4.
high See [RTCWEB-TRANSPORT], Section 4.

Applications that use this API should be aware that often better overall user experience is obtained by lowering the priority of things that are not as important rather than raising the priority of the things that are.

4.11 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 on the connection and 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.

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

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.

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.1 Dictionary RTCCertificateExpiration

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

dictionary RTCCertificateExpiration {
    [EnforceRange]
    DOMTimeStamp expires;
};
expires

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.

When generateCertificate is called with an object argument, the user agent attempts to convert the object into a RTCCertificateExpiration . If this is unsuccessful, immediately return a promise that is rejected with a TypeError and abort processing.

A user agent generates a certificate that has an expiration date set to the current time plus the value of the expires attribute. The expires attribute of the returned RTCCertificate is set to the expiration time of the certificate. A user agent MAY choose to limit the value of the expires attribute.

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;
    readonly attribute FrozenArray<RTCDtlsFingerprint> fingerprints;
    AlgorithmIdentifier getAlgorithm();
};
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.

fingerprints of type FrozenArray<RTCDtlsFingerprint>, readonly

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

Methods
getAlgorithm

Returns the value of keygenAlgorithm passed in the call to generateCertificate().

No parameters.
Return type: AlgorithmIdentifier

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. 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 a RTCPeerConnection, result in signaling; when this signaling is forwarded to a remote peer, it causes corresponding tracks to be created on the remote side.

The actual encoding and transmission of MediaStreamTracks is managed through objects called RTCRtpSender s. Similarly, the reception and decoding of MediaStreamTracks is managed through objects called RTCRtpReceiver s. Each track to be sent is associated with exactly one RTCRtpSender , 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.

RTCRtpSender s are created when the application attaches a MediaStreamTrack to a RTCPeerConnection , via the addTrack method. RTCRtpReceiver s, on the other hand, are created when remote signaling indicates new tracks are available, and each new MediaStreamTrack and its associated RTCRtpReceiver are surfaced to the application via the ontrack event. Both RTCRtpSender and RTCRtpReceiver objects are created by the addTransceiver method.

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

5.1 RTCPeerConnection Interface Extensions

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

partial 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 are currently attached to this RTCPeerConnection object.

The getSenders method 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 senderset be a new empty set.
  3. For each transceiver in transceivers,
    1. Let sender be transceiver.sender.
    2. Add sender to senderset.
  4. Let senders be a new sequence consisting of all the RTCRtpSender objects in senderset. The conversion from the senders set to the sequence is user agent defined and the order does not have to be stable between calls.
  5. Return senders.
No parameters.
Return type: sequence<RTCRtpSender>
getReceivers

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

The getReceivers method MUST return the result of executing the CollectReceivers algorithm.

We define the CollectReceivers algorithm as follows:

  1. Let transceivers be the result of executing the CollectTransceivers algorithm.
  2. Let receiverset be a new empty set.
  3. For each transceiver in transceivers,
    1. Let receiver be transceiver.receiver.
    2. Add receiver to receiverset.
  4. Let receivers be a new sequence consisting of all the RTCRtpReceiver objects in receiverset. The conversion from the receivers set to the sequence is user agent defined and the order does not have to be stable between calls.
  5. Return receivers.
No parameters.
Return type: sequence<RTCRtpReceiver>
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 that represents a snapshot of all the RTCRtpTransceiver objects in this RTCPeerConnection object's set of transceivers. The conversion from the transceiver set to the sequence is user agent defined and the order does not have to be stable between calls.
  2. Return transceivers.
No parameters.
Return type: sequence<RTCRtpTransceiver>
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 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.

  4. If connection's [[isClosed]] slot is true, throw an InvalidStateError exception and abort these steps.

  5. Let senders be the result of executing the CollectSenders algorithm. If an RTCRtpSender for track already exists in senders, throw an InvalidAccessError exception and abort these steps.

  6. 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 track added, 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:

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

    1. Set sender.track to track.

    2. Set sender's [[associated MediaStreams]] to streams.

    3. Enable sending direction on the RTCRtpTransceiver associated with sender.

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

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

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

    3. Create an RTCRtpTransceiver with sender and receiver and let transceiver be the result.

    4. Add transceiver to connection's set of transceivers

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

  10. Update the negotiation-needed flag for connection.

  11. Return sender.

Parameter Type Nullable Optional Description
track MediaStreamTrack ✘ ✘
streams MediaStream ✘ ✘
Return type: RTCRtpSender
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, 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 sender be the argument to removeTrack.

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

  3. If connection's [[isClosed]] slot is true, throw an InvalidStateError exception and abort these steps.

  4. If sender was not created by connection , throw an InvalidAccessError exception and abort these steps.

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

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

  7. Set sender.track to null.

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

  9. If transceiver.currentDirection is recvonly or inactive, then abort these steps.

  10. If transceiver.currentDirection is sendrecv set transceiver.direction to recvonly.

  11. If transceiver.currentDirection is sendonly set transceiver.direction to inactive.

  12. Update the negotiation-needed flag for connection.

Parameter Type Nullable Optional Description
sender RTCRtpSender ✘ ✘
Return type: void
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.).

When this method is invoked, the User Agent MUST run the following steps:

  1. If the dictionary argument is present, and it has a streams member, let streams be that list of MediaStream objects, or an empty list otherwise.

  2. If the dictionary argument is present, and it has a sendEncodings member, let sendEncodings be that list of RTCRtpEncodingParameters objects, or an empty list otherwise.

  3. 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 and abort these, and all further steps.

    2. Let track be null.

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

  5. Create an RTCRtpSender with track, 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.

    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.

  6. Create an RTCRtpReceiver with kind and let receiver be the result. This specification does not define how to configure createOffer to receive multiple RTP encodings. However when setRemoteDescription is called with a corresponding remote description that is able to send multiple RTP encodings as defined in [JSEP], the RTCRtpReceiver may receive multiple RTP encodings and the parameters retrieved via the transceiver's receiver.getParameters() will reflect the encodings negotiated.

  7. Create an RTCRtpTransceiver with sender and receiver and let transceiver be the result.

  8. Add transceiver to connection's set of transceivers

  9. Update the negotiation-needed flag for connection.

  10. Return transceiver.

Parameter Type Nullable Optional Description
trackOrKind (MediaStreamTrack or DOMString) ✘ ✘
init RTCRtpTransceiverInit ✘ ✔
Return type: RTCRtpTransceiver 
dictionary 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 ontrack 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. 

enum RTCRtpTransceiverDirection {
    "sendrecv",
    "sendonly",
    "recvonly",
    "inactive"
};
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.

5.1.1 Processing Remote MediaStreamTracks

An application can reject incoming MediaStreamTrack objects by calling RTCRtpTransceiver.stop().

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

  1. Let connection be the RTCPeerConnection expecting this media.

  2. If connection's [[isClosed]] slot is true, 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. The source of track is a remote source provided by connection.

    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 [[isClosed]] slot is true, abort these steps.

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

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 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. Set sender.track to track.

  3. Let sender have an [[associated MediaStreams]] internal slot, representing a list of MediaStream objects that the MediaStreamTrack object of this sender is associated with.

  4. Set sender's [[associated MediaStreams]] slot to streams.

  5. Let sender have a [[send encodings]] internal slot, representing a list of RTCRtpEncodingParameters objects, initialized to an empty list.

  6. If sendEncodings is given as input to this algorithm, set the [[send encodings]] slot to sendEncodings.

  7. Return sender.

interface RTCRtpSender {
    readonly attribute MediaStreamTrack? track;
    readonly attribute RTCDtlsTransport? transport;
    readonly attribute RTCDtlsTransport? rtcpTransport;
    static RTCRtpCapabilities getCapabilities(DOMString kind);
    Promise<void>      setParameters(optional RTCRtpParameters parameters);
    RTCRtpParameters   getParameters();
    Promise<void>      replaceTrack(MediaStreamTrack withTrack);
};

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 track.muted is set to true, the RTCRtpSender sends silence (audio) or a black frame (video). If track is set to null then the RTCRtpSender does not send.

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.

rtcpTransport of type RTCDtlsTransport, readonly , nullable

The rtcpTransport attribute is the transport over which RTCP is sent and received. Prior to construction of the RTCDtlsTransport object, the rtcpTransport attribute will be null. When RTCP mux is used (or bundling, which mandates RTCP mux), rtcpTransport will be null, and both RTP and RTCP traffic will flow over the transport described by transport.

Methods

getCapabilities, static

The RTCRtpSender.getCapabilities method returns the most optimist view on 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.(This is a fingerprinting vector.)

Parameter Type Nullable Optional Description
kind DOMString ✘ ✘
Return type: RTCRtpCapabilities
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 setParameters is invoked.
  2. Let transceiver be the RTCRtpTransceiver object associated with sender.
  3. Let N be the value of sender.getParameters().encodings.length.
  4. Let p be a new promise.
  5. Return p, performing the next steps in parallel.
  6. If transceiver.stopped is true, abort these steps and return a promise rejected with InvalidStateError.
  7. If parameters.encodings.length is different from N, or 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 sender.getParameters(), abort these steps and return a promise rejected with InvalidModificationError. Note that this also applies to transactionId.
  8. If the scaleResolutionDownBy parameter in the parameters argument has a value less than 1.0, abort these steps and return a promise rejected with RangeError.
  9. Set the RTCRtpSender 's internal transactionId slot to a previously unused value.
  10. 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.

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 RTCRtpParameters dictionary are designed to not enable this, so attributes like ssrc 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.

Parameter Type Nullable Optional Description
parameters RTCRtpParameters ✘ ✔
Return type: Promise<void>
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 following 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 (or with a null track), 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 transceiver be the RTCRtpTransceiver object associated with sender.

  3. Let connection be the RTCPeerConnection object that created sender.

  4. If transceiver.stopped is true, return a promise rejected with an InvalidStateError.

  5. Let withTrack be the argument to this method.

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

  7. If transceiver is not yet associated with a media description [JSEP] (section 3.4.1.), then set sender's track attribute to withTrack, and return a promise resolved 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. Negotiation is not needed if withTrack is null or if the sender's existing track is ended (which appears as though the track was muted). 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. If withTrack is null, have the sender stop sending, without negotiating. Otherwise, have the sender switch seamlessly to transmitting withTrack instead of the sender's existing track, 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> 
dictionary RTCRtpParameters {
    DOMString                                 transactionId;
    sequence<RTCRtpEncodingParameters>        encodings;
    sequence<RTCRtpHeaderExtensionParameters> headerExtensions;
    RTCRtcpParameters                         rtcp;
    sequence<RTCRtpCodecParameters>           codecs;
    RTCDegradationPreference                  degradationPreference = "balanced";
};

Dictionary RTCRtpParameters Members

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.

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.

codecs of type sequence<RTCRtpCodecParameters>

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

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. 

dictionary RTCRtpEncodingParameters {
    unsigned long       ssrc;
    RTCRtpRtxParameters rtx;
    RTCRtpFecParameters fec;
    RTCDtxStatus        dtx;
    boolean             active;
    RTCPriorityType     priority;
    unsigned long       maxBitrate;
    unsigned long       maxFramerate;
    DOMString           rid;
    double              scaleResolutionDownBy = 1;
};

Dictionary RTCRtpEncodingParameters Members

ssrc of type unsigned long

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

rtx of type RTCRtpRtxParameters

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

fec of type RTCRtpFecParameters

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

dtx of type RTCDtxStatus

For an RTCRtpSender , indicates whether discontinuous transmission will be used. Setting it to disabled causes discontinuous transmission to be turned off. Setting it to enabled causes discontinuous transmission to be turned on if it was negotiated (either via a codec-specific parameter or via negotiation of the CN codec). This attribute is ignored by a video sender.

active of type boolean

For an RTCRtpSender , 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. For an RTCRtpReceiver , a value of true indicates that this encoding is being decoded. A value of false indicates this encoding is no longer being decoded.

priority of type RTCPriorityType

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

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.

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.

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 or equal to 1.0.

Usage of the attributes is defined in the table below:

Attribute Type Receiver/Sender Read/Write
ssrc unsigned long Receiver/Sender Read-only
fec RTCRtpFecParameters Receiver/Sender Read-only
dtx RTCDtxStatus Sender Read/Write
rtx RTCRtpRtxParameters Receiver/Sender Read-only
active boolean Sender Read/Write
priority RTCPriorityType Sender Read/Write
maxBitrate unsigned long Sender Read/Write
maxFramerate unsigned long Sender Read/Write
scaleResolutionDownBy double Sender Read/Write
rid DOMString Receiver/Sender Read-only 
enum RTCDtxStatus {
    "disabled",
    "enabled"
};
Enumeration description
disabled

Discontinuous transmission is disabled.
enabled

Discontinuous transmission is enabled if negotiated.

 
enum RTCDegradationPreference {
    "maintain-framerate",
    "maintain-resolution",
    "balanced"
};
Enumeration description
maintain-framerate

Degrade resolution in order to maintain framerate.
maintain-resolution

Degrade framerate in order to maintain resolution.
balanced

Degrade a balance of framerate and resolution.

 
dictionary RTCRtpRtxParameters {
    unsigned long ssrc;
};

Dictionary RTCRtpRtxParameters Members

ssrc of type unsigned long

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

dictionary RTCRtpFecParameters {
    unsigned long ssrc;
};

Dictionary RTCRtpFecParameters Members

ssrc of type unsigned long

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

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

dictionary RTCRtpHeaderExtensionParameters {
    DOMString      uri;
    unsigned short id;
    boolean        encrypted;
};

Dictionary RTCRtpHeaderExtensionParameters Members

uri of type DOMString

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

id of type unsigned short

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

encrypted of type boolean

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

dictionary RTCRtpCodecParameters {
    unsigned short payloadType;
    DOMString      mimeType;
    unsigned long  clockRate;
    unsigned short channels = 1;
    DOMString      sdpFmtpLine;
};

Dictionary RTCRtpCodecParameters Members

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.

mimeType of type DOMString

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

clockRate of type unsigned long

The codec clock rate expressed in Hertz.

channels of type unsigned short, defaulting to 1

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

sdpFmtpLine of type DOMString

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

dictionary RTCRtpCapabilities {
    sequence<RTCRtpCodecCapability>           codecs;
    sequence<RTCRtpHeaderExtensionCapability> headerExtensions;
};

Dictionary RTCRtpCapabilities Members

codecs of type sequence<RTCRtpCodecCapability>

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.

headerExtensions of type sequence<RTCRtpHeaderExtensionCapability>

Supported RTP header extensions.

dictionary RTCRtpCodecCapability {
    DOMString mimeType;
};

Dictionary RTCRtpCodecCapability Members

mimeType of type DOMString

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

dictionary 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 kind, kind, and optionally an id string, id, run the following steps:

  1. Let receiver be a new RTCRtpReceiver object.

  2. Let track be a new MediaStreamTrack object [GETUSERMEDIA].

  3. Initialize track.kind to kind.

  4. If an id string, id, was given as input to this algorithm, initialize track.id to id. (Otherwise the value generated when track was created will be used.)

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

  6. Initialize track.readyState to live.

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

  8. Set receiver.track to track.

  9. Return receiver.

interface RTCRtpReceiver {
    readonly attribute MediaStreamTrack  track;
    readonly attribute RTCDtlsTransport? transport;
    readonly attribute RTCDtlsTransport? rtcpTransport;
    static RTCRtpCapabilities          getCapabilities(DOMString kind);
    RTCRtpParameters                   getParameters();
    sequence<RTCRtpContributingSource> getContributingSources();
};

Attributes

track of type MediaStreamTrack, readonly

The track attribute is the track that is associated with this RTCRtpReceiver object. 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.

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.

rtcpTransport of type RTCDtlsTransport, readonly , nullable

The rtcpTransport attribute is the transport over which RTCP is sent and received. Prior to construction of the RTCDtlsTransport object, the rtcpTransport attribute will be null. When RTCP mux is used (or bundling, which mandates RTCP mux), rtcpTransport will be null, and both RTP and RTCP traffic will flow over transport.

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

Parameter Type Nullable Optional Description
kind DOMString ✘ ✘
Return type: RTCRtpCapabilities
getParameters

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

No parameters.
Return type: RTCRtpParameters
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>

The RTCRtpContributingSource objects contain information about a given contributing source, including the time the most recent time a packet was received from the source. The browser MUST keep information from RTP packets received in the previous 10 seconds. Each time an RTP packet is received, the RTCRtpContributingSource objects are updated. If the RTP packet contains CSRCs, then the RTCRtpContributingSource objects corresponding to those CSRCs are updated. If the RTP packet contains no CSRCs, then the RTCRtpContributingSource object corresponding to the SSRC is updated.

interface RTCRtpContributingSource {
    readonly attribute DOMHighResTimeStamp timestamp;
    readonly attribute unsigned long       source;
    readonly attribute byte?               audioLevel;
    readonly attribute boolean?            voiceActivityFlag;
};

Attributes

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.

source of type unsigned long, readonly

The CSRC or SSRC value of the contributing source.

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.

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 RTCRtpTransceiver Interface

The RTCRtpTransceiver interface represents a combination of an RTCRtpSender and an RTCRtpReceiver that share a common mid.

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, and an RTCRtpSender object, sender, run the following steps:

  1. Let transceiver be a new RTCRtpTransceiver object.

  2. Set transceiver.sender to sender.

  3. Set transceiver.receiver to receiver.

  4. Set transceiver.stopped to false.

  5. Return transceiver.

interface RTCRtpTransceiver {
    readonly attribute DOMString?                  mid;
    [SameObject]
    readonly attribute RTCRtpSender                sender;
    [SameObject]
    readonly attribute RTCRtpReceiver              receiver;
    readonly attribute boolean                     stopped;
    readonly attribute RTCRtpTransceiverDirection  direction;
    readonly attribute RTCRtpTransceiverDirection? currentDirection;
    void setDirection(RTCRtpTransceiverDirection direction);
    void stop();
    void setCodecPreferences(sequence<RTCRtpCodecCapability> codecs);
};

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. If there is no MID value in the remote SDP, and no MID value was previously assigned, a random value will be created for the mid as described in [JSEP] (section 5.9.) when the remote SDP is set. After rollbacks, the value may change from a non-null value to null.

sender of type RTCRtpSender, readonly

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

receiver of type RTCRtpReceiver, readonly

The receiver attribute is the RTCRtpReceiver corresponding to the RTP media that may be received 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 RTCTransceiver to be stopped.

direction of type RTCRtpTransceiverDirection, readonly

As defined in [JSEP] (section 4.2.3.), the direction attribute indicates the preferred direction of this transceiver, which will be used in calls to createOffer and createAnswer . The value of direction does not change except due to calls to setDirection .

currentDirection of type RTCRtpTransceiverDirection, readonly, nullable

As defined in [JSEP] (section 4.2.3), 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, or if the transceiver is stopped , currentDirection is null.

Methods

setDirection

The setDirection method sets the direction of the RTCRtpTransceiver. Calls to setDirection() do 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.). Calling setDirection() updates the negotiation-needed flag for the RTCRtpTransceiver's associated RTCPeerConnection .

When this 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 newDirection be the argument to setDirection.

  3. If newDirection is equal to transceiver.direction, abort these steps.

  4. If newDirection has a value other than sendrecv, sendonly, recvonly or inactive, throw an InvalidModificationError and abort these steps.

  5. Set transceiver.direction to newDirection.

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

  7. Update the negotiation-needed flag for connection.

Parameter Type Nullable Optional Description
direction RTCRtpTransceiverDirection ✘ ✘
Return type: void
stop

The stop method irreversibly stops the RTCRtpTransceiver. The sender of this transceiver will no longer send, the receiver will no longer receive. Calling stop() updates the negotiation-needed flag for the RTCRtpTransceiver's associated RTCPeerConnection .

Stopping a 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).

When this method is invoked, the User Agent MUST run the following steps:

  1. Let transceiver be the RTCRtpTransceiver object which is to be stopped.

  2. If transceiver.stopped is true, abort these steps.

  3. Let connection be the RTCPeerConnection object on which the transceiver is to be stopped.

  4. If connection's [[isClosed]] slot is true, throw an InvalidStateError exception and abort these steps.

  5. Let sender be transceiver.sender.

  6. Let receiver be transceiver.receiver.

  7. Stop sending media with sender.

  8. Stop receiving media with receiver.

  9. Set receiver.track.readyState to ended.

  10. Set transceiver.stopped to true.

  11. Mark connection as needing negotiation.

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

5.4.1 "Hold" functionality

Together, the setDirection and replaceTrack methods enable developers to implement "hold" scenarios.

To send music to a peer and cease rendering received audio (music-on-hold):

Example 3
// Assume we have an audio transceiver and a music track named musicTrack
audio.sender.replaceTrack(musicTrack);
// Mute received audio
audio.receiver.track.enabled = "false";
// Set the direction to send-only (requires negotiation)
audio.setDirection("sendonly");

To respond to a remote peer's "sendonly" offer:

Example 4
// Stop sending audio
audio.sender.replaceTrack(null);
// Set the direction recvonly (requires negotiation)
audio.setDirection("recvonly");
// Apply the sendonly offer, and then call createAnswer
// and send a recvonly answer
pc.setRemoteDescription(sendonlyOffer).then(doAnswer).catch(onSignalingError);

To stop sending music and send audio captured from a microphone, as well to render received audio:

Example 5
//assume we have an audio transceiver and a microphone track named micTrack
audio.sender.replaceTrack(micTrack);
// Unmute received audio
audio.receiver.track.enabled = "true";
// // Set the direction to sendrecv (requires negotiation)
audio.setDirection("sendrecv");

To respond to being taken off hold by a remote peer:

Example 6
// Start sending audio
audio.sender.replaceTrack(micTrack);
// Set the direction sendrecv (requires negotiation)
audio.setDirection("sendrecv");
// Apply the sendrecv offer, and then call createAnswer
// and send a sendrecv answer
pc.setRemoteDescription(sendrecvOffer).then(doAnswer).catch(onSignalingError);

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

interface RTCDtlsTransport {
    readonly attribute RTCIceTransport       transport;
    readonly attribute RTCDtlsTransportState state;
    sequence<ArrayBuffer> getRemoteCertificates();
             attribute EventHandler          onstatechange;
};

Attributes

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.

state of type RTCDtlsTransportState, readonly

The state attribute MUST return the state of the transport.

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

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>

RTCDtlsTransportState Enum

enum 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.
connected DTLS has completed negotiation of a secure connection.
closed The transport has been closed.
failed The transport has failed as the result of an error (such as a failure to validate the remote fingerprint).

5.5.1 The RTCDtlsFingerprint Object

The RTCDtlsFingerprint object includes the hash function algorithm and certificate fingerprint as described in [ RFC4572].

dictionary 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, initially specified in [ RFC4572] Section 8. As noted in [JSEP] Section 5.2.1, the digest algorithm used for the fingerprint matches that used in the certificate signature.

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.

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's [[isClosed]] slot is true, abort these steps.

  3. Let transport be the RTCIceTransport for which candidate gathering began.

  4. Set transport's gatheringState to gathering .

  5. Fire a simple event named gatheringstatechange at transport.

  6. Update the ICE gathering state of connection.

When the ICE Agent indicates that it finished 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's [[isClosed]] slot is true, abort these steps.

  3. Let transport be the RTCIceTransport for which candidate gathering finished.

  4. Create an RTCIceCandidate instance newCandidate, with sdpMid and sdpMLineIndex set to the values associated with this RTCIceTransport , with ufrag set to the ufrag of the generation of candidates for which gathering finished, with candidate set to an empty string, and with all other nullable members set to null.

  5. Fire an event named icecandidate with 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's gatheringState to complete .

  8. Fire a simple event named gatheringstatechange at transport.

  9. Update the ICE gathering state of connection.

Issue 1
ICEbis doesn't define what a "generation of candidates" is, though this terminology is used in places like [TRICKLE-ICE]. Once a definition is added we should reference it here.

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 connection be the RTCPeerConnection object associated with this ICE Agent.

  2. If connection's [[isClosed]] slot is true, abort these steps.

  3. Let transport be the RTCIceTransport for which this candidate is being made available.

  4. Add the candidate to connection's localDescription .

  5. Create an RTCIceCandidate instance to represent the candidate. Let newCandidate be that object.

  6. Add newCandidate to transport's set of local candidates.

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

When the ICE Agent indicates that the RTCIceTransportState for an RTCIceTransport has changed, 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's [[isClosed]] slot is true, abort these steps.

  3. Let transport be the RTCIceTransport whose state is changing.

  4. Let newState be the new indicated RTCIceTransportState .

  5. Set transport's state to newState.

  6. Fire a simple event named statechange at transport.

  7. Update the ICE connection state of connection.

  8. Update the connection state of connection.

When the ICE Agent indicates that the selected candidate pair for an RTCIceTransport has changed, 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's [[isClosed]] slot is true, abort these steps.

  3. Let transport be the RTCIceTransport whose selected candidate pair is changing.

  4. Let newCandidatePair be a newly created RTCIceCandidatePair representing the indicated pair if one is selected, and null otherwise.

  5. Set transport's selected candidate pair to newCandidatePair.

  6. Fire a simple event named selectedcandidatepairchange at transport.

interface RTCIceTransport {
    readonly attribute RTCIceRole           role;
    readonly attribute RTCIceComponent      component;
    readonly attribute RTCIceTransportState state;
    readonly attribute RTCIceGathererState  gatheringState;
    sequence<RTCIceCandidate> getLocalCandidates();
    sequence<RTCIceCandidate> getRemoteCandidates();
    RTCIceCandidatePair?      getSelectedCandidatePair();
    RTCIceParameters?         getLocalParameters();
    RTCIceParameters?         getRemoteParameters();
             attribute EventHandler         onstatechange;
             attribute EventHandler         ongatheringstatechange;
             attribute EventHandler         onselectedcandidatepairchange;
};

Attributes

role of type RTCIceRole, readonly

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

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

state of type RTCIceTransportState, readonly

The state attribute MUST return the state of the transport.

gatheringState of type RTCIceGatheringState, readonly

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

onstatechange of type EventHandler
This event handler, of event handler event type statechange , MUST be fired any time the RTCIceTransport state changes.
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.

Methods

getLocalCandidates

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

No parameters.
Return type: sequence<RTCIceCandidate>
getRemoteCandidates

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

No parameters.
Return type: sequence<RTCIceCandidate>
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
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
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 
dictionary RTCIceParameters {
    DOMString usernameFragment;
    DOMString password;
};

Dictionary RTCIceParameters Members

usernameFragment of type DOMString

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

password of type DOMString

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

dictionary RTCIceCandidatePair {
    RTCIceCandidate local;
    RTCIceCandidate remote;
};

Dictionary RTCIceCandidatePair Members

local of type RTCIceCandidate

The local ICE candidate.

remote of type RTCIceCandidate

The remote ICE candidate.

RTCIceGathererState Enum

enum RTCIceGathererState {
    "new",
    "gathering",
    "complete"
};
Enumeration description
new The RTCIceTransport was just created, and has not started gathering candidates yet.
gathering The RTCIceTransport is in the process of gathering candidates.
complete The RTCIceTransport has completed gathering and the end-of-candidates indication for this transport has been sent. It will not gather candidates again until an ICE restart causes it to restart.

RTCIceTransportState Enum

enum RTCIceTransportState {
    "new",
    "checking",
    "connected",
    "completed",
    "failed",
    "disconnected",
    "closed"
};
Enumeration description
new The RTCIceTransport is gathering candidates and/or waiting for remote candidates to be supplied, and has not yet started checking.
checking The RTCIceTransport has received at least one remote candidate and is checking candidate pairs and has either not yet found a connection or consent checks [RFC7675] have failed on all previously successful candidate pairs. In addition to checking, it may also still be gathering.
connected The RTCIceTransport has found a usable connection, but is still checking other candidate pairs to see if there is a better connection. It may also still be gathering and/or waiting for additional remote candidates. If consent checks [RFC7675] fail on the connection in use, and there are no other successful candidate pairs available, then the state transitions to "checking" (if there are candidate pairs remaining to be checked) or "disconnected" (if there are no candidate pairs to check, but the peer is still gathering and/or waiting for additional remote candidates).
completed The RTCIceTransport has finished gathering, received an indication that there are no more remote candidates, finished checking all candidate pairs and found a connection. If consent checks [RFC7675] subsequently fail on all successful candidate pairs, the state transitions to "failed".
failed The RTCIceTransport has finished gathering, received an indication that there are no more remote candidates, finished checking all candidate pairs, and all pairs have either failed connectivity checks or have lost consent.
disconnected The ICE Agent has determined that connectivity is currently lost for this RTCIceTransport . This is more aggressive than failed, and may trigger intermittently (and resolve itself without action) on a flaky network. The way this state is determined is implementation dependent. Examples include:
  • Losing the network interface for the connection in use.
  • Repeatedly failing to receive a response to STUN requests.
Alternatively, the RTCIceTransport has finished checking all existing candidates pairs and failed to find a connection (or consent checks [RFC7675] once successful, have now failed), but it is still gathering and/or waiting for additional remote candidates.
closed The RTCIceTransport has shut down and is no longer responding to STUN requests.

The failed and completed states require an indication that there are no additional remote candidates. This can be indicated either by canTrickleIceCandidates being set to false, or the processing of an end-of-candidates indication as described in [JSEP].

Some example transitions might be:

ICE transport state transition diagram
Fig. 2 Non-normative ICE transport state transition diagram

RTCIceRole Enum

enum RTCIceRole {
    "controlling",
    "controlled"
};
Enumeration description
controlling A controlling agent as defined by [ICE], Section 3.
controlled A controlled agent as defined by [ICE], Section 3.

RTCIceComponent Enum

enum RTCIceComponent {
    "RTP",
    "RTCP"
};
Enumeration description
RTP The ICE Transport is used for RTP (or RTP/RTCP-multiplexing), as defined in [ICE], Section 4.1.1.1. Protocols multiplexed with RTP (e.g. data channel) share its component ID.
RTCP The ICE Transport is used for RTCP as defined by [ICE], Section 4.1.1.1.

5.7 RTCTrackEvent

The track event uses the RTCTrackEvent interface.

Firing an RTCTrackEvent event named e with an RTCRtpReceiver receiver, a MediaStreamTrack track and a MediaStream[] streams, 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 RTCTrackEvent interface with the receiver attribute set to receiver, track attribute set to track, streams attribute set to streams, MUST be created and dispatched at the given target.

[Constructor(DOMString type, RTCTrackEventInit eventInitDict)]
interface RTCTrackEvent : Event {
    readonly attribute RTCRtpReceiver           receiver;
    readonly attribute MediaStreamTrack         track;
    readonly attribute FrozenArray<MediaStream> streams;
    readonly attribute RTCRtpTransceiver        transceiver;
};

Constructors

RTCTrackEvent
readonly attribute RTCRtpReceiver receiver
Parameter Type Nullable Optional Description
type DOMString ✘ ✘
eventInitDict RTCTrackEventInit ✘ ✘

Attributes

receiver of type RTCRtpReceiver, readonly

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

track of type MediaStreamTrack, readonly

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

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.

transceiver of type RTCRtpTransceiver, readonly

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

dictionary RTCTrackEventInit : EventInit {
    required RTCRtpReceiver        receiver;
    required MediaStreamTrack      track;
             sequence<MediaStream> streams = [];
    required RTCRtpTransceiver     transceiver;
};

Dictionary RTCTrackEventInit Members

receiver of type RTCRtpReceiver, required

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

track of type MediaStreamTrack, required

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

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.

transceiver of type RTCRtpTransceiver, required

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

6. Peer-to-peer Data API

The Peer-to-peer Data API lets a web application send and receive generic application data peer-to-peer. The API for sending and receiving data models the behavior of WebSockets [WEBSOCKETS-API].

6.1 RTCPeerConnection Interface Extensions

The Peer-to-peer data API extends the RTCPeerConnection interface as described below.

partial interface RTCPeerConnection {
    readonly attribute RTCSctpTransport? sctp;
    RTCDataChannel createDataChannel([TreatNullAs=EmptyString] USVString label,
                                     optional RTCDataChannelInit dataChannelDict);
             attribute EventHandler      ondatachannel;
};

Attributes

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.

ondatachannel of type EventHandler
The event type of this event handler is datachannel .

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. Let connection be the RTCPeerConnection object on which the method is invoked.

  2. If connection's [[isClosed]] slot is true, throw an InvalidStateError exception and abort these steps.

  3. Let channel be a newly created RTCDataChannel object.

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

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

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

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

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

  10. If id is equal to 65535, which is greater than the maximum allowed ID of 65534 but still qualifies as an unsigned short, throw a TypeError exception and abort these steps.

  11. If id attribute is uninitialized (not set via the dictionary), initialize it to a value generated by the user agent, according to [RTCWEB-DATA-PROTOCOL], 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.

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

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

  14. If channel was the first RTCDataChannel created on connection, update the negotiation-needed flag for connection.

Parameter Type Nullable Optional Description
label USVString ✘ ✘
dataChannelDict RTCDataChannelInit ✘ ✔
Return type: RTCDataChannel

6.1.1 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;
};
Attributes
transport of type RTCDtlsTransport, readonly

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

maxMessageSize of type unsigned long, readonly

The maximum size of data that can be passed to RTCDataChannel 's send() method.

6.2 RTCDataChannel

The RTCDataChannel interface represents a bi-directional data channel between two peers. A RTCDataChannel is created via a factory method on an RTCPeerConnection object. The messages sent between the browsers are described in [RTCWEB-DATA] and [ RTCWEB-DATA-PROTOCOL].

There are two ways to establish a connection with RTCDataChannel . The first way is to simply create a RTCDataChannel at one of the peers with the negotiated RTCDataChannelInit dictionary member unset or set to its default value false. This will announce the new channel in-band and trigger a RTCDataChannelEvent with the corresponding RTCDataChannel object at the other peer. The second way is to let the application negotiate the RTCDataChannel . To do this, create a RTCDataChannel object with the negotiated RTCDataChannelInit dictionary member set to true, and signal out-of-band (e.g. via a web server) to the other side that it SHOULD create a corresponding RTCDataChannel with the negotiated RTCDataChannelInit dictionary member set to true and the same id . This will connect the two separately created RTCDataChannel objects. The second way makes it possible to create channels with asymmetric properties and to create channels in a declarative way by specifying matching id s.

Each RTCDataChannel has an associated underlying data transport that is used to transport actual data to the other peer. The transport properties of the underlying data transport, such as in order delivery settings and reliability mode, are configured by the peer as the channel is created. The properties of a channel cannot change after the channel has been created. The actual wire protocol between the peers is specified by the WebRTC DataChannel Protocol specification [RTCWEB-DATA].

A RTCDataChannel can be configured to operate in different reliability modes. A reliable channel ensures that the data is delivered at the other peer through retransmissions. An unreliable channel is configured to either limit the number of retransmissions ( maxRetransmits ) or set a time during which transmissions (including retransmissions) are allowed ( maxPacketLifeTime ). These properties can not be used simultaneously and an attempt to do so will result in an error. Not setting any of these properties results in a reliable channel.

A RTCDataChannel , created with createDataChannel or dispatched via a RTCDataChannelEvent , MUST initially be in the connecting state. When the RTCDataChannel object's underlying data transport is ready, the user agent MUST announce the RTCDataChannel as open.

When the user agent is to announce a RTCDataChannel as open, the user agent MUST queue a task to run the following steps:

  1. If the associated RTCPeerConnection object's [[ isClosed]] slot is true, abort these steps.

  2. Let channel be the RTCDataChannel object to be announced.

  3. Set channel's readyState attribute to open.

  4. Fire a simple event named open at channel.

When an underlying data transport is to be announced (the other peer created a channel with negotiated unset or set to false), the user agent of the peer that did not initiate the creation process MUST queue a task to run the following steps:

  1. If the associated RTCPeerConnection object's [[ isClosed]] slot is true, abort these steps.

  2. Let channel be a newly created RTCDataChannel object.

  3. Let configuration be an information bundle received from the other peer as a part of the process to establish the underlying data transport described by the WebRTC DataChannel Protocol specification [RTCWEB-DATA-PROTOCOL].

  4. Initialize channel's label , ordered , maxPacketLifeTime , maxRetransmits , protocol , negotiated and id attributes to their corresponding values in configuration.

  5. Set channel's readyState attribute to connecting.

  6. Fire a datachannel event named datachannel with channel at the RTCPeerConnection object.

An RTCDataChannel object's underlying data transport may be torn down in a non-abrupt manner by running the closing procedure. When that happens the user agent MUST, unless the procedure was initiated by the close method, queue a task that sets the object's readyState attribute to closing. This will eventually render the data transport closed.

When a RTCDataChannel object's underlying data transport has been closed, the user agent MUST queue a task to run the following steps:

  1. Let channel be the RTCDataChannel object whose transport was closed.

  2. Set channel's readyState attribute to closed.

  3. If the transport was closed with an error, fire a NetworkError event at channel.

  4. Fire a simple event named close at channel.

In some cases, the user agent may be unable to create an RTCDataChannel 's underlying data transport. For example, the data channel's id may be outside the range negotiated by the [ RTCWEB-DATA] implementations, or in the case where the user agent generates an id according to [RTCWEB-DATA-PROTOCOL], no more IDs may be available. When the user agent determines that an RTCDataChannel 's underlying data transport cannot be created, the user agent MUST queue a task to run the following steps:

  1. Let channel be the RTCDataChannel object for which the user agent could not create an underlying data transport.

  2. Set channel's readyState attribute to closed.

  3. Fire a NetworkError event at channel.

  4. Fire a simple event named close at channel.

interface RTCDataChannel : EventTarget {
    readonly attribute USVString           label;
    readonly attribute boolean             ordered;
    readonly attribute unsigned short?     maxPacketLifeTime;
    readonly attribute unsigned short?     maxRetransmits;
    readonly attribute USVString           protocol;
    readonly attribute boolean             negotiated;
    readonly attribute unsigned short      id;
    readonly attribute RTCPriorityType     priority;
    readonly attribute RTCDataChannelState readyState;
    readonly attribute unsigned long       bufferedAmount;
             attribute unsigned long       bufferedAmountLowThreshold;
             attribute EventHandler        onopen;
             attribute EventHandler        onbufferedamountlow;
             attribute EventHandler        onerror;
             attribute EventHandler        onclose;
    void close();
             attribute EventHandler        onmessage;
             attribute DOMString           binaryType;
    void send(USVString data);
    void send(Blob data);
    void send(ArrayBuffer data);
    void send(ArrayBufferView data);
};

Attributes

label of type USVString, 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.

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.

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.

protocol of type USVString, 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.

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.

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.

priority of type RTCPriorityType, readonly

The priority attribute returns the priority for this RTCDataChannel . The priority is assigned by the user agent at channel creation time. The attribute 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).

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.

onopen of type EventHandler
The event type of this event handler is open .
onbufferedamountlow of type EventHandler
The event type of this event handler is bufferedamountlow .
onerror of type EventHandler
The event type of this event handler is error .
onclose of type EventHandler
The event type of this event handler is close .
onmessage of type EventHandler
The event type of this event handler is message .
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.

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 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 
dictionary RTCDataChannelInit {
    boolean         ordered = true;
    unsigned short  maxPacketLifeTime;
    unsigned short  maxRetransmits;
    USVString       protocol = "";
    boolean         negotiated = false;
    unsigned short  id;
    RTCPriorityType priority = "low";
};

Dictionary RTCDataChannelInit Members

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.

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.

protocol of type USVString, defaulting to ""

Subprotocol name used for this channel.

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.

id of type unsigned short

Overrides the default selection of id for this channel.

priority of type RTCPriorityType, defaulting to low

Priority of this channel.

The send() method is overloaded to handle different data argument types. When any version of the method is called, the user agent MUST run the following steps:

  1. Let channel be the RTCDataChannel object on which data is to be sent.

  2. If channel's readyState attribute is connecting, throw an InvalidStateError exception and abort these steps.

  3. Execute the sub step that corresponds to the type of the methods argument:

    • string object:

      Let data be the object and increase the bufferedAmount attribute by the number of bytes needed to express data as UTF-8.

    • Blob object:

      Let data be the raw data represented by the Blob object and increase the bufferedAmount attribute by the size of data, in bytes.

    • ArrayBuffer object:

      Let data be the data stored in the buffer described by the ArrayBuffer object and increase the bufferedAmount attribute by the length of the ArrayBuffer in bytes.

    • ArrayBufferView object:

      Let data be the data stored in the section of the buffer described by the ArrayBuffer object that the ArrayBufferView object references and increase the bufferedAmount attribute by the length of the ArrayBufferView in bytes.

  4. If channel's underlying data transport is not established yet, or if the closing procedure has started, then abort these steps.

  5. Attempt to send data on channel's underlying data transport; if the data cannot be sent, e.g. because it would need to be buffered but the buffer is full, the user agent MUST abruptly close channel's underlying data transport with an error.

enum RTCDataChannelState {
    "connecting",
    "open",
    "closing",
    "closed"
};
Enumeration description
connecting

The user agent is attempting to establish the underlying data transport. This is the initial state of a RTCDataChannel object created with createDataChannel .
open

The underlying data transport is established and communication is possible. This is the initial state of a RTCDataChannel object dispatched as a part of a RTCDataChannelEvent .
closing

The procedure to close down the underlying data transport has started.
closed

The underlying data transport has been closed or could not be established.

6.3 RTCDataChannelEvent

The datachannel event uses the RTCDataChannelEvent interface.

Firing a datachannel event named e with a RTCDataChannel channel 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 RTCDataChannelEvent interface with the channel attribute set to channel, MUST be created and dispatched at the given target. 

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

Constructors

RTCDataChannelEvent
readonly attribute RTCDataChannel channel
Parameter Type Nullable Optional Description
type DOMString ✘ ✘
eventInitDict RTCDataChannelEventInit ✘ ✘

Attributes

channel of type RTCDataChannel, readonly

The channel attribute represents the RTCDataChannel object associated with the event.

dictionary RTCDataChannelEventInit : EventInit {
    required RTCDataChannel channel;
};

Dictionary RTCDataChannelEventInit Members

channel of type RTCDataChannel, required

The RTCDataChannel object to be announced by the event.

6.4 Garbage Collection

A RTCDataChannel object MUST not be garbage collected if its

7. Peer-to-peer DTMF

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

7.1 RTCRtpSender Interface Extensions

The Peer-to-peer DTMF API extends the RTCRtpSender interface as described below.

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

Attributes

dtmf of type RTCDTMFSender, readonly , nullable

The dtmf attribute returns a RTCDTMFSender which can be used to send DTMF. A null value indicates that this RTCRtpSender cannot send DTMF.

7.2 RTCDTMFSender 

interface RTCDTMFSender : EventTarget {
    void insertDTMF(DOMString tones,
                    optional unsigned long duration = 100,
                    optional unsigned long interToneGap = 70);
             attribute EventHandler ontonechange;
    readonly attribute DOMString    toneBuffer;
};

Attributes

ontonechange of type EventHandler

The event type of this event handler is tonechange .

toneBuffer of type DOMString, readonly

The toneBuffer attribute MUST return a list of the tones remaining to be played out. For the syntax, content, and interpretation of this list, see insertDTMF .

Methods

insertDTMF

An RTCDTMFSender object's insertDTMF method is used to send DTMF tones.

The tones parameter is treated as a series of characters. The characters 0 through 9, A through D, #, and * generate the associated DTMF tones. The characters a to d MUST be normalized to uppercase on entry and are equivalent to A to D. As noted in [ RTCWEB-AUDIO] Section 3, support for the characters 0 through 9, A through D, #, and * are required. The character ',' MUST be supported, and indicates a delay of 2 seconds before processing the next character in the tones parameter. All other characters (and only those other characters) MUST be considered unrecognized.

The duration parameter indicates the duration in ms to use for each character passed in the tones parameters. The duration cannot be more than 6000 ms or less than 40 ms. The default duration is 100 ms for each tone.

The interToneGap parameter indicates the gap between tones in ms. The user agent clamps it to at least 30 ms. The default value is 70 ms.

The browser MAY increase the duration and interToneGap times to cause the times that DTMF start and stop to align with the boundaries of RTP packets but it MUST not increase either of them by more than the duration of a single RTP audio packet.

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

  1. let sender be the RTCRtpSender used to send DTMF.

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

  3. If transceiver.stopped is true, throw an InvalidStateError exception.
  4. If transceiver.currentDirection is recvonly or inactive, throw an InvalidStateError exception.
  5. Let tones be the method's first argument.
  6. If tones contains any unrecognized characters, throw an InvalidCharacterError exception and abort these steps.
  7. Set the object's toneBuffer attribute to tones.
  8. If the value of the duration parameter is less than 40, set it to 40. If, on the other hand, the value is greater than 6000, set it to 6000.
  9. If the value of the interToneGap parameter is less than 30, set it to 30.
  10. If toneBuffer is an empty string, abort these steps.
  11. If a Playout task is scheduled to be run; abort these steps; otherwise queue a task that runs the following steps (Playout task):
    1. If transceiver.stopped is true, abort these steps.
    2. If transceiver.currentDirection is recvonly or inactive, abort these steps.
    3. If toneBuffer is an empty string, fire an event named tonechange with an empty string at the RTCDTMFSender object and abort these steps.
    4. Remove the first character from toneBuffer and let that character be tone.
    5. Start playout of tone for duration ms on the associated RTP media stream, using the appropriate codec.
    6. Queue a task to be executed in duration + interToneGap ms from now that runs the steps labelled Playout task.
    7. Fire an event named tonechange with a string consisting of tone at the RTCDTMFSender object.

Calling insertDTMF with an empty tones parameter can be used to cancel all tones queued to play after the currently playing tone.

Parameter Type Nullable Optional Description
tones DOMString ✘ ✘
duration unsigned long = 100 ✘ ✔
interToneGap unsigned long = 70 ✘ ✔
Return type: void

7.3 RTCDTMFToneChangeEvent

The tonechange event uses the RTCDTMFToneChangeEvent interface.

Firing a tonechange event named e with a DOMString tone 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 RTCDTMFToneChangeEvent interface with the tone attribute set to tone, MUST be created and dispatched at the given target.

[Constructor(DOMString type, RTCDTMFToneChangeEventInit eventInitDict)]
interface RTCDTMFToneChangeEvent : Event {
    readonly attribute DOMString tone;
};

Constructors

RTCDTMFToneChangeEvent
readonly attribute DOMString tone
Parameter Type Nullable Optional Description
type DOMString ✘ ✘
eventInitDict RTCDTMFToneChangeEventInit ✘ ✘

Attributes

tone of type DOMString, readonly

The tone attribute contains the character for the tone that has just begun playout (see insertDTMF ). If the value is the empty string, it indicates that the toneBuffer is an empty string and that the previous tones have completed playback.

dictionary RTCDTMFToneChangeEventInit : EventInit {
    required DOMString tone;
};

Dictionary RTCDTMFToneChangeEventInit Members

tone of type DOMString

The tone attribute contains the character for the tone that has just begun playout (see insertDTMF ). If the value is the empty string, it indicates that the previous tone has completed playback.

8. Statistics Model

8.1 Introduction

The basic statistics model is that the browser maintains a set of statistics referenced by a selector. The selector may, for example, be a MediaStreamTrack. For a track to be a valid selector, it MUST be a MediaStreamTrack that is sent or received by the RTCPeerConnection object on which the stats request was issued. The calling Web application provides the selector to the getStats() method and the browser emits (in the JavaScript) a set of statistics that it believes is relevant to the selector.

Issue 2
Evaluate the need for other selectors than MediaStreamTrack.

The statistics returned are designed in such a way that repeated queries can be linked by the RTCStats id dictionary member. Thus, a Web application can make measurements over a given time period by requesting measurements at the beginning and end of that period.

8.2 RTCPeerConnection Interface Extensions

The Statistics API extends the RTCPeerConnection interface as described below.

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

Methods

getStats

Gathers stats for the given selector and reports the result asynchronously.

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

  1. Let selectorArg be the methods first argument.

  2. If selectorArg is neither null nor a valid selector, return a promise rejected with a TypeError.

  3. Let p be a new promise.

  4. Run the following steps in parallel:

    1. Start gathering the stats indicated by selectorArg. If selectorArg is null, stats MUST be gathered for the whole RTCPeerConnection object.

    2. When the relevant stats have been gathered, resolve p with a new RTCStatsReport object, representing the gathered stats.

  5. Return p.

Parameter Type Nullable Optional Description
selector MediaStreamTrack = null ✔ ✔
Return type: Promise<RTCStatsReport>

8.3 RTCStatsReport Object

The getStats() method delivers a successful result in the form of an RTCStatsReport object. An RTCStatsReport object is a map between strings that identify the inspected objects (id attribute in RTCStats instances), and their corresponding RTCStats -derived dictionaries.

An RTCStatsReport may be composed of several RTCStats -derived dictionaries, each reporting stats for one underlying object that the implementation thinks is relevant for the selector. One achieves the total for the selector by summing over all the stats of a certain type; for instance, if a MediaStreamTrack is carried by multiple SSRCs over the network, the RTCStatsReport may contain one RTCStats-derived dictionary per SSRC (which can be distinguished by the value of the "ssrc" stats attribute).

interface RTCStatsReport {
    readonly maplike<DOMString, object>;
};

This interface has "entries", "forEach", "get", "has", "keys", "values", @@iterator methods and a "size" getter brought by readonly maplike.

Use these to retrieve the various dictionaries descended from RTCStats that this stats report is composed of. The set of supported property names [WEBIDL-1] is defined as the ids of all the RTCStats -derived dictionaries that have been generated for this stats report.

8.4 RTCStats Dictionary

An RTCStats dictionary represents the stats gathered by inspecting a specific object relevant to a selector. The RTCStats dictionary is a base type that specifies as set of default attributes, such as timestamp and type. Specific stats are added by extending the RTCStats dictionary.

Note that while stats names are standardized, any given implementation may be using experimental values or values not yet known to the Web application. Thus, applications MUST be prepared to deal with unknown stats.

Statistics need to be synchronized with each other in order to yield reasonable values in computation; for instance, if "bytesSent" and "packetsSent" are both reported, they both need to be reported over the same interval, so that "average packet size" can be computed as "bytes / packets" - if the intervals are different, this will yield errors. Thus implementations MUST return synchronized values for all stats in an RTCStats -derived dictionary.

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

Dictionary RTCStats Members

timestamp of type DOMHighResTimeStamp

The timestamp, of type DOMHighResTimeStamp [HIGHRES-TIME], associated with this object. The time is relative to the UNIX epoch (Jan 1, 1970, UTC).

type of type RTCStatsType

The type of this object.

The type attribute MUST be initialized to the name of the most specific type this RTCStats dictionary represents.

id of type DOMString

A unique id that is associated with the object that was inspected to produce this RTCStats object. Two RTCStats objects, extracted from two different RTCStatsReport objects, MUST have the same id if they were produced by inspecting the same underlying object. User agents are free to pick any format for the id as long as it meets the requirements above.

enum RTCStatsType {
};

The set of valid values for RTCStatsType, and the dictionaries derived from RTCStats that they indicate, are documented in [ WEBRTC-STATS].

8.5 Mandatory To Implement Stats

The stats listed in [WEBRTC-STATS] are intended to cover a wide range of use cases. Not all of them have to be implemented by every WebRTC implementation.

An implementation MUST support generating statistics of the following types when the corresponding objects exist on a PeerConnection, with the attributes that are listed when they are valid for that object:

An implementation MAY support generating any other statistic defined in [WEBRTC-STATS], and MAY generate statistics that are not documented.

8.6 GetStats Example

Consider the case where the user is experiencing bad sound and the application wants to determine if the cause of it is packet loss. The following example code might be used:

Example 7
var baselineReport, currentReport;
var selector = pc.getSenders()[0].track;

pc.getStats(selector).then(function (report) {
    baselineReport = report;
})
.then(function() {
    return new Promise(function(resolve) {
        setTimeout(resolve, aBit); // ... wait a bit
    });
})
.then(function() {
    return pc.getStats(selector);
})
.then(function (report) {
    currentReport = report;
    processStats();
})
.catch(function (error) {
  log(error.toString());
});

function processStats() {
    // compare the elements from the current report with the baseline
    currentReport.forEach (now => {
        if (now.type != "outboundrtp")
            return;

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

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

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

            // if fractionLost is > 0.3, we have probably found the culprit
            var fractionLost = (packetsSent - packetsReceived) / packetsSent;
        }
    }
}

9. Identity

9.1 Identity Provider Interaction

WebRTC offers and answers (and hence the channels established by RTCPeerConnection objects) can be authenticated by using a web-based Identity Provider (IdP). The idea is that the entity sending an offer or answer acts as the Authenticating Party (AP) and obtains an identity assertion from the IdP which it attaches to the session description. The consumer of the session description (i.e., the RTCPeerConnection on which setRemoteDescription is called) acts as the Relying Party (RP) and verifies the assertion.

The interaction with the IdP is designed to decouple the browser from any particular identity provider; the browser need only know how to load the IdP's JavaScript, the location of which is determined by the IdP's identity, and the generic interface to generating and validating assertions. The IdP provides whatever logic is necessary to bridge the generic protocol to the IdP's specific requirements. Thus, a single browser can support any number of identity protocols, including being forward compatible with IdPs which did not exist at the time the browser was written.

9.1.1 Identity Provider Selection

An IdP is used to generate an identity assertion as follows:

  1. If the setIdentityProvider() method has been called, the IdP provided shall be used.
  2. If the setIdentityProvider() method has not been called, then the user agent MAY use an IdP configured into the browser.

In order to verify assertions, the IdP domain name and protocol are taken from the domain and protocol fields of the identity assertion.

9.1.2 Instantiating an IdP Proxy

In order to communicate with the IdP, the user agent loads the IdP JavaScript from the IdP. The URI for the IdP script is a well-known URI formed from the domain and protocol fields, as specified in [RTCWEB-SECURITY-ARCH].

The IdP MAY generate an HTTP redirect to another "https" origin, the browser MUST treat a redirect to any other scheme as a fatal error.

The user agent instantiates an isolated interpreted context, a JavaScript realm that operates in the origin of the loaded JavaScript. Note that a redirect will change the origin of the loaded script.

The realm is populated with a global that implements both the RTCIdentityProviderGlobalScope and WorkerGlobalScope [WEBWORKERS] interfaces.

The user agent provides an instance of RTCIdentityProviderRegistrar named rtcIdentityProvider in the global scope of the realm. This object is used by the IdP to interact with the user agent.

[Global,
 Exposed=RTCIdentityProviderGlobalScope]
interface RTCIdentityProviderGlobalScope : WorkerGlobalScope {
    readonly attribute RTCIdentityProviderRegistrar rtcIdentityProvider;
};
Attributes
rtcIdentityProvider of type RTCIdentityProviderRegistrar, readonly
This object is used by the IdP to register an RTCIdentityProvider instance with the browser.
9.1.2.1 Implementing an IdP Securely

An environment that mimics the identity provider realm can be provided by any script. However, only scripts running in the origin of the IdP are able to generate an identical environment. Other origins can load and run the IdP proxy code, but they will be unable to replicate data that is unique to the origin of the IdP.

This means that it is critical that an IdP use data that is restricted to its own origin when generating identity assertions. Otherwise, another origin could load the IdP script and use it to impersonate users.

The data that the IdP script uses could be stored on the client (for example, in IndexedDB) or loaded from servers. Data that is acquired from a server SHOULD require credentials and be protected from cross-origin access.

There is no risk to the integrity of identity assertions if an IdP validates an identity assertion without using origin-private data.

9.2 Registering an IdP Proxy

An IdP proxy implements the RTCIdentityProvider methods, which are the means by which the user agent is able to request that an identity assertion be generated or validated.

Once instantiated, the IdP script is executed. The IdP MUST call the register() function on the RTCIdentityProviderRegistrar instance during script execution. If an IdP is not registered during this script execution, the user agent cannot use the IdP proxy and MUST fail any future attempt to interact with the IdP.

[Exposed=RTCIdentityProviderGlobalScope]
interface RTCIdentityProviderRegistrar {
    void register(RTCIdentityProvider idp);
};

Methods

register

This method is invoked by the IdP when its script is first executed. This registers RTCIdentityProvider methods with the user agent.

Parameter Type Nullable Optional Description
idp RTCIdentityProvider ✘ ✘
Return type: void

9.2.1 Interface Exposed by Identity Providers

The callback functions in RTCIdentityProvider are exposed by identity providers and is called by RTCPeerConnection to acquire or validate identity assertions. 

dictionary RTCIdentityProvider {
    required GenerateAssertionCallback generateAssertion;
    required ValidateAssertionCallback validateAssertion;
};
Dictionary RTCIdentityProvider Members
generateAssertion of type GenerateAssertionCallback, required

A user agent invokes this method on the IdP to request the generation of an identity assertion.

The IdP provides a promise that resolves to an RTCIdentityAssertionResult to successfully generate an identity assertion. Any other value, or a rejected promise, is treated as an error.

validateAssertion of type ValidateAssertionCallback, required

A user agent invokes this method on the IdP to request the validation of an identity assertion.

The IdP returns a Promise that resolves to an RTCIdentityValidationResult to successfully validate an identity assertion and to provide the actual identity. Any other value, or a rejected promise, is treated as an error.

callback GenerateAssertionCallback = Promise<RTCIdentityAssertionResult> (DOMString contents,
                                                                          DOMString origin,
                                                                          RTCIdentityProviderOptions options);
Callback GenerateAssertionCallback Parameters
contents of type DOMString
The contents parameter includes the information that the user agent wants covered by the identity assertion. A successful validation of the provided assertion MUST produce this string.
origin of type DOMString
The origin parameter identifies the origin of the RTCPeerConnection that triggered this request. An IdP can use this information as input to policy decisions about use. This value is generated by the user agent based on the origin of the document that created the RTCPeerConnection and therefore can be trusted to be correct.
options of type RTCIdentityProviderOptions
This includes the options provided by the application when calling setIdentityProvider. Though the dictionary is an optional argument to setIdentityProvider, default values are used as necessary when passing the value to the identity provider; see the definition of RTCIdentityProviderOptions for details.
callback ValidateAssertionCallback = Promise<RTCIdentityValidationResult> (DOMString assertion,
                                                                           DOMString origin);
Callback ValidateAssertionCallback Parameters
assertion of type DOMString
The assertion parameter includes the assertion that was recovered from an a=identity in the session description; that is, the value that was part of the RTCIdentityAssertionResult provided by the IdP that generated the assertion.
origin of type DOMString
The origin parameter identifies the origin of the RTCPeerConnection that triggered this request. An IdP can use this information as input to policy decisions about use.

9.2.2 Identity Assertion and Validation Results 

dictionary RTCIdentityAssertionResult {
    required RTCIdentityProviderDetails idp;
    required DOMString                  assertion;
};
Dictionary RTCIdentityAssertionResult Members
idp of type RTCIdentityProviderDetails, required

An IdP provides these details to identify the IdP that validates the identity assertion. This struct contains the same information that is provided to setIdentityProvider.

assertion of type DOMString, required

An identity assertion. This is an opaque string that MUST contain all information necessary to assert identity. This value is consumed by the validating IdP.

dictionary RTCIdentityProviderDetails {
    required DOMString domain;
             DOMString protocol = "default";
};
Dictionary RTCIdentityProviderDetails Members
domain of type DOMString, required

The domain name of the IdP that validated the associated identity assertion.

protocol of type DOMString, defaulting to "default"

The protocol parameter used for the IdP.

dictionary RTCIdentityValidationResult {
    required DOMString identity;
    required DOMString contents;
};
Dictionary RTCIdentityValidationResult Members
identity of type DOMString, required

The validated identity of the peer.

contents of type DOMString, required

The payload of the identity assertion. An IdP that validates an identity assertion MUST return the same string that was provided to the original IdP that generated the assertion.

The user agent uses the contents string to determine if the identity assertion matches the session description.

9.3 Requesting Identity Assertions

The identity assertion request process is triggered by a call to createOffer, createAnswer, or getIdentityAssertion. When these calls are invoked and an identity provider has been set, the following steps are executed:

  1. The RTCPeerConnection instantiates an IdP as described in Identity Provider Selection and Registering an IdP Proxy. If the IdP cannot be loaded, instantiated, or the IdP proxy is not registered, this process fails.

  2. The RTCPeerConnection invokes the generateAssertion method on the RTCIdentityProvider methods registered by the IdP.

    The RTCPeerConnection generates the contents parameter to this method as described in [ RTCWEB-SECURITY-ARCH]. The value of contents includes the fingerprint of the certificate that was selected or generated during the construction of the RTCPeerConnection. The origin parameter contains the origin of the script that calls the RTCPeerConnection method that triggers this behavior. The usernameHint value is the same value that is provided to setIdentityProvider, if any such value was provided.

  3. The IdP proxy returns a Promise to the RTCPeerConnection. The IdP proxy is expected to generate the identity assertion asynchronously.

    If the user has been authenticated by the IdP, and the IdP is able to generate an identity assertion, the IdP resolves the promise with an identity assertion in the form of an RTCIdentityAssertionResult .

    This step depends entirely on the IdP. The methods by which an IdP authenticates users or generates assertions is not specified, though they could involve interacting with the IdP server or other servers.

  4. If the IdP proxy produces an error or returns a promise that does not resolve to a valid RTCIdentityValidationResult (see 9.5 IdP Error Handling), then identity validation fails.

  5. The RTCPeerConnection MAY store the identity assertion for use with future offers or answers. If a fresh identity assertion is needed for any reason, applications can create a new RTCPeerConnection.

  6. If the identity request was triggered by a createOffer() or createAnswer(), then the assertion is converted to a JSON string, base64-encoded and inserted into an a=identity attribute in the session description.

If assertion generation fails, then the promise for the corresponding function call is rejected with a DOMException that has the name OperationError.

9.3.1 User Login Procedure

An IdP MAY reject an attempt to generate an identity assertion if it is unable to verify that a user is authenticated. This might be due to the IdP not having the necessary authentication information available to it (such as cookies).

Rejecting the promise returned by generateAssertion will cause the error to propagate to the application. Login errors are indicated by rejecting the promise with an RTCError with errorDetail set to "IdPNeedLogin".

The URL to login at will be passed to the application in the idpLoginUrl attribute of the RTCPeerConnection.

An application can load the login URL in an IFRAME or popup window; the resulting page then SHOULD provide the user with an opportunity to enter any information necessary to complete the authorization process.

Once the authorization process is complete, the page loaded in the IFRAME or popup sends a message using postMessage [ webmessaging] to the page that loaded it (through the window.opener attribute for popups, or through window.parent for pages loaded in an IFRAME). The message MUST consist of the DOMString "LOGINDONE". This message informs the application that another attempt at generating an identity assertion is likely to be successful.

9.4 Verifying Identity Assertions

Identity assertion validation happens when setRemoteDescription is invoked on RTCPeerConnection . The process runs asynchronously, meaning that validation of an identity assertion might not block the completion of setRemoteDescription.

The identity assertion request process involves the following asynchronous steps:

  1. The RTCPeerConnection awaits any prior identity validation. Only one identity validation can run at a time for an RTCPeerConnection. This can happen because the resolution of setRemoteDescription is not blocked by identity validation unless there is a target peer identity.

  2. The RTCPeerConnection loads the identity assertion from the session description and decodes the base64 value, then parses the resulting JSON. The idp parameter of the resulting dictionary contains a domain and an optional protocol value that identifies the IdP, as described in [ RTCWEB-SECURITY-ARCH].

  3. The RTCPeerConnection instantiates the identified IdP as described in 9.1.1 Identity Provider Selection and 9.2 Registering an IdP Proxy. If the IdP cannot be loaded, instantiated or the IdP proxy is not registered, this process fails.

  4. The RTCPeerConnection invokes the validateAssertion method registered by the IdP.

    The assertion parameter is taken from the decoded identity assertion. The origin parameter contains the origin of the script that calls the RTCPeerConnection method that triggers this behavior.

  5. The IdP proxy returns a promise and performs the validation process asynchronously.

    The IdP proxy verifies the identity assertion using whatever means necessary. Depending on the authentication protocol this could involve interacting with the IdP server.

  6. If the IdP proxy produces an error or returns a promise that does not resolve to a valid RTCIdentityValidationResult (see 9.5 IdP Error Handling), then identity validation fails.

  7. Once the assertion is successfully verified, the IdP proxy resolves the promise with an RTCIdentityValidationResult containing the validated identity and the original contents that are the payload of the assertion.

  8. The RTCPeerConnection decodes the contents and validates that it contains a fingerprint value for every a=fingerprint attribute in the session description. This ensures that the certificate used by the remote peer for communications is covered by the identity assertion.

    Note

    A user agent is required to fail to communicate with peers that offer a certificate that doesn't match an a=fingerprint line in the negotiated session description.

  9. The RTCPeerConnection validates that the domain portion of the identity matches the domain of the IdP as described in [ RTCWEB-SECURITY-ARCH]. If this check fails then the identity validation fails.

  10. The RTCPeerConnection resolves the peerIdentity attribute with a new instance of RTCIdentityAssertion that includes the IdP domain and peer identity.

  11. The user agent MAY display identity information to a user in its UI. Any user identity information that is displayed in this fashion MUST use a mechanism that cannot be spoofed by content.

If identity validation fails, the peerIdentity promise is rejected with a DOMException that has a name of OperationError.

If identity validation fails and there is a target peer identity for the RTCPeerConnection, the promise returned by setRemoteDescription MUST be rejected with the same DOMException.

If identity validation fails and there is no a target peer identity, the value of the peerIdentity MUST be set to a new, unresolved promise instance. This permits the use of renegotiation (or a subsequent answer, if the session description was a provisional answer) to resolve or reject the identity.

9.5 IdP Error Handling

Errors in IdP processing will - in most cases - result in the failure of the procedure that invoked the IdP proxy. This will result in the rejection of the promise returned by getIdentityAssertion , createOffer , or createAnswer . An IdP proxy error causes a setRemoteDescription promise to be rejected if there is a target peer identity; IdP errors in calls to setRemoteDescription where there is no target peer identity cause the peerIdentity promise to be rejected instead.

If an error occurs these promises are rejected with a RTCError if an error occurs in interacting with the IdP proxy. The following scenarios result in errors:

9.6 RTCPeerConnection Interface Extensions

The Identity API extends the RTCPeerConnection interface as described below.

partial interface RTCPeerConnection {
    void               setIdentityProvider(DOMString provider,
                                           optional RTCIdentityProviderOptions options);
    Promise<DOMString> getIdentityAssertion();
    readonly attribute Promise<RTCIdentityAssertion> peerIdentity;
    readonly attribute DOMString?                    idpLoginUrl;
};

Attributes

peerIdentity of type Promise<RTCIdentityAssertion>, readonly

A promise that resolves with the identity of the peer if the identity is successfully validated.

This promise is rejected if an identity assertion is present in a remote session description and validation of that assertion fails for any reason. If the promise is rejected, a new unresolved value is created, unless a target peer identity has been established. If this promise successfully resolves, the value will not change.

idpLoginUrl of type DOMString, readonly , nullable

The URL that an application can navigate to so that the user can login to the IdP, as described in 9.3.1 User Login Procedure.

Methods

setIdentityProvider

Sets the identity provider to be used for a given RTCPeerConnection object. Applications need not make this call; if the browser is already configured for an IdP, then that configured IdP might be used to get an assertion.

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

  1. If the RTCPeerConnection object's [[ isClosed]] slot is true, throw an InvalidStateError exception and abort these steps.

  2. Set the current identity provider values to the tuple (provider, options).

  3. If any identity provider value has changed, discard any stored identity assertion.

Identity provider information is not used until an identity assertion is required, either in response to a call to getIdentityAssertion, or a session description is requested with a call to either createOffer or createAnswer.

Parameter Type Nullable Optional Description
provider DOMString ✘ ✘
options RTCIdentityProviderOptions ✘ ✔
Return type: void
getIdentityAssertion

Initiates the process of obtaining an identity assertion. Applications need not make this call. It is merely intended to allow them to start the process of obtaining identity assertions before a call is initiated. If an identity is needed, either because the browser has been configured with a default identity provider or because the setIdentityProvider method was called, then an identity will be automatically requested when an offer or answer is created.

When getIdentityAssertion is invoked, queue a task to run the following steps:

  1. If the RTCPeerConnection object's [[ isClosed]] slot is true, throw an InvalidStateError exception and abort these steps.

  2. Request an identity assertion from the IdP.

  3. Resolve the promise with the base64 and JSON encoded assertion.

No parameters.
Return type: Promise<DOMString> 
dictionary RTCIdentityProviderOptions {
    DOMString protocol = "default";
    DOMString usernameHint;
    DOMString peerIdentity;
};

RTCIdentityProviderOptions Members

protocol of type DOMString

The name of the protocol that is used by the identity provider. This MUST NOT include '/' (U+002F) or '\' (U+005C) characters. This value defaults to "default" if not provided.

usernameHint of type DOMString

A hint to the identity provider about the identity of the principal for which it should generate an identity assertion. If absent, the value undefined is used.

peerIdentity of type DOMString

The identity of the peer. For identity providers that bind their assertions to a particular pair of communication peers, this allows them to generate an assertion that includes both local and remote identities. If this value is omitted, but a value is provided for the peerIdentity member of RTCConfiguration , the value from RTCConfiguration is used.

[Constructor(DOMString idp, DOMString name)]
interface RTCIdentityAssertion {
    attribute DOMString idp;
    attribute DOMString name;
};

Attributes

idp of type DOMString

The domain name of the identity provider that validated this identity.

name of type DOMString

An RFC5322-conformant [RFC5322] representation of the verified peer identity. This identity will have been verified via the procedures described in [RTCWEB-SECURITY-ARCH].

9.7 Identity Examples

The identity system is designed so that applications need not take any special action in order for users to generate and verify identity assertions; if a user has configured an IdP into their browser, then the browser will automatically request/generate assertions and the other side will automatically verify them and display the results. However, applications may wish to exercise tighter control over the identity system as shown by the following examples.

This example shows how to configure the identity provider.

Example 8
pc.setIdentityProvider("example.com");

This example shows how to configure the identity provider with all the options.

Example 9
pc.setIdentityProvider("example.com", {
    protocol: "default",
    usernameHint: "alice@example.com",
    peerIdentity: "bob@example.net"
});

This example shows how to consume identity assertions inside a Web application.

Example 10
pc.peerIdentity.then(identity =>
  console.log("IdP= " + identity.idp + " identity=" + identity.name));

10. Media Stream API Extensions for Network Use

10.1 Introduction

The MediaStreamTrack interface, as defined in the [ GETUSERMEDIA] specification, typically represents a stream of data of audio or video. One or more MediaStreamTracks can be collected in a MediaStream (strictly speaking, a MediaStream as defined in [GETUSERMEDIA] may contain zero or more MediaStreamTrack objects).

A MediaStreamTrack may be extended to represent a media flow that either comes from or is sent to a remote peer (and not just the local camera, for instance). The extensions required to enable this capability on the MediaStreamTrack object will be described in this section. How the media is transmitted to the peer is described in [ RTCWEB-RTP], [RTCWEB-AUDIO], and [RTCWEB-TRANSPORT].

A MediaStreamTrack sent to another peer will appear as one and only one MediaStreamTrack to the recipient. A peer is defined as a user agent that supports this specification. In addition, the sending side application can indicate what MediaStream object(s) the MediaStreamTrack is member of. The corresponding MediaStream object(s) on the receiver side will be created (if not already present) and populated accordingly.

As also described earlier in this document, the objects RTCRtpSender and RTCRtpReceiver can be used by the application to get more fine grained control over the transmission and reception of MediaStreamTracks.

Channels are the smallest unit considered in the MediaStream specification. Channels are intended to be encoded together for transmission as, for instance, an RTP payload type. All of the channels that a codec needs to encode jointly MUST be in the same MediaStreamTrack and the codecs SHOULD be able to encode, or discard, all the channels in the track.

The concepts of an input and output to a given MediaStreamTrack apply in the case of MediaStreamTrack objects transmitted over the network as well. A MediaStreamTrack created by an RTCPeerConnection object (as described previously in this document) will take as input the data received from a remote peer. Similarly, a MediaStreamTrack from a local source, for instance a camera via [GETUSERMEDIA], will have an output that represents what is transmitted to a remote peer if the object is used with an RTCPeerConnection object.

The concept of duplicating MediaStream and MediaStreamTrack objects as described in [GETUSERMEDIA] is also applicable here. This feature can be used, for instance, in a video-conferencing scenario to display the local video from the user's camera and microphone in a local monitor, while only transmitting the audio to the remote peer (e.g. in response to the user using a "video mute" feature). Combining different MediaStreamTrack objects into new MediaStream objects is useful in certain situations.

Note

In this document, we only specify aspects of the following objects that are relevant when used along with an RTCPeerConnection . Please refer to the original definitions of the objects in the [GETUSERMEDIA] document for general information on using MediaStream and MediaStreamTrack.

10.2 MediaStream

10.2.1 id

The id attribute specified in MediaStream returns an id that is unique to this stream, so that streams can be recognized at the remote end of the RTCPeerConnection API.

When a MediaStream is created to represent a stream obtained from a remote peer, the id attribute is initialized from information provided by the remote source.

Note

The id of a MediaStream object is unique to the source of the stream, but that does not mean it is not possible to end up with duplicates. For example, the tracks of a locally generated stream could be sent from one user agent to a remote peer using RTCPeerConnection and then sent back to the original user agent in the same manner, in which case the original user agent will have multiple streams with the same id (the locally-generated one and the one received from the remote peer).

10.3 MediaStreamTrack

A MediaStreamTrack object's reference to its MediaStream in the non-local media source case (an RTP source, as is the case for MediaStreamTracks received over an RTCPeerConnection ) is always strong.

When an RTCPeerConnection receives data on an RTP source for the first time, it MUST update the muted state of the corresponding MediaStreamTrack with the value false.

When an RTCPeerConnection 's RTP source is temporarily unable to receive media due to a loss of connection or if a mute signal has been received, it MUST update the muted state of the corresponding MediaStreamTrack with the value true. When media data is available again, the muted state MUST be updated with the value false.

Issue 3

The mute signal mentioned in the previous paragraph is yet to be defined.

The procedure update a track's muted state is specified in [ GETUSERMEDIA].

When a track comes from a remote peer and the remote peer has permanently stopped sending data the ended event MUST be fired on the track, as specified in [GETUSERMEDIA].

Issue 4

How do you know when it has stopped? This seems like an SDP question, not a media-level question. (Suggestion: when the track is ended, either through port 0, or removing the a=msid attrib)

When a remote source is notified that a MediaStreamTrack , using the source, has ended [GETUSERMEDIA] the User Agent MAY choose to free resources allocated for the incoming stream, for instance turn off the decoder.

10.3.1 MediaTrackSupportedConstraints, MediaTrackCapabilities, MediaTrackConstraints and MediaTrackSettings

The basics of MediaTrackSupportedConstraints, MediaTrackCapabilites, MediaTrackConstraints and MediaTrackSettings is outlined in [GETUSERMEDIA]. However, the MediaTrackSettings for a MediaStreamTrack sourced by a RTCPeerConnection will only be populated with members to the extent that data is supplied by means of the remote RTCSessionDescription applied via setRemoteDescription and the actual RTP data. This means that certain members, such as facingMode, echoCancellation , latency, deviceId and groupId, will always be missing.

10.4 Isolated Media Streams

A MediaStream acquired using getUserMedia() is, by default, accessible to an application. This means that the application is able to access the contents of tracks, modify their content, and send that media to any peer it chooses.

WebRTC supports calling scenarios where media is sent to a specifically identified peer, without the contents of media streams being accessible to applications. This is enabled by use of the peerIdentity parameter to getUserMedia().

An application willingly relinquishes access to media by including a peerIdentity parameter in the MediaStreamConstraints. This attribute is set to a DOMString containing the identity of a specific peer.

The MediaStreamConstraints dictionary is expanded to include the peerIdentity parameter.

partial dictionary MediaStreamConstraints {
    DOMString peerIdentity;
};

Dictionary MediaStreamConstraints Members

peerIdentity of type DOMString

If set, peerIdentity isolates media from the application. Media can only be sent to the identified peer.

A user that is prompted to provide consent for access to a camera or microphone can be shown the value of the peerIdentity parameter, so that they can be informed that the consent is more narrowly restricted.

When the peerIdentity option is supplied to getUserMedia(), all of the MediaStreamTracks in the resulting MediaStream are isolated so that content is not accessible to any application. Isolated MediaStreamTracks can be used for two purposes:

A MediaStreamTrack that is added to another MediaStream remains isolated. When an isolated MediaStreamTrack is added to a MediaStream with a different peerIdentity, the MediaStream gets a combination of isolation restrictions. A MediaStream containing MediaStreamTrack instances with mixed isolation properties can be displayed, but cannot be sent using RTCPeerConnection .

Any peerIdentity property MUST be retained on cloned copies of MediaStreamTracks.

10.4.1 Extended MediaStreamTrack Properties

MediaStreamTrack is expanded to include an isolated attribute and a corresponding event. This allows an application to quickly and easily determine whether a track is accessible. 

partial interface MediaStreamTrack {
    readonly attribute boolean      isolated;
             attribute EventHandler onisolationchange;
};
Attributes
isolated of type boolean, readonly

A MediaStreamTrack is isolated (and the corresponding isolated attribute set to true) when content is inaccessible to the owning document. This occurs as a result of setting the peerIdentity option. A track is also isolated if it comes from a cross origin source.

onisolationchange of type EventHandler

This event handler, of type isolationchange, is fired when the value of the isolated attribute changes.

10.4.2 Isolated Streams and RTCPeerConnection

A MediaStreamTrack with a peerIdentity option set can be added to any RTCPeerConnection . However, the content of an isolated track MUST NOT be transmitted unless all of the following constraints are met:

  • A MediaStreamTrack from a stream acquired using the peerIdentity option can be transmitted if the RTCPeerConnection has successfully validated the identity of the peer AND that identity is the same identity that was used in the peerIdentity option associated with the track. That is, the name attribute of the peerIdentity attribute of the RTCPeerConnection instance MUST match the value of the peerIdentity option passed to getUserMedia().

    Rules for matching identity are described in [ RTCWEB-SECURITY-ARCH].

  • The peer has indicated that it will respect the isolation properties of streams. That is, a DTLS connection with a promise to respect stream confidentiality, as defined in [RTCWEB-ALPN] has been established.

Failing to meet these conditions means that no media can be sent for the affected MediaStreamTrack. Video MUST be replaced by black frames, audio MUST be replaced by silence, and equivalently information-free content MUST be provided for other media types.

Remotely sourced MediaStreamTracks MUST be isolated if they are received over a DTLS connection that has been negotiated with track isolation. This protects isolated media from the application in the receiving browser. These tracks MUST only be displayed to a user using the appropriate media element (e.g., <video> or <audio>).

Any MediaStreamTrack that has the peerIdentity option set causes all tracks sent using the same RTCPeerConnection to be isolated at the receiving peer. All DTLS connections created for a RTCPeerConnection with isolated local streams MUST be negotiated so that media remains isolated at the remote peer. This causes non-isolated media to become isolated at the receiving peer if any isolated tracks are added to the same RTCPeerConnection .

Note

Tracks that are not bound to a particular peerIdentity do not cause other streams to be isolated, these tracks simply do not have their content transmitted.

If a stream becomes isolated after initially being accessible, or an isolated stream is added to an active session, then media for that stream is replaced by information-free content (e.g., black frames or silence).

10.4.3 Protection Afforded by Media Isolation

Media isolation ensures that the content of a MediaStreamTrack is not accessible to web applications. However, to ensure that media with a peerIdentity option set can be sent to peers, some meta-information about the media will be exposed to applications.

Applications will be able to observe the parameters of the media that affect session negotiation and conversion into RTP. This includes the codecs that might be supported by the track, the bitrate, the number of packets, and the current settings that are set on the MediaStreamTrack.

In particular, the statistics that RTCPeerConnection records are not reduced in capability. New statistics that might compromise isolation MUST be avoided, or explicitly suppressed for isolated streams.

Most of these data are exposed to the network when the media is transmitted. Only the settings for the MediaStreamTrack present a new source of information. This can includes the frame rate and resolution of video tracks, the bandwidth of audio tracks, and other information about the source, which would not otherwise be revealed to a network observer. Since settings don't change at a high frequency or in response to changes in media content, settings only reveal limited reveal information about the content of a track. However, any setting that might change dynamically in response to the content of an isolated MediaStreamTrack MUST have changes suppressed.

11. Examples and Call Flows

This section is non-normative.

11.1 Simple Peer-to-peer Example

When two peers decide they are going to set up a connection to each other, they both go through these steps. The STUN/TURN server configuration describes a server they can use to get things like their public IP address or to set up NAT traversal. They also have to send data for the signaling channel to each other using the same out-of-band mechanism they used to establish that they were going to communicate in the first place.

Example 11
var signalingChannel = new SignalingChannel();
var configuration = { "iceServers": [{ "urls": "stuns:stun.example.org" }] };
var pc;

// call start() to initiate
function start() {
    pc = new RTCPeerConnection(configuration);

    // send any ice candidates to the other peer
    pc.onicecandidate = function (evt) {
        signalingChannel.send(JSON.stringify({ "candidate": evt.candidate }));
    };

    // let the "negotiationneeded" event trigger offer generation
    pc.onnegotiationneeded = function () {
        pc.createOffer().then(function (offer) {
            return pc.setLocalDescription(offer);
        })
        .then(function () {
            // send the offer to the other peer
            signalingChannel.send(JSON.stringify({ "desc": pc.localDescription }));
        })
        .catch(logError);
    };

    // once remote video track arrives, show it in the remote video element
    pc.ontrack = function (evt) {
        if (evt.track.kind === "video")
          remoteView.srcObject = evt.streams[0];
    };

    // get a local stream, show it in a self-view and add it to be sent
    navigator.mediaDevices.getUserMedia({ "audio": true, "video": true })
        .then(function (stream) {
            selfView.srcObject = stream;
            pc.addTrack(stream.getAudioTracks()[0], stream);
            pc.addTrack(stream.getVideoTracks()[0], stream);
        })
        .catch(logError);
}

signalingChannel.onmessage = function (evt) {
    if (!pc)
        start();

    var message = JSON.parse(evt.data);
    if (message.desc) {
        var desc = message.desc;

        // if we get an offer, we need to reply with an answer
        if (desc.type == "offer") {
            pc.setRemoteDescription(desc).then(function () {
                return pc.createAnswer();
            })
            .then(function (answer) {
                return pc.setLocalDescription(answer);
            })
            .then(function () {
                var str = JSON.stringify({ "desc": pc.localDescription });
                signalingChannel.send(str);
            })
            .catch(logError);
        } else if (desc.type == "answer") {
            pc.setRemoteDescription(desc).catch(logError);
        } else {
            log("Unsupported SDP type. Your code may differ here.");
        }
    } else
        pc.addIceCandidate(message.candidate).catch(logError);
};

function logError(error) {
    log(error.name + ": " + error.message);
}

11.2 Simple Peer-to-peer Example with Warm-up

When two peers decide they are going to set up a connection to each other and want to have the ICE, DTLS, and media connections "warmed up" such that they are ready to send and receive media immediately, they both go through these steps.

Example 12
var signalingChannel = new SignalingChannel();
var configuration = { "iceServers": [{ "urls": "stuns:stun.example.org" }] };
var pc;
var audio = null;
var audioSendTrack = null;
var video = null;
var videoSendTrack = null;
var started = false;

// Call warmp() to warm-up ICE, DTLS, and media, but not send media yet.
function warmup(answerer) {
    pc = new RTCPeerConnection(configuration);
    if (!answerer) {
      audio = pc.addTransceiver("audio");
      video = pc.addTransceiver("video");
    }

    // send any ice candidates to the other peer
    pc.onicecandidate = function (evt) {
        signalingChannel.send(JSON.stringify({ "candidate": evt.candidate }));
    };

    // let the "negotiationneeded" event trigger offer generation
    pc.onnegotiationneeded = function () {
        pc.createOffer().then(function (offer) {
            return pc.setLocalDescription(offer);
        })
        .then(function () {
            // send the offer to the other peer
            signalingChannel.send(JSON.stringify({ "desc": pc.localDescription }));
        })
        .catch(logError);
    };

    // once remote video track arrives, show it in the remote video element
    pc.ontrack = function (evt) {
        if (evt.track.kind === "audio") {
          if (answerer) {
            audio = evt.transceiver;
            audio.setDirection("sendrecv");
            if (started && audioSendTrack) {
              audio.sender.replaceTrack(audioSendTrack);
            }
          }
        } else if (evt.track.kind === "video") {
          if (answerer) {
            video = evt.transceiver;
            video.setDirection("sendrecv");
            if (started && videoSendTrack) {
              video.sender.replaceTrack(videoSendTrack);
            }
          }
          remoteView.srcObject = evt.streams[0];
        }
    };

    // get a local stream, show it in a self-view and add it to be sent
    navigator.mediaDevices.getUserMedia({ "audio": true, "video": true })
      .then(function (stream) {
        selfView.srcObject = stream;
        audioSendTrack = stream.getAudioTracks()[0];
        if (started) {
          audio.sender.replaceTrack(audioSendTrack);
        }
        videoSendTrack = stream.getVideoTracks()[0];
        if (started) {
          video.sender.replaceTrack(videoSendTrack);
        }
      })
      .catch(logError);
}

// Call start() to start sending media.
function start() {
  started = true;
  signalingChannel.send(JSON.stringify({ "start": true }));
}

signalingChannel.onmessage = function (evt) {
    if (!pc)
        warmup(true);

    var message = JSON.parse(evt.data);
    if (message.desc) {
        var desc = message.desc;

        // if we get an offer, we need to reply with an answer
        if (desc.type == "offer") {
            pc.setRemoteDescription(desc).then(function () {
                return pc.createAnswer();
            })
            .then(function (answer) {
                return pc.setLocalDescription(answer);
            })
            .then(function () {
                var str = JSON.stringify({ "desc": pc.localDescription });
                signalingChannel.send(str);
            })
            .catch(logError);
        } else
            pc.setRemoteDescription(desc).catch(logError);
    } else if (message.start) {
      started = true;
      if (audio && audioSendTrack) {
        audio.sender.replaceTrack(audioSendTrack);
      }
      if (video && videoSendTrack) {
        video.sender.replaceTrack(videoSendTrack);
      }
    } else
        pc.addIceCandidate(message.candidate).catch(logError);
};

function logError(error) {
    log(error.name + ": " + error.message);
}

11.3 Simple Peer-to-peer Example with media before signaling

The answerer may wish to send media in parallel with sending the answer, and the offerer may wish to render the media before the answer arrives.

Example 13
var signalingChannel = new SignalingChannel();
var configuration = { "iceServers": [{ "urls": "stuns:stun.example.org" }] };
var pc;

// call start() to initiate
function start() {
    pc = new RTCPeerConnection(configuration);

    // send any ice candidates to the other peer
    pc.onicecandidate = function (evt) {
        signalingChannel.send(JSON.stringify({ "candidate": evt.candidate }));
    };

    // let the "negotiationneeded" event trigger offer generation
    pc.onnegotiationneeded = function () {
        pc.createOffer().then(function (offer) {
            return pc.setLocalDescription(offer);
        })
        .then(function () {
            // send the offer to the other peer
            signalingChannel.send(JSON.stringify({ "desc": pc.localDescription }));
        })
        .catch(logError);
    };

    // get a local stream, show it in a self-view and add it to be sent
    navigator.mediaDevices.getUserMedia({ "audio": true, "video": true })
        .then(function (stream) {
            selfView.srcObject = stream;
            var remoteStream = new MediaStream();
            var audioSender = pc.addTrack(stream.getAudioTracks()[0], stream);
            var videoSender = pc.addTrack(stream.getVideoTracks()[0], stream);
            [audioSender, videoSender].forEach(function(sender) {
                remoteStream.addTrack(pc.getReceivers.find(function (receiver) {
                    return receiver.mid == sender.mid;
                }).track);
            });

            // Render the media even before ontrack fires.
            remoteView.srcObject = remoteStream;
        })
        .catch(logError);
}

signalingChannel.onmessage = function (evt) {
    if (!pc)
        start();

    var message = JSON.parse(evt.data);
    if (message.desc) {
        var desc = message.desc;

        // if we get an offer, we need to reply with an answer
        if (desc.type == "offer") {
            pc.setRemoteDescription(desc).then(function () {
                return pc.createAnswer();
            })
            .then(function (answer) {
                return pc.setLocalDescription(answer);
            })
            .then(function () {
                var str = JSON.stringify({ "desc": pc.localDescription });
                signalingChannel.send(str);
            })
            .catch(logError);
        } else
            pc.setRemoteDescription(desc).catch(logError);
    } else
        pc.addIceCandidate(message.candidate).catch(logError);
};

function logError(error) {
    log(error.name + ": " + error.message);
}

11.4 Simple Simulcast Example

A client wants to send multiple RTP encodings (simulcast) to a server.

Example 14
var signalingChannel = new SignalingChannel();
var configuration = { "iceServers": [{ "urls": "stuns:stun.example.org" }] };
var pc;

// call start() to initiate
function start() {
    pc = new RTCPeerConnection(configuration);

    // let the "negotiationneeded" event trigger offer generation
    pc.onnegotiationneeded = function () {
        pc.createOffer().then(function (offer) {
            return pc.setLocalDescription(offer);
        })
        .then(function () {
            // send the offer to the other peer
            signalingChannel.send(JSON.stringify({ "desc": pc.localDescription }));
        })
        .catch(logError);
    };

    // get a local stream, show it in a self-view and add it to be sent
    navigator.mediaDevices.getUserMedia({ "audio": true, "video": true })
        .then(function (stream) {
            selfView.srcObject = stream;
            pc.addTransceiver(stream.getAudioTracks()[0], {direction: "sendonly"});
            pc.addTransceiver(stream.getVideoTracks()[0], {
                direction: "sendonly",
                sendEncodings: [
                    {
                      rid: "f",
                    },
                    {
                      rid: "h",
                      scaleDownResolutionBy: 2.0
                    },
                    {
                      rid: "q",
                      scaleDownResolutionBy: 4.0
                    }
                ]
            });
        })
        .catch(logError);
}

signalingChannel.onmessage = function (evt) {
    var message = JSON.parse(evt.data);
    if (message.desc)
        pc.setRemoteDescription(message.desc).catch(logError);
    else
        pc.addIceCandidate(message.candidate).catch(logError);
};

function logError(error) {
    log(error.name + ": " + error.message);
}

11.5 Advanced Peer-to-peer Example

This example shows the more complete functionality.

Issue 5

TODO

Example 15

      

    


    

      
11.6 Peer-to-peer Data Example
      

      

        
This example shows how to create a
          RTCDataChannel
           object and perform the offer/answer exchange required to connect the channel to the other peer. The
          RTCDataChannel
           is used in the context of a simple chat application and listeners are attached to monitor when the channel is ready, messages are received and when the channel is closed.

        

          
Example 16
var signalingChannel = new SignalingChannel();
var configuration = { "iceServers": [{ "urls": "stuns:stun.example.org" }] };
var pc;
var channel;

// call start(true) to initiate
function start(isInitiator) {
    pc = new RTCPeerConnection(configuration);

    // send any ice candidates to the other peer
    pc.onicecandidate = function (evt) {
        signalingChannel.send(JSON.stringify({ "candidate": evt.candidate }));
    };

    // let the "negotiationneeded" event trigger offer generation
    pc.onnegotiationneeded = function () {
        pc.createOffer().then(function (offer) {
            return pc.setLocalDescription(offer);
        })
        .then(function () {
            // send the offer to the other peer
            signalingChannel.send(JSON.stringify({ "desc": pc.localDescription }));
        })
        .catch(logError);
    };

    if (isInitiator) {
        // create data channel and setup chat
        channel = pc.createDataChannel("chat");
        setupChat();
    } else {
        // setup chat on incoming data channel
        pc.ondatachannel = function (evt) {
            channel = evt.channel;
            setupChat();
        };
    }
}

signalingChannel.onmessage = function (evt) {
    if (!pc)
        start(false);

    var message = JSON.parse(evt.data);
    if (message.desc) {
        var desc = message.desc;

        // if we get an offer, we need to reply with an answer
        if (desc.type == "offer") {
            pc.setRemoteDescription(desc).then(function () {
                return pc.createAnswer();
            })
            .then(function (answer) {
                return pc.setLocalDescription(answer);
            })
            .then(function () {
                var str = JSON.stringify({ "desc": pc.localDescription });
                signalingChannel.send(str);
            })
            .catch(logError);
        } else
            pc.setRemoteDescription(desc).catch(logError);
    } else
        pc.addIceCandidate(message.candidate).catch(logError);
};

function setupChat() {
    channel.onopen = function () {
        // e.g. enable send button
        enableChat(channel);
    };

    channel.onmessage = function (evt) {
        showChatMessage(evt.data);
    };
}

function sendChatMessage(msg) {
    channel.send(msg);
}

function logError(error) {
    log(error.name + ": " + error.message);
}

      

      
    


    

      
11.7 Call Flow Browser to Browser
      

      

        
Issue 6

        
Editors' Note: This example flow needs to be discussed on the list and is likely wrong in many ways.

      

      
This shows an example of one possible call flow between two browsers. This does not show the procedure to get access to local media or every callback that gets fired but instead tries to reduce it down to only show the key events and messages.

      
A message sequence chart detailing a call flow between two browsers

      
    


    

      
11.8 DTMF Example
      

      
Examples assume that sender is an RTCRtpSender.

      
Sending the DTMF signal "1234" with 500 ms duration per tone:

      

        
Example 17
if (sender.dtmf) {
    var duration = 500;
    sender.dtmf.insertDTMF("1234", duration);
} else
    log("DTMF function not available");

      
Send the DTMF signal "1234", and light up the active key using
        lightKey(key) while the tone is playing (assuming that
        lightKey("") will darken all the keys):

      

        
Example 18
if (sender.dtmf) {
  sender.dtmf.ontonechange = function (e) {
      if (!e.tone)
          return;
      // light up the key when playout starts
      lightKey(e.tone);
      // turn off the light after tone duration
      setTimeout(lightKey, sender.duration, "");
  };
  sender.dtmf.insertDTMF("1234");
} else
    log("DTMF function not available");

      
Send a 1-second "1" tone followed by a 2-second "2" tone:

      

        
Example 19
if (sender.dtmf) {
  sender.dtmf.ontonechange = function (e) {
      if (e.tone == "1")
          sender.dtmf.insertDTMF("2", 2000);
  };
  sender.dtmf.isertDTMF("1", 1000);
} else
    log("DTMF function not available");

      
It is always safe to append to the tone buffer. This example appends before any tone playout has started as well as during playout.

      

        
Example 20
if (sender.dtmf) {
  sender.dtmf.insertDTMF("123");
  // append more tones to the tone buffer before playout has begun
  sender.dtmf.insertDTMF(sender.toneBuffer + "456");

  sender.dtmf.ontonechange = function (e) {
      if (e.tone == "1")
          // append more tones when playout has begun
          sender.dtmf.insertDTMF(sender.toneBuffer + "789");
  };
} else
    log("DTMF function not available");

      
Send the DTMF signal "123" and abort after sending "2".

      

        
Example 21
if (sender.dtmf) {
  sender.dtmf.ontonechange = function (e) {
      if (e.tone == "2")
          // empty the buffer to not play any tone after "2"
          sender.dtmf.insertDTMF("");
  };
  sender.dtmf.insertDTMF("123");
} else
    log("DTMF function not available");

    

    
  


  

    
    
12. Error Handling
    

    
This section and its subsections extend the list of Error subclasses defined in [ECMASCRIPT-6.0] following the pattern for NativeError in section 19.5.6 of that specification. Assume the following:

    

    

      
12.1 ECMAScript 6 Terminology
      

      
The following terms used in this section are defined in [ECMASCRIPT-6.0].

      

        
          

            Term/Notation
            Section in [ECMASCRIPT-6.0]
          

        
        
          

            Type(X)
            6
          

          

            intrinsic object
            6.1.7.4
          

          

            [[ErrorData]]
            19.5.1
          

          

            internal slot
            6.1.7.2
          

          

            NewTarget
            various uses, but no definition
          

          

            active function object
            8.3
          

          

            OrdinaryCreateFromConstructor()
            9.1.14
          

          

            ReturnIfAbrupt()
            6.2.2.4
          

          

            Assert
            5.2
          

          

            String
            4.3.17-19, depending on context
          

          

            PropertyDescriptor
            6.2.4
          

          

            [[Value]]
            6.1.7.1
          

          

            [[Writable]]
            6.1.7.1
          

          

            [[Enumerable]]
            6.1.7.1
          

          

            [[Configurable]]
            6.1.7.1
          

          

            DefinePropertyOrThrow()
            7.3.7
          

          

            abrupt completion
            6.2.2
          

          

            ToString()
            7.1.12
          

          

            [[Prototype]]
            9.1
          

          

            %Error%
            19.5.1
          

          

            Error
            19.5
          

          

            %ErrorPrototype%
            19.5.3
          

          

            Object.prototype.toString
            19.1.3.6
          

        
      

    


    

      
12.2 RTCError Object
      


      

        
12.2.1 RTCError Constructor
        

        
The RTCError Constructor is the %RTCError% intrinsic object. When RTCError is called as a function rather than as a constructor, it creates and initializes a new
          RTCError object. A call of the object as a function is equivalent to calling it as a constructor with the same arguments. Thus the function call RTCError(...) is equivalent to the object creation expression new
        RTCError(...) with the same arguments.
        

        
The RTCError constructor is designed to be subclassable. It may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified RTCError behaviour must include a super call to the
          RTCError constructor to create and initialize the subclass instance with an [[ErrorData]] internal slot.


        

          
12.2.1.1 TODO errorDetailEnum
          

          
TODO - make a enum for all the error details? Is the enum OK for extending?
          

          

          

        


        

          
12.2.1.2 RTCError ( errorDetail, message )
          

          
When the RTCError function is called with arguments errorDetail and message the following steps are taken:

          
    
            
  1. If NewTarget is undefined, let newTarget be the active function object, else let newTarget be NewTarget.
            
    2. 
            
  2. Let O be OrdinaryCreateFromConstructor(newTarget,
              "%RTCErrorPrototype%", «[[ErrorData]]» ).
            
    3. 
            
  3. ReturnIfAbrupt(O).
    4. 
            
  4. If errorDetail is not undefined, then
              
      
                
    1. Let errorDetailDesc be the PropertyDescriptor{[[Value]]: errorDetail, [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false}.
      2. 
                
    2. Let cStatus be DefinePropertyOrThrow(O, "
                  errorDetail", errorDetailDesc).
      3. 
                
    3. Assert: eStatus is not an abrupt completion.
      4. 
              
    
            
    5. 
            
  5. If message is not undefined, then
              
      
                
    1. Let msg be ToString(message).
      2. 
                
    2. Let msgDesc be the PropertyDescriptor{[[Value]]:
                  msg, [[Writable]]: true, [[Enumerable]]:
                  false, [[Configurable]]: true}.
      3. 
                
    3. Let mStatus be DefinePropertyOrThrow(O, "
                  message", msgDesc).
      4. 
                
    4. Assert: mStatus is not an abrupt completion.
      5. 
              
    
            
    6. 
            
  6. Return O.
    7. 
          

        

      


      

        
12.2.2 Properties of the RTCError Constructor
        

        
The value of the [[Prototype]] internal slot of the
          RTCError
           constructor is the intrinsic object %Error%.

        
Besides the length property (whose value is 1), the RTCError
           constructor has the following properties:


        

          
12.2.2.1 RTCError.prototype
          

          
The initial value of RTCError.prototype is the RTCError
          prototype object. This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

        

      


      

        
12.2.3 Properties of the RTCError Prototype Object
        

        
The RTCError
           prototype object is an ordinary object. It is not an Error instance and does not have an [[ErrorData]] internal slot.

        
The value of the [[Prototype]] internal slot of the
          RTCError
           prototype object is the intrinsic object
          %ErrorPrototype%.


        

          
12.2.3.1 RTCError.prototype.constructor
          

          
The initial value of the constructor property of the prototype for the RTCError
             constructor is the intrinsic object %RTCError%.

        


        

          
12.2.3.2 RTCError.prototype.errorDetail
          

          
The initial value of the errorDetail property of the prototype for the RTCError
             constructor is the empty String.

        


        

          
12.2.3.3 RTCError.prototype.sdpLineNumber
          

          
The initial value of the sdpLineNumber property of the prototype for the RTCError
             constructor is 0.

        


        

          
12.2.3.4 RTCError.prototype.httpRequestStatusCode
          

          
The initial value of the httpRequestStatusCode property of the prototype for the RTCError
             constructor is 0.

        


        

          
12.2.3.5 RTCError.prototype.message
          

          
The initial value of the message property of the prototype for the
            RTCError
             constructor is the empty String.

        


        

          
12.2.3.6 RTCError.prototype.name
          

          
The initial value of the name property of the prototype for the RTCError constructor is
            "RTCError".

        

      


      

        
12.2.4 Properties of RTCError Instances
        

        
RTCError
           instances are ordinary objects that inherit properties from the RTCError
           prototype object and have an [[ErrorData]] internal slot whose value is undefined. The only specified use of [[ErrorData]] is by Object.prototype.toString ([
          ECMASCRIPT-6.0], section 19.1.3.6) to identify instances of Error or its various subclasses.

      

      

        
Note

        

          The following will need to be updated when we finish out the error definitions.
        

      

      
The following interface is defined for cases when an RTCError is raised as an event:

      

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


        

          
Constructors

          

            
RTCErrorEvent

            

              
Constructs a new
                RTCErrorEvent
                .

              

                
                  

                    Parameter
                    Type
                    Nullable
                    Optional
                    Description
                  

                  

                    type
                    DOMString
                    ✘
                    ✘
                    
                  

                  

                    eventInitDict
                    
                      RTCErrorEventInit
                    ✘
                    ✘
                    
                  

                
              

            

          

        


        

          
Attributes

          

            
error of type RTCError, readonly ,
            nullable

            

              
The RTCError
                 describing the error that triggered the event (if any).

            

          

        

      

      

        
dictionary RTCErrorEventInit : EventInit {
    RTCError? error = null;
};


        

          
Dictionary RTCErrorEventInit
          Members

          

            
error of type RTCError, nullable,
            defaulting to null

            

              
The RTCError
                 describing the error associated with the event (if any)

            

          

        

      

    

  


  

    
    
13. Event summary
    

    
This section is non-normative.

    
The following events fire on RTCDataChannel
      
      objects:

    

      
        

          Event name
          Interface
          Fired when...
        

      
      
        

          open
          Event
          
            The RTCDataChannel
             object's underlying data
            transport has been established (or re-established).
          
        

        

          message
          MessageEvent [
            webmessaging]
          A message was successfully received.
        

        

          bufferedamountlow
          Event
          The RTCDataChannel
             object's
            bufferedAmount
            
            decreases from above its bufferedAmountLowThreshold
             to less than or equal to its bufferedAmountLowThreshold
            .
        

        

          error
          ErrorEvent
            
          
          Any error occured from the data channel.
        

        

          close
          Event
          
            The RTCDataChannel
             object's underlying data
            transport has bee closed.
          
        

      
    

    
The following events fire on RTCPeerConnection
      
      objects:

    

      
        

          Event name
          Interface
          Fired when...
        

      
      
        

          connecting
          Event
          
            

              
Issue 7

              
TODO

            

          		
        

        
        

          track
          RTCTrackEvent
            
          
          A new incoming MediaStreamTrack has been created, and an associated RTCRtpReceiver has been added to the set of receivers.
        

        

          negotiationneeded
          Event
          The browser wishes to inform the application that session negotiation needs to be done (i.e. a createOffer call followed by setLocalDescription).
          
        

        

          signalingstatechange
          Event
          
            The signaling state has changed. This state change is the result of either setLocalDescription
             or
            setRemoteDescription
             being invoked.
          
        

        

          iceconnectionstatechange
          Event
          
            The RTCPeerConnection's ICE connection state has changed.
          
        

        

          icegatheringstatechange
          Event
          
            The RTCPeerConnection's ICE gathering state has changed.
          
        

        

          icecandidate
          RTCPeerConnectionIceEvent
            
          
          A new RTCIceCandidate
             is made available to the script.
        

        

          connectionstatechange
          Event
          
            The RTCPeerConnection connectionState has changed.
          
        

        

          icecandidateerror
          RTCPeerConnectionIceErrorEvent
            
          
          A failure occured when gathering ICE candidates.
        

        

          datachannel
          RTCDataChannelEvent
            
          
          A new RTCDataChannel
             is dispatched to the script in response to the other peer creating a channel.
        

        

          isolationchange
          Event
          A new Event is dispatched to the script when the isolated attribute on a MediaStreamTrack changes.
          
        

        

          fingerprintfailure
          Event
          
            The RTCPeerConnection's DTLS Certificate did not match any of the fingerprints in the SDP.
          
        

      
    

    
The following events fire on RTCDTMFSender
      
      objects:

    

      
        

          Event name
          Interface
          Fired when...
        

      
      
        

          tonechange
          RTCDTMFToneChangeEvent
            
          
          The RTCDTMFSender
             object has either just begun playout of a tone (returned as the tone
             attribute) or just ended playout of a tone (returned as an empty value in the
            tone
            
            attribute).
        

      
    

    
The following events fire on RTCIceTransport
      
      objects:

    

      
        

          Event name
          Interface
          Fired when...
        

      
      
        

          statechange
          Event
          The RTCIceTransport
             state changes.
        

        

          gatheringstatechange
          Event
          The RTCIceTransport
             gathering state changes.
          
        

        

          selectedcandidatepairchange
          Event
          The RTCIceTransport
            's selected candidate pair changes.
          
        

      
    

    
The following events fire on RTCDtlsTransport
      
      objects:

    

      
        

          Event name
          Interface
          Fired when...
        

      
      
        

          statechange
          Event
          The RTCDtlsTransport
             state changes.
        

      
    

  


  

    
    
14. Privacy and Security Considerations
    

    
This section is non-normative.

    
This section is non-normative; it specifies no new behaviour, but instead summarizes information already present in other parts of the specification. The overall security considerations of the general set of APIs and protocols used in WebRTC are described in [
      RTCWEB-SECURITY-ARCH].


    

      
14.1 Impact on same origin policy
      

      
This document extends the Web platform with the ability to set up real time, direct communication between browsers and other devices, including other browsers.

      
This means that data and media can be shared between applications running in different browsers, or between an application running in the same browser and something that is not a browser, something that is an extension to the usual barriers in the Web model against sending data between entities with different origins.

      
The WebRTC specification provides no user prompts or chrome indicators for communication; it assumes that once the Web page has been allowed to access media, it is free to share that media with other entities as it chooses. Peer-to-peer exchanges of data view WebRTC datachannels can thus occur without any user explicit consent or involvement, similarly as a server-mediated exchange (e.g. via Web Sockets) could occur without user involvement.
      

      
The peerIdentity
         mechanism loads and executes JavaScript code from a third-party server acting as an identity provider. That code is executed in a separate JavaScript realm and does not affect the protections afforded by the same origin policy.

    


    

      
14.2 Revealing IP addresses
      

      
Even without WebRTC, the Web server providing a Web application will know the public IP address to which the application is delivered. Setting up communications exposes additional information about the browser’s network context to the web application, and may include the set of (possibly private) IP addresses available to the browser for WebRTC use. Some of this information has to be passed to the corresponding party to enable the establishment of a communication session.
      

      
Revealing IP addresses can leak location and means of connection; this can be sensitive. Depending on the network environment, it can also increase the fingerprinting surface and create persistent cross-origin state that cannot easily be cleared by the user.

      
A connection will always reveal the IP addresses proposed for communication to the corresponding party. The application can limit this exposure by choosing not to use certain addresses using the settings exposed by the RTCIceTransportPolicy dictionary, and by using relays (for instance TURN servers) rather than direct connections between participants. One will normally assume that the IP address of TURN servers is not sensitive information. These choices can for instance be made by the application based on whether the user has indicated consent to start a media connection with the other party.

      
Mitigating the exposure of IP addresses to the application itself requires limiting the IP addresses that can be used, which will impact the ability to communicate on the most direct path between endpoints. Browsers are encouraged to provide appropriate controls for deciding which IP addresses are made available to applications, based on the security posture desired by the user. The choice of which addresses to expose is controlled by local policy (see [RTCWEB-IP-HANDLING] for details).
      

    


    

      
14.3 Impact on local network
      

      
Since the browser is an active platform executing in a trusted network environment (inside the firewall), it is important to limit the damage that the browser can do to other elements on the local network, and it is important to protect data from interception, manipulation and modification by untrusted participants.

      
Mitigations include:

      
      
These measures are specified in the relevant IETF documents.

    


    

      
14.4 Confidentiality of Communications
      

      
The fact that communication is taking place cannot be hidden from adversaries that can observe the network, so this has to be regarded as public information.

      
A mechanism, peerIdentity
        , is provided that gives Javascript the option of requesting media that the same javascript cannot access, but can only be sent to certain other entities.

    


    

      
14.5 Persistent information exposed by WebRTC
      

      
As described above, the list of IP addresses exposed by the WebRTC API can be used as a persistent cross-origin state.

      
Beyond IP addresses, the WebRTC API exposes information about the underlying media system via the RTCRtpSender.getCapabilities and RTCRtpReceiver.getCapabilities methods, including detailed and ordered information about the codecs that the system is able to produce and consume. A subset of that information is likely to be represented in the SDP session descriptions generated, exposed and transmitted during session
      negotiation. That information is in most cases persistent across time and origins, and increases the fingerprint surface of a given device.

      
If set, the configured default ICE servers exposed by defaultIceServers on
        RTCPeerConnection instances also provides persistent across time and origins information which increases the fingerprinting surface of a given browser.

      
When establishing DTLS connections, the WebRTC API can generate certificates that can be persisted by the application (e.g. in IndexedDB). These certificates are not shared across origins, and get cleared when persistent storage is cleared for the origin.

    

  

  

  

    
    
15. Change Log
    

    
This section will be removed before publication.

    
    
    
Changes since November 23, 2016

    
    
      
  1. [#899] Make stats MTI, remove overlap with stats spec
    2. 
      
  2. [#920] Remove ICE Agent text from RTCPeerConnection due to the new RTCICETransport objects.
    3. 
      
  3. [#937] Define what happens when transceiver.stop() is called.
    4. 
      
  4. [#938] Define what happens when setDirection() is called.
    5. 
      
  5. [#939] Remove "stopped" from removeTrack() and immediately stop sender.
    6. 
      
  6. [#940] Remove "stopped" from close, insertDTMF, and replaceTrack.
      
    7. 
      
  7. [#944] Clarify that sender does not send if sender.track is set to null.
    8. 
      
  8. [#949] Give legacy callbacks RTCSessionDescriptionInit so they can modify SDP.
    9. 
      
  9. [#956] Add API for setting QoS priority of data channels.
    10. 
      
  10. [#960] Allow replaceTrack(null)
    11. 
      
  11. [#963] Split transceiver direction into "direction" and "currentDirection"
      
    12. 
      
  12. [#966] setParameters rejects with InvalidStateError if transceiver.stopped is true.
    13. 
      
  13. [#968] Add ufrag to IceCandidate and use IceCandidate for end-of-candidates.
    14. 
      
  14. [#970] Clarify that setParameters cannot add or remove simulcast encodings.
    15. 
      
  15. [#972, #973] Add generic Error Object that can hold detailed error information.
    16. 
      
  16. [#936, #953, #967] Editorial: remove old in-spec issue text, update JSEP references, update hold examples, fix section titles
    17. 
    

    
Changes since September 13, 2016

    
    
      
  1. [#738] Add ability to get fingerprints of an RTCCertificate
      
    2. 
      
  2. [#783] Clarify supported DTMF characters
    3. 
      
  3. [#785] Reject invalid DTMF characters when inserted
    4. 
      
  4. [#786] If track is ended or muted, send silence for audio or black frame for video
    5. 
      
  5. [#790] Add checks that verify that a candidate matches a remote media decription
    6. 
      
  6. [#791] Add text that fires the 'connectionstatechange' event
      
    7. 
      
  7. [#793] Define DTMF tone attribute and make it required
    8. 
      
  8. [#796] Language cleanup around use of MediaTrackSettings
      
    9. 
      
  9. [#797] Clarify when negotiation-needed flag is cleared
    10. 
      
  10. [#804] Clarify that JSEP is normative in some cases; also numerous small editorial fixes
    11. 
      
  11. [#805] Reduce insertDTMF max duration from 8000 ms to 6000 ms
      
    12. 
      
  12. [#807] Clarify that empty string in DTMFToneChangeEvent indicates that the previous tones (plural) have completed.
    13. 
      
  13. [#809] Clarify that InvalidStateError is thrown if insertDTMF is called on a stopped sender.
    14. 
      
  14. [#815] Change IceConnectionState to match PeerConnection state in certain edge cases.
    15. 
      
  15. [#833, #865, #884, #904] Editorial: update JSEP references
      
    16. 
      
  16. [#835] Add definition link for NN and disallow SDP modification
      
    17. 
      
  17. [#837] Have insertDTMF validate toneBuffer before returning.
      
    18. 
      
  18. [#840] Remove reference to IANA registry for Statistics
    19. 
      
  19. [#844] Throw InvalidAccessError if removeTrack is called with invalid sender
    20. 
      
  20. [#847] Specify how to handle invalid data channel IDs, or lack of IDs.
    21. 
      
  21. [#851] Editorial: Fix wording for insertDTMF
    22. 
      
  22. [#852] Remove insertDTMF's duration and interToneGap attributes
      
    23. 
      
  23. [#853] Make insertDTMF tone string normalization mandatory
      
    24. 
      
  24. [#855] Clarify that insertDTMF's DTMFToneChangeEvent also requires toneBuffer to be empty in order to fire
    25. 
      
  25. [#860] More clarification around when removeTrack should throw an exception, now considering rollback as well
    26. 
      
  26. [#861] Clarify what setConfiguration changes
    27. 
      
  27. [#864] Define channel member of RTCDataChannelEventInit and make it required
    28. 
      
  28. [#871] Remove ability to modify RID via addTrack()
    29. 
      
  29. [#872] Pass peer identity to IdP via new RTCIdentityProviderOptions
      
    30. 
      
  30. [#875, #893] Major restructuring of createOffer and createAnswer to eliminate race conditions
    31. 
      
  31. [#877] Store RTCConfiguration so getConfiguration can return it
      
    32. 
      
  32. [#880, #896] Clean up definition of expires in certificates
      
    33. 
      
  33. [#882] Split gathering state variables into two types, gathering and gatherer, and clean up descriptions of values for each
      
    34. 
      
  34. [#883] Clarify that insertDTMF interToneGap is in milliseconds
      
    35. 
      
  35. [#895] Add steps in "setting a description" for rolling back transceivers.
      
    36. 
      
  36. [#900] Reject incoming tracks using transceiver.stop()
    37. 
      
  37. [#913] Overhaul NN text while adjusting it to key off transceivers
      
    38. 
      
  38. [#919] Remove incorrect statement related to IP leaking issue
      
    39. 
      
  39. [#929] Have RTCSessionDescription's sdp member default to "" 
    40. 
      
  40. [#863, #870, #890, #892, #911, #912, #915, #926, #928, #935] Editorial: typos, links, dead text, WebIDL, Travis, etc.
    41. 
    

    
Changes since July 22, 2016

    
    
      
  1. [#713] Missing destruction sequence for ICE Agent
    2. 
      
  2. [#730] Revised WebRTC 1.0 RTCIceTransportState transition diagram
      
    3. 
      
  3. [#722] How setDirection interacts with active/inactive sender/receivers
      
    4. 
      
  4. [#716] Improve error handling for IdP proxy interactions
    5. 
      
  5. [#719] The IdP environment can be spoofed
    6. 
      
  6. [#733] Clarification on RTX in Codec Capabilities/Parameters
    7. 
      
  7. [#734] RTCRtpEncodingParameters attribute to turn on/off sending CN/DTX
      
    8. 
      
  8. [#737] Fix mistakes in examples
    9. 
      
  9. [#739] Replace set of senders/receivers/transceivers with algorithms
      
    10. 
      
  10. [#721] Specify the synchronous and queued steps for addIceCandidate
      
    11. 
      
  11. [#759] Clarification on receipt of multiple RTP encodings
    12. 
      
  12. [#758] Support replaceTrack with the previous track ended
    13. 
      
  13. [#745] Add steps to createOffer and explicitly specify what is queued
      
    14. 
      
  14. [#762] Remove closed check from addIceCandidate steps (covered by enqueue steps)
    15. 
      
  15. [#750] RTCIdentityProviderGlobalScope needs Exposed attributes
    16. 
      
  16. [#752] Add steps to createAnswer and explicitly specify what is queued
      
    17. 
      
  17. [#756] Integrate queueing into the setLocal/RemoteDescription steps
      
    18. 
      
  18. [#765] Adding more detail to the definition of the ICE `disconnected` state.
      
    19. 
      
  19. [#778] Remove void conformance requirement on interToneGap
    20. 
      
  20. [#779] Make duration and interToneGap attributes unsigned long
    21. 
    

    
Changes since May 13, 2016

    
    
      
  1. [#640, #641, #659, #679, #680, #681, #682, #686, #694, #696, #697, #707, #708, #711] General editorial fixes
    2. 
      
  2. [#642] Editorial: make last arg of addTransceiver optional
    3. 
      
  3. [#643] Document defaultIceServers as source of fingerprinting
    4. 
      
  4. [#646] Create table of RTCRtpEncodingParameters for RtpSender/RtpReceiver
      
    5. 
      
  5. [#648] Clarify MIME (media/sub-) type
    6. 
      
  6. [#649] Example of how to do hold
    7. 
      
  7. [#662] Clarify effect of RTCRtpReceiver.track.stop()
    8. 
      
  8. [#663] Define a 7XX STUN error code
    9. 
      
  9. [#665] Clarify when setDirection() acts
    10. 
      
  10. [#666] Clarify that transports can be null
    11. 
      
  11. [#676] Transceiver.stop() causes negotiationneeded to be set
    12. 
      
  12. [#677] Clean up rtcpTransport description
    13. 
      
  13. [#701] In addTrack, mention that MSID of new track is added
    14. 
      
  14. [#702, #704] Define algs for creating sender/receiver/transceiver, then use them in addTrack() and addTransceiver()
    15. 
      
  15. [#725] Change 'process to apply candidate' to 'add the ICE candidate'
      
    16. 
    

    
Changes since February 15, 2016

    
    
      
  1. [#475] Definition of Active for an RTCRtpReceiver
    2. 
      
  2. [#500] Reserve and use RangeError for scaleResolutionDownBy < 1.0
      
    3. 
      
  3. [#504] Add getParameters() method to RTCRtpReceiver
    4. 
      
  4. [#509] RID unmodifiable in setParameters()
    5. 
      
  5. [#510] Gather spec text about the ICE Agent at one place
    6. 
      
  6. [#512] Use 'connection' as configuration target instead of User Agent
      
    7. 
      
  7. [#505] Add activateReceiver method to RTCRtpTransceiver
    8. 
      
  8. [#516] Support for DTMF tones A-D
    9. 
      
  9. [#499] Certificate API: add getAlgorithm method
    10. 
      
  10. [#507] Make the definition of addIceCandidate() more explicit
    11. 
      
  11. [#525] Add STUN Error Code reference
    12. 
      
  12. [#524] Add error codes reference (RTCPeerConnectionIceErrorEvent)
      
    13. 
      
  13. [#522] Let setting ice candidate pool size trigger start of gathering
      
    14. 
      
  14. [#519] Relation between local track and outgoing encoding
    15. 
      
  15. [#520] Add text about 'remote sources' and how they are stopped
    16. 
      
  16. [#527] Enable trickling of end-of-candidates through addIceCandidate
      
    17. 
      
  17. [#544] Remove "public" from ice transport policy
    18. 
      
  18. [#547] Datachannel label and protocol are USVString
    19. 
      
  19. [#552] Never close the RTCPeerConnection if setting a local/remote description fails
    20. 
      
  20. [#535] Update MID to be random values when not received in offer
    21. 
      
  21. [#553] Move 'closed' state from RTCSignalingState to RTCPeerConnectionState
      
    22. 
      
  22. [#557] Splitting apart RTCIceConnectionState and RTCIceTransportState
      
    23. 
      
  23. [#560] Changing from callback interface to dictionary for RTCIdentityProvider
      
    24. 
      
  24. [#574] Make RTCSessionDescription readonly, and createOffer return dictionary
      
    25. 
      
  25. [#577] Make RtpSender.track nullable
    26. 
      
  26. [#587] Defining how track settings are set for remote tracks
    27. 
      
  27. [#603] Add closed state and same state checks to update ice connection/gathering state steps
    28. 
      
  28. [#604] ReplaceTrack: Use sender's transceiver to determine if a 'simple track swap' is enough
    29. 
      
  29. [#606] RTCIceCandidate: Use nullable members in init dictionary to describe constructor behavior
    30. 
      
  30. [#466] Use an enum to describe directionality of RTP Stream
    31. 
      
  31. [#602] addTransceiver(): Throw a TypeError on a bogus track kind
    32. 
      
  32. [#610] Server cannot be reached - Issues with IPv6
    33. 
      
  33. [#611] Clarify ICE consent freshness feedback
    34. 
      
  34. [#618] Fix RTCPeerConnection legacy overloads
    35. 
      
  35. [#620] RTCRtpTransceiver: add setDirection and readonly direction attribute
      
    36. 
      
  36. [#625] Unifiy DTMF time with rtcweb WG
    37. 
      
  37. [#630] Add ICE candidate type references
    38. 
      
  38. [#635] pc.addTrack: Add kind check when reusing a sender and skip early returns
    39. 
      
  39. [#636] replaceTrack: Use 'transceiver kind' instead of track.kind (track may be null)
    40. 
    

    
Changes since January 26, 2016

    
    
      
  1. [#485] Update SOTD as the document is now quite stable and the group is looking for wide review
    2. 
      
  2. [#468, #335] Replace DOMError with DOMException
    3. 
      
  3. [#472, #319] Update error reports to align with existing DOM Errors
      
    4. 
      
  4. [#491, #479] Specify error when rejecting invalid SDP changes
    5. 
      
  5. [#462] Add PeerConnection.activateSender() and update early media example
      
    6. 
      
  6. [#434] Change setParameters call to be Async
    7. 
    

    
Changes since December 22, 2015

    
    
      
  1. [#179, #439] Document IP address leakage in RTCIceCandidate
    2. 
      
  2. [#439] Complete security considerations based on security questionnaire and IP address discussions #439
    3. 
      
  3. [#446] Non-nullable RTCTrackEvent args means Init dict members are required
      
    4. 
      
  4. [#449] Clarify flow of SDP exchanges (Update simple p2p example)
    5. 
      
  5. [#451] Clean up event handler attribute descriptions
    6. 
      
  6. [#452, #438] Make replaceTrack() handle "not sending yet" case
    7. 
      
  7. [#454] Add contributing source voice activity flag
    8. 
      
  8. [#455, #439] Add references to parsing stun/turn URLs section
    9. 
      
  9. [#456, #338] SDP changes between the createOffer and setLocalDescription (add JSEP reference)
    10. 
      
  10. [#459] Add non-normative ICE state transitions
    11. 
      
  11. [#460, #461] getRemoteCertificates() behavior in "new" and "connecting" states
    12. 
      
  12. [#465, #140] Use ErrorEvent as interface for events emitted by RTCDataChannel.onerror
      
    13. 
      
  13. [#469, #382, #373] Reject changes to peerIdentity and certificates in setConfiguration
      
    14. 
      
  14. [#474, #406] Define RTCIceTransport.component when RTP/RTCP mux is in use
      
    15. 
    

    
Changes since November 23, 2015

    
    
      
  1. [#353] Plan X: Add an API for using RID to do simulcast
    2. 
      
  2. [#365] Adding an accessor for the browser-configured ICE servers
    3. 
      
  3. [#398] Make RtpTransceiver.mid nullable and remove RtpSender.mid and RtpReceiver.mid
      
    4. 
      
  4. [#402, #391] Remove requirement about DTMF tones A-D
    5. 
      
  5. [#403, #377] Use positive values for AudioLevel
    6. 
      
  6. [#401, #267] Add bitrate definition
    7. 
      
  7. [#404] Remove 'Events on MediaStream' section (duplicates new text in Media Capture spec)
    8. 
      
  8. [#410, #328] Make RTCBundlePolicy Enum section normative
    9. 
      
  9. [#411, #408] Clarify component for IceTransport when RTP/RTCP mux is used
      
    10. 
      
  10. [#414] Define ReSpec processor for cross-reference to JSEP
    11. 
      
  11. [#418] Make degradationPreference per-sender instead of per-encoding
      
    12. 
      
  12. [#416] RTCRtpSender.replaceTrack() fixes (e.g. handle closed RTCPeerConnection)
      
    13. 
      
  13. [#421] Require sdp in RTCSessionDescription{,Init}
    14. 
      
  14. [#422] Remove confusing paragraph on fourth party interception
    15. 
      
  15. [#423] Add specific references to JSEP where possible
    16. 
      
  16. [#428] Don't create a default stream in 'dispatch a receiver' steps
      
    17. 
      
  17. [#429] Adding expires attribute to generateCertificate
    18. 
      
  18. [#430] Add maxFramerate knob for simulcast
    19. 
      
  19. [#432] Update RTCIceTransportPolicy
    20. 
      
  20. [#433] Use unsigned long ssrc in stats
    21. 
      
  21. [#424] Editorial: Distinguish states from their attribute representation
      
    22. 
    

    
Changes since October 6, 2015

    
    
      
  1. [#325] Adding additional members to RTCIceCandidate dictionary
    2. 
      
  2. [#327] Adding sha-256 to the certificate management options for RSA
      
    3. 
      
  3. [#342] Using DOMTimestamp for RTCCertificate::expires
    4. 
      
  4. [#293] Add RTCRtpTransceiver and PeerConnection.addMedia
    5. 
      
  5. [#366, #343] Use RTCDegradationPreference
    6. 
      
  6. [#374] Throw on too long label/protocol in createDataChannel()
    7. 
      
  7. [#266] Tidy up setLocal/RemoteDescription processing model
    8. 
      
  8. [#361] Adding setCodecPreferences to RTCRtpTransceiver
    9. 
      
  9. [#371] Add RtcpMuxPolicy
    10. 
      
  10. [#385, #312] Don't invoke public API in legacy function section
    11. 
      
  11. [#394, #393] don't throw on empty iceServers list
    12. 
    

    
Changes since September 22, 2015

    
    
      
  1. [#289, #153] Add way to set size of ICE candidate pool
    2. 
      
  2. [#256] Fix prose on getStats() wo/selector + move type check to sync section
      
    3. 
      
  3. [#242] Remove SyntaxError on malformed ICE candidate
    4. 
      
  4. [#284] Add icecandidateerror event for indicating ICE gathering errors
      
    5. 
      
  5. [#298] Add support for codec reordering and removal in RtpParameters
      
    6. 
      
  6. [#311] Fixing syntax for required RTCCertificate arguments
    7. 
      
  7. [#280] Add extra IceTransport read-only attributes and methods
    8. 
      
  8. [#291] Add PeerConnection.connectionState
    9. 
      
  9. [#300, #4, #6, #276] Add API to get SSRC and audio levels
    10. 
      
  10. [#301] Fix RTCStatsReport with object and maplike instead of getter
      
    11. 
      
  11. [#302] (Partly) removing interface use for RTCSessionDescription and RTCIceCandidate
      
    12. 
      
  12. [#314, #299] Update the operations queue to handle promises and closed signalling
    13. 
      
  13. [#273] Add a bunch of fields to RtpParameters and RtpEncodingParameters
      
    14. 
    

    
Changes since June 11, 2015

    
    
      
  1. [#234] Add RTCRtpParameters, RTCRtpSender.getParameters, and RTCRtpSender.setParameters
      
    2. 
      
  2. [#225] Support for pending and current SDP
    3. 
      
  3. [#229] Removing the weird optionality from RTCSessionDescription and its constructor.
    4. 
      
  4. [#235] Modernize getStats() with promises
    5. 
      
  5. [#243] Mark candidate property of RTCIceCandidateInit required
    6. 
      
  6. [#248] Fix error handling for certificate management
    7. 
      
  7. [#259] Change type of RtpEncodingParameters.priority to an enum
    8. 
      
  8. [#21, #262] Sort out 2119 MUSTs and SHOULDs
    9. 
      
  9. [#268] Add RtpEncodingParameters.maxBitrate
    10. 
      
  10. [#241] Add RtpSender.transport, RtpReceiver.transport, RTCDtlsTransport, RTCIceTransport, etc
    11. 
      
  11. [#224, #261] Sort out when responding PeerConnection reaches iceConnetionState completed
    12. 
      
  12. [#303] Replace track without renegotiation
    13. 
      
  13. [#269] Add RTCRtpSender.getCapabilities and RTCRtpReceiver.getCapabilities
      
    14. 
    

    
Changes since March 6, 2015

    
    
      
  1. [PR #167] Removed RTCPeerConnection.createDTMFSender and added RTCRtpSender.dtmf, along with corresponding examples.
    2. 
      
  2. [PR #184] RTCPeerConnection will NOT connect unless identity is verified.
      
    3. 
      
  3. [PR #27] Documenting practice with candidate events
    4. 
      
  4. [PR #203] Rewrote mitigations text for security considerations section
      
    5. 
      
  5. [PR #192] Added support for auth tokens. Fixes #190
    6. 
      
  6. [PR #207] Update ice config examples to use multiple urls and *s schemes
      
    7. 
      
  7. [PR #210] Optional RTCConfiguration in RTCPC constructor
    8. 
      
  8. [PR #171] Add RTCAnswerOptions (with common RTCOfferAnswerOptions dictionary)
      
    9. 
      
  9. [PR #178] Identity provider interface redesign
    10. 
      
  10. [PR #193] Add .mid property to sender/receiver. Fixes #191
    11. 
      
  11. [PR #218] Enqueue addIceCandidate
    12. 
      
  12. [PR #213 (1)] Rename updateIce() to setConfiguration()
    13. 
      
  13. [PR #213 (2)] Make RTCPeerConnection.setConfiguration() replace the existing configuration
    14. 
      
  14. [PR #214] Certificate management API (Bug 21880)
    15. 
      
  15. [PR #220] Clarify muted state (proposed fix for issue #139)
    16. 
      
  16. [PR #221] Define when RTCRtpReceivers are created and dispatced (issue #198)
    17. 
      
  17. [PR #215] Adding expires attribute to certificate management
    18. 
      
  18. [PR #233] Add a "bufferedamountlow" event
    19. 
    

    
Changes since December 5, 2014

    
    
      
  1. Properly define the negotiationneeded event, and its interactions with other API calls.
    2. 
      
  2. Add support for RTCRtpSender and RTCRtpReceiver.
    3. 
      
  3. Update misleading local/RemoteDescription attribute text.
    4. 
      
  4. Add RTCBundlePolicy.
    5. 
      
  5. All callback-based methods have been moved to a legacy section, and replaced by same-named overloads using Promises instead.
    6. 
      
  6. [PR #194] Added first version of Security Considerations (more work needed)
      
    7. 
      
  7. Updated identity provider structure.
    8. 
    

    
Changes since June 4, 2014

    
    
      
  1. Bug 25724: Allow garbage collection of closed PeerConnections
    2. 
      
  2. Bug 27214: Add onicegatheringstatechange event
    3. 
      
  3. Bug 26644: Fixing end of candidates event
    4. 
    

    
Changes since April 10, 2014

    
    
      
  1. Bug 25774: Mixed isolation
    2. 
    

    
Changes since April 10, 2014

    
    
      
  1. Bug 25855: Clarification about conformance requirements phrased as algorithms
      
    2. 
      
  2. Bug 25892: SignalingStateChange event should be fired only if there is a change in signaling state.
    3. 
      
  3. Bug 25152: createObjectURL used in examples is no longer supported by Media Capture and Streams.
    4. 
      
  4. Bug 25976: DTMFSender.insertDTMF steps should validate the values of duration and interToneGap.
    5. 
      
  5. Bug 25189: Mandatory errorCallback is missing in examples for getStats.
      
    6. 
      
  6. Bug 25840: Creating DataChannel with same label.
    7. 
      
  7. Updated comment above example ice state transitions (discussed in Bug 25257).
      
    8. 
      
  8. Updated insertDTMF() algorithm to ignore unrecognized characters (as discussed in bug 25977).
    9. 
      
  9. Made formatting of references to ice connection state consistent.
      
    10. 
      
  10. Made insertDTMF() throw on unrecognized characters (used to ignore).
      
    11. 
      
  11. Removed requestIdentity from RTCConfiguration and RTCOfferAnswerOptions. Removed RTCOfferAnswerOptions as a result.
    12. 
      
  12. Adding isolated property and associated event to MediaStreamTrack.
      
    13. 
    

    
Changes since March 21, 2014

    
    
      
  1. Changes to identity-related text:
        
      
          
    • Removed noaccess constraint
      • 
          
    • Add the ability to peerIdentity constrain RTCPeerConnection, which limits communication to a single peer
      • 
          
    • Change the way that the browser communicates with IdP to a message channel (http://www.w3.org/TR/webmessaging/#message-channels)
          
      • 
          
    • Improved error feedback from IdP interactions (added new events with more detailed context)
      • 
          
    • Changed the way that an IdP is able to request user login (LOGINNEEDED message)
      • 
        
    
      
    2. 
      
  2. Bug 25155: maxRetransmitTime is not the name of the SCTP concept it points to.
    3. 
    

    
Changes since January 27, 2014

    
    
      
  1. Refined identity assertion generation and validation.
    2. 
      
  2. Default DTMF gap changed from 50 to 70 ms.
    3. 
      
  3. Bug 24875: Examples in the WebRTC spec are not updated As per the modified API.
    4. 
    

    
Changes since August 30, 2013

    
    
      
  1. Make RTCPeerConnection close method be idempotent.
    2. 
      
  2. Clarified ICE server configuration could contain URI types other than STUN and TURN.
    3. 
      
  3. Changed the DTMF timing values.
    4. 
      
  4. Allow offerToReceiveAudio/video indicate number of streams to offer.
      
    5. 
      
  5. ACTION-98: Added text about clamping of maxRetransmitTime and maxRetransmits.
      
    6. 
      
  6. ACTION-88: Removed nullable types from dictionaries (added attribute default values for attributes that would be left uninitialized without the init dictionary present.
    7. 
      
  7. InvalidMediaStreamTrackError changed to InvalidParameter.
    8. 
      
  8. Fire NetworkError when the data transport is closed with an error.
      
    9. 
      
  9. Add an exception for data channel with trying to use existing code.
      
    10. 
      
  10. Change maxRetransmits to be an unsigned type.
    11. 
      
  11. Clarify state changes when ICE restarts.
    12. 
      
  12. Added InvalidStateError exception for operations on a RTCPeerConnection that is closed.
    13. 
      
  13. Major changes to Identity Proxy section.
    14. 
      
  14. (ACTION: 95) Moved IceTransports (constraint) to RTCConfiguration dictionary.
      
    15. 
      
  15. (ACTION: 95) Introduced RTCOfferAnswerOptions and RTCOfferOptions dictionaries.
      
    16. 
      
  16. (ACTION: 95) Removed constraints argument from addStream() (and removed IANA Constraints section).
    17. 
      
  17. Added validation of the RTCConfiguration dictionary argument(s).
    18. 
      
  18. Added getConfiguration() on RTCPeerConnection.
    19. 
    

    
Changes since June 3, 2013

    
    
      
  1. Removed synchronous section left-overs.
    2. 
      
  2. RTCIceServer now accepts multiple URLs.
    3. 
      
  3. Redefined the meaning of negotiated for DataChannel.
    4. 
      
  4. Made iceServers a sequence (instead of an Array).
    5. 
      
  5. Updated error reporting (to use DOMError and camel cased names).
    6. 
      
  6. Added success and failure callbacks to addIceCandidate().
    7. 
      
  7. Made local/remoteDescription attributes nullable.
    8. 
      
  8. Added username member to RTCIceServer dictionary.
    9. 
    

    
Changes since March 22, 2013

    
    
      
  1. Added IceRestart constraint.
    2. 
      
  2. Big updates on DataChannel API to use new channel setup procedures.
      
    3. 
    

    
Changes since Feb 22, 2013

    
    
      
  1. Example review: Updated DTMF and Stats examples. Added text about when to fire "negotiationneeded" event to align with examples.
    2. 
      
  2. Updated RTCPeerConnection state machine. Added a shared processing model for setLocalDescription()/setRemoteDescription().
    3. 
      
  3. Updated simple callflow to match the current API.
    4. 
    

    
Changes since Jan 16, 2013

    
    
      
  1. Initial import of Statistics API to version 2.
    2. 
      
  2. Integration of Statistics API version 2.5 started.
    3. 
      
  3. Updated Statistics API to match Boston/list discussions.
    4. 
      
  4. Extracted API extensions introduced by features, such as the P2P Data API, from the RTCPeerConnection API.
    5. 
      
  5. Updated DTMF algorithm to dispatch an event when insertDTMF() is called with an empty string to cancel future tones.
    6. 
      
  6. Updated DTMF algorithm to not cancel and reschedule if a playout task is running (only update toneBuffer and other values).
    7. 
    

    
Changes since Dec 12, 2012

    
    
      
  1. Changed AudioMediaStreamTrack to RTCDTMFSender and gave it its own section. Updated text to reflect most recent agreements. Also added examples section.
    2. 
      
  2. Replaced the localStreams and remoteStreams attributes with functions returning sequences of MediaStream objects.
    3. 
      
  3. Added spec text for attributes and methods adopted from the WebSocket interface.
      
    4. 
      
  4. Changed the state ENUMs and transition diagrams.
    5. 
      
  5. Aligned the data channel processing model a bit more with WebSockets (mainly closing the underlying transport).
    6. 
    

    
Changes since Nov 13, 2012

    
    
      
  1. Made some clarifications as to how operation queuing works, and fixed a few errors with the error handling description.
    2. 
      
  2. Introduced new representation of tracks in a stream (removed MediaStreamTrackList). Added algorithm for creating a track to represent an incoming network media component.
    3. 
      
  3. Renamed MediaStream.label to MediaStream.id (the definition needs some more work).
    4. 
    

    
Changes since Nov 03, 2012

    
    
      
  1. Added text describing the queuing mechanism for RTCPeerConnection.
      
    2. 
      
  2. Updated simple P2P example to include all mandatory (error) callbacks.
      
    3. 
      
  3. Updated P2P data example to include all mandatory (error) callbacks. Also added some missing RTC prefixes.
    4. 
    

    
Changes since Oct 19, 2012

    
    
      
  1. Clarified how createOffer() and createAnswer() use their callbacks.
      
    2. 
      
  2. Made all failure callbacks mandatory.
    3. 
      
  3. Added error object types, general error handling principles, and rules for when errors should be thrown.
    4. 
    

    
Changes since Sept 23, 2012

    
    
      
  1. Restructured the document layout and created separate sections for features like Peer-to-peer Data API, Statistics and Identity.
    2. 
    

    
Changes since Aug 16, 2012

    
    
      
  1. Replaced stringifier with serializer on RTCSessionDescription and RTCIceCandidate (used when JSON.stringify() is called).
    2. 
      
  2. Removed offer and createProvisionalAnswer arguments from the createAnswer() method.
    3. 
      
  3. Removed restart argument from the updateIce() method.
    4. 
      
  4. Made RTCDataChannel an EventTarget
    5. 
      
  5. Updated simple RTCPeerConnection example to match spec changes.
    6. 
      
  6. Added section about RTCDataChannel garbage collection.
    7. 
      
  7. Added stuff for identity proxy.
    8. 
      
  8. Added stuff for stats.
    9. 
      
  9. Added stuff peer and ice state reporting.
    10. 
      
  10. Minor changes to sequence diagrams.
    11. 
      
  11. Added a more complete RTCDataChannel example
    12. 
      
  12. Various fixes from Dan's Idp API review.
    13. 
      
  13. Patched the Stats API.
    14. 
    

    
Changes since Aug 13, 2012

    
    
      
  1. Made the RTCSessionDescription and RTCIceCandidate constructors take dictionaries instead of a strings. Also added detailed stringifier algorithm.
      
    2. 
      
  2. Went through the list of issues (issue numbers are only valid with HEAD at fcda53c460). Closed (fixed/wontfix): 1, 8, 10, 13, 14, 16, 18, 19, 22, 23, 24. Converted to notes: 4, 12. Updated: 9.
    3. 
      
  3. Incorporate changes
      proposed by Li Li.
      
    4. 
      
  4. Use an enum for DataChannelState and fix IDLs where using an optional argument also requires all previous optional arguments to have a default value.
      
    5. 
    

    
Changes since Jul 20, 2012

    
    
      
  1. Added RTC Prefix to names (including the notes below).
    2. 
      
  2. Moved to new definition of configuration and ice servers object.
    3. 
      
  3. Added correlating lines to candidate structure.
    4. 
      
  4. Converted setLocalDescription and setRemoteDescription to be asynchronous.
      
    5. 
      
  5. Added call flows.
    6. 
    

    
Changes since Jul 13, 2012

    
    
      
  1. Removed peer attribute from RTCPeerConnectionIceEvent (duplicates functionality of Event.target attribute).
    2. 
      
  2. Removed RTCIceCandidateCallback (no longer used).
    3. 
      
  3. Removed RTCPeerConnectionEvent (we use a simple event instead).
    4. 
      
  4. Removed RTCSdpType argument from setLocalDescription() and setRemoteDescription(). Updated simple example to match.
    5. 
    

    
Changes since May 28, 2012

    
    
      
  1. Changed names to use RTC Prefix.
    2. 
      
  2. Changed the data structure used to pass in STUN and TURN servers in configuration.
      
    3. 
      
  3. Updated simple RTCPeerConnection example (RTCPeerConnection constructor arguments; use icecandidate event).
    4. 
      
  4. Initial import of new Data API.
    5. 
      
  5. Removed some left-overs from the old Data Stream API.
    6. 
      
  6. Renamed "underlying data channel" to "underlying data transport". Fixed closing procedures. Fixed some typos.
    7. 
    

    
Changes since April 27, 2012

    
    
      
  1. Major rewrite of RTCPeerConnection section to line up with IETF JSEP draft.
      
    2. 
      
  2. Added simple RTCPeerConnection example. Initial update of RTCSessionDescription and RTCIceCandidate to support serialization and construction.
      
    3. 
    

    
Changes since 21 April 2012

    
    
      
  1. Moved MediaStream and related definitions to getUserMedia.
    2. 
      
  2. Removed section "Obtaining local multimedia content".
    3. 
      
  3. Updated getUserMedia() calls in examples (changes in Media Capture TF spec).
      
    4. 
      
  4. Introduced MediaStreamTrackList interface with support for adding and removing tracks.
    5. 
      
  5. Updated the algorithm that is run when RTCPeerConnection receives a stream (create new stream when negotiated instead of when data arrives).
      
    6. 
    

    
Changes since 12 January 2012

    
    
      
  1. Clarified the relation of Stream, Track, and Channel.
    2. 
    

    
Changes since 17 October 2011

    
    
      
  1. Tweak the introduction text and add a reference to the IETF RTCWEB group.
      
    2. 
      
  2. Changed the first argument to getUserMedia to be an object.
    3. 
      
  3. Added a MediaStreamHints object as a second argument to RTCPeerConnection.addStream.
      
    4. 
      
  4. Added AudioMediaStreamTrack class and DTMF interface.
    5. 
    

    
Changes since 23 August 2011

    
    
      
  1. Separated the SDP and ICE Agent into separate agents and added explicit state attributes for each.
    2. 
      
  2. Removed the send method from PeerConenction and associated callback function.
      
    3. 
      
  3. Modified MediaStream() constructor to take a list of MediaStreamTrack objects instead of a MediaStream. Removed text about MediaStream parent and child relationship.
    4. 
      
  4. Added abstract.
    5. 
      
  5. Moved a few paragraphs from the MediaStreamTrack.label section to the MediaStream.label section (where they belong).
    6. 
      
  6. Split MediaStream.tracks into MediaStream.audioTracks and MediaStream.videoTracks.
      
    7. 
      
  7. Removed a sentence that implied that track access is limited to LocalMediaStream.
      
    8. 
      
  8. Updated a few getUserMedia()-examples to use MediaStreamOptions.
    9. 
      
  9. Replaced calls to URL.getObjectURL() with URL.createObjectURL() in example code.
    10. 
      
  10. Fixed some broken getUserMedia() links.
    11. 
      
  11. Introduced state handling on MediaStreamTrack (removed state handling from MediaStream).
    12. 
      
  12. Reintroduced onended on MediaStream to simplify checking if all tracks are ended.
    13. 
      
  13. Aligned the MediaStreamTrack ended event dispatching behavior with that of MediaStream.
    14. 
      
  14. Updated the LocalMediaStream.stop() algorithm to implicitly use the end track algorithm.
    15. 
      
  15. Replaced an occurrence the term finished track with ended track (to align with rest of spec).
    16. 
      
  16. Moved (and extended) the explanation about track references and media sources from LocalMediaStream to MediaStreamTrack.
    17. 
    

  


  

    
    
A. Acknowledgements
    

    
The editors wish to thank the Working Group chairs and Team Contact, Harald Alvestrand, Stefan Håkansson, Erik Lagerway and Dominique Hazaël-Massieux, for their support. Substantial text in this specification was provided by many people including Martin Thomson, Harald Alvestrand, Justin Uberti, Eric Rescorla, Peter Thatcher, Jan-Ivar Bruaroey and Peter Saint-Andre. Dan Burnett would like to acknowledge the significant support received from Voxeo and Aspect during the development of this specification.

    
The RTCRtpSender and RTCRtpReceiver objects were initially described in the W3C ORTC CG, and have been adapted for use in this specification.

  



  

    
    
B. References
    


    

      
B.1 Normative references
      

      
[ECMASCRIPT-6.0]

        
Allen Wirfs-Brock. Ecma International. ECMA-262 6th Edition, The ECMAScript 2015 Language Specification. June 2015. Standard. URL: http://www.ecma-international.org/ecma-262/6.0/index.html
        
[FILEAPI]

        
Arun Ranganathan; Jonas Sicking. W3C. File API. 21 April 2015. W3C Working Draft. URL: https://www.w3.org/TR/FileAPI/
        
[FIPS-180-4]

        
U.S. Department of Commerce/National Institute of Standards and Technology. FIPS PUB 180-4 Secure Hash Standard. URL: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf
        
[GETUSERMEDIA]

        
Daniel Burnett; Adam Bergkvist; Cullen Jennings; Anant Narayanan; Bernard Aboba. W3C. Media Capture and Streams. 19 May 2016. W3C Candidate Recommendation. URL: https://www.w3.org/TR/mediacapture-streams/
        
[HIGHRES-TIME]

        
Ilya Grigorik; James Simonsen; Jatinder Mann. W3C. High Resolution Time Level 2. 1 November 2016. W3C Candidate Recommendation. URL: https://www.w3.org/TR/hr-time-2/
        
[HTML]

        
Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
        
[HTML5]

        
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. W3C. HTML5. 28 October 2014. W3C Recommendation. URL: https://www.w3.org/TR/html5/
        
[ICE]

        
J. Rosenberg. IETF. Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT) Traversal for Offer/Answer Protocols. April 2010. Proposed Standard. URL: https://tools.ietf.org/html/rfc5245
        
[JSEP]

        
Justin Uberti; Cullen Jennings; Eric Rescorla. IETF. Javascript Session Establishment Protocol. 21 October 2016. Active Internet-Draft. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-jsep/
        
[RFC2119]

        
S. Bradner. IETF. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
        
[RFC4566]

        
M. Handley; V. Jacobson; C. Perkins. IETF. SDP: Session Description Protocol. July 2006. Proposed Standard. URL: https://tools.ietf.org/html/rfc4566
        
[RFC4572]

        
J. Lennox. IETF. Connection-Oriented Media Transport over the Transport Layer Security (TLS) Protocol in the Session Description Protocol (SDP). July 2006. Proposed Standard. URL: https://tools.ietf.org/html/rfc4572
        
[RFC5389]

        
J. Rosenberg; R. Mahy; P. Matthews; D. Wing. IETF. Session Traversal Utilities for NAT (STUN). October 2008. Proposed Standard. URL: https://tools.ietf.org/html/rfc5389
        
[RFC5888]

        
G. Camarillo; H. Schulzrinne. IETF. The Session Description Protocol (SDP) Grouping Framework. June 2010. Proposed Standard. URL: https://tools.ietf.org/html/rfc5888
        
[RFC6236]

        
I. Johansson; K. Jung. IETF. Negotiation of Generic Image Attributes in the Session Description Protocol (SDP). May 2011. Proposed Standard. URL: https://tools.ietf.org/html/rfc6236
        
[RFC6464]

        
J. Lennox, Ed.; E. Ivov; E. Marocco. IETF. A Real-time Transport Protocol (RTP) Header Extension for Client-to-Mixer Audio Level Indication. December 2011. Proposed Standard. URL: https://tools.ietf.org/html/rfc6464
        
[RFC6465]

        
E. Ivov, Ed.; E. Marocco, Ed.; J. Lennox. IETF. A Real-time Transport Protocol (RTP) Header Extension for Mixer-to-Client Audio Level Indication. December 2011. Proposed Standard. URL: https://tools.ietf.org/html/rfc6465
        
[RFC6544]

        
J. Rosenberg; A. Keranen; B. B. Lowekamp; A. B. Roach. IETF. TCP Candidates with Interactive Connectivity Establishment (ICE). March 2012. Proposed Standard. URL: https://tools.ietf.org/html/rfc6544
        
[RFC7064]

        
S. Nandakumar; G. Salgueiro; P. Jones; M. Petit-Huguenin. IETF. URI Scheme for the Session Traversal Utilities for NAT (STUN) Protocol. November 2013. Proposed Standard. URL: https://tools.ietf.org/html/rfc7064
        
[RFC7065]

        
M. Petit-Huguenin; S. Nandakumar; G. Salgueiro; P. Jones. IETF. Traversal Using Relays around NAT (TURN) Uniform Resource Identifiers. November 2013. Proposed Standard. URL: https://tools.ietf.org/html/rfc7065
        
[RFC7675]

        
M. Perumal; D. Wing; R. Ravindranath; T. Reddy; M. Thomson. IETF. Session Traversal Utilities for NAT (STUN) Usage for Consent Freshness. October 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7675
        
[RTCWEB-ALPN]

        
M. Thomson. IETF. Application Layer Protocol Negotiation for Web Real-Time Communications. 23 July 2014. Active Internet-Draft. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-alpn/
        
[RTCWEB-AUDIO]

        
JM. Valin; C. Bran. IETF. WebRTC Audio Codec and Processing Requirements. 27 January 2014. Active Internet-Draft. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-audio/
        
[RTCWEB-DATA]

        
R. Jesup; S. Loreto; M. Tuexen. IETF. RTCWeb Data Channels. 21 October 2013. Active Internet-Draft. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-data-channel/
        
[RTCWEB-DATA-PROTOCOL]

        
R. Jesup; S. Loreto; M. Tuexen. IETF. RTCWeb Data Channel Protocol. 21 October 2013. Active Internet-Draft. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-data-protocol/
        
[RTCWEB-RTP]

        
C. Perkins; M. Westerlund; J. Ott. IETF. Web Real-Time Communication (WebRTC): Media Transport and Use of RTP. 16 December 2013. Active Internet-Draft. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-rtp-usage/
        
[RTCWEB-SECURITY-ARCH]

        
Eric Rescorla. IETF. WebRTC Security Architecture. 22 January 2014. Active Internet-Draft. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-security-arch/
        
[RTCWEB-TRANSPORT]

        
H. Alvestrand. IETF. Transports for RTCWEB. 22 January 2014. Active Internet-Draft. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-transports/
        
[SDP]

        
J. Rosenberg; H. Schulzrinne. IETF. An Offer/Answer Model with Session Description Protocol (SDP). June 2002. Proposed Standard. URL: https://tools.ietf.org/html/rfc3264
        
[TRAM-TURN-THIRD-PARTY-AUTHZ]

        
T. Reddy; P. Patil; R. Ravindranath; J. Uberti. IETF. Session Traversal Utilities for NAT (STUN) Extension for Third Party Authorization. 25 February 2015. Internet Draft (work in progress). URL: https://datatracker.ietf.org/doc/draft-ietf-tram-turn-third-party-authz/
        
[TSVWG-RTCWEB-QOS]

        
S. Dhesikan; C. Jennings; D. Druta; P. Jones; J. Polk. IETF. DSCP and other packet markings for RTCWeb QoS. 12 November 2014. Internet Draft (work in progress). URL: https://datatracker.ietf.org/doc/draft-ietf-tsvwg-rtcweb-qos
        
[WEBIDL-1]

        
Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. Web IDL. 15 December 2016. W3C Working Draft. URL: https://www.w3.org/TR/WebIDL-1/
        
[WEBRTC-STATS]

        
Harald Alvestrand; Varun Singh. W3C. Identifiers for WebRTC's Statistics API. 14 December 2016. W3C Working Draft. URL: https://www.w3.org/TR/webrtc-stats/
        
[WEBWORKERS]

        
Ian Hickson. W3C. Web Workers. 24 September 2015. W3C Working Draft. URL: https://www.w3.org/TR/workers/
        
[WebCryptoAPI]

        
Mark Watson. W3C. Web Cryptography API. 15 December 2016. W3C Proposed Recommendation. URL: https://www.w3.org/TR/WebCryptoAPI/
        
[X509V3]

        
ITU-T Recommendation X.509 version 3 (1997). "Information Technology - Open Systems Interconnection - The Directory Authentication Framework"  ISO/IEC 9594-8:1997.
        
[X690]

        
Recommendation X.690 — Information Technology — ASN.1 Encoding Rules — Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules (DER). International Telecommunication Union.
        
[webmessaging]

        
Ian Hickson. W3C. HTML5 Web Messaging. 19 May 2015. W3C Recommendation. URL: https://www.w3.org/TR/webmessaging/
        

      

    


    

      
B.2 Informative references
      

      
[IANA-RTP-2]

        
IANA. RTP Payload Format media types. URL: http://www.iana.org/assignments/rtp-parameters/rtp-parameters.xhtml#rtp-parameters-2
        
[INDEXEDDB]

        
Nikunj Mehta; Jonas Sicking; Eliot Graff; Andrei Popescu; Jeremy Orlow; Joshua Bell. W3C. Indexed Database API. 8 January 2015. W3C Recommendation. URL: https://www.w3.org/TR/IndexedDB/
        
[RFC3550]

        
H. Schulzrinne; S. Casner; R. Frederick; V. Jacobson. IETF. RTP: A Transport Protocol for Real-Time Applications. July 2003. Internet Standard. URL: https://tools.ietf.org/html/rfc3550
        
[RFC3890]

        
M. Westerlund. IETF. A Transport Independent Bandwidth Modifier for the Session Description Protocol (SDP). September 2004. Proposed Standard. URL: https://tools.ietf.org/html/rfc3890
        
[RFC5285]

        
D. Singer; H. Desineni. IETF. A General Mechanism for RTP Header Extensions. July 2008. Proposed Standard. URL: https://tools.ietf.org/html/rfc5285
        
[RFC5322]

        
P. Resnick, Ed.. IETF. Internet Message Format. October 2008. Draft Standard. URL: https://tools.ietf.org/html/rfc5322
        
[RFC5506]

        
I. Johansson; M. Westerlund. IETF. Support for Reduced-Size Real-Time Transport Control Protocol (RTCP): Opportunities and Consequences. April 2009. Proposed Standard. URL: https://tools.ietf.org/html/rfc5506
        
[RTCWEB-IP-HANDLING]

        
Guo-wei Shieh; Justin Uberti. IETF. WebRTC IP Address Handling Recommendations. 20 March 2016. Active Internet-Draft. URL: https://datatracker.ietf.org/doc/draft-ietf-rtcweb-ip-handling/
        
[RTCWEB-OVERVIEW]

        
H. Alvestrand. IETF. Overview: Real Time Protocols for Brower-based Applications. 14 February 2014. Active Internet-Draft. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-overview/
        
[RTCWEB-SECURITY]

        
Eric Rescorla. IETF. Security Considerations for WebRTC. 22 January 2014. Active Internet-Draft. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-security/
        
[STUN-PARAMETERS]

        
IETF. IANA. STUN Error Codes. April 2011. IANA Parameter Assignment. URL: http://www.iana.org/assignments/stun-parameters/stun-parameters.xhtml#stun-parameters-6
        
[TRICKLE-ICE]

        
E. Ivov; E. Rescorla; J. Uberti. IETF. Trickle ICE: Incremental Provisioning of Candidates for the Interactive Connectivity Establishment (ICE) Protocol. 7 February 2014. Internet Draft (work in progress). URL: http://datatracker.ietf.org/doc/draft-ietf-mmusic-trickle-ice
        
[WEBSOCKETS-API]

        
Ian Hickson. W3C. The WebSocket API. 20 September 2012. W3C Candidate Recommendation. URL: https://www.w3.org/TR/websockets/
        
[XMLHttpRequest]

        
Anne van Kesteren; Julian Aubourg; Jungkee Song; Hallvord Steen et al. W3C. XMLHttpRequest Level 1. 6 October 2016. W3C Note. URL: https://www.w3.org/TR/XMLHttpRequest/