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 http://www.w3.org/TR/.

This document is neither complete nor stable, and as such is not yet suitable for commercial implementation. However, early experimentation is encouraged. The API is based on preliminary work done in the WHATWG. The Web Real-Time Communications Working Group expects this specification to evolve significantly based on:

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.

Table of Contents

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 with the exception of the RTCIdentityProvider interface which is used by the user agent but not implemented by the user agent.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.

3. Terminology

The EventHandler interface represents a callback used for event handlers as defined in [HTML5].

The concepts queue a task and fires a simple event are defined in [HTML5].

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

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

4. Peer-to-peer connections

4.1 Introduction

An RTCPeerConnection allows two users to communicate directly, browser to browser. 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].

4.2 Configuration

4.2.1 RTCConfiguration Type

dictionary RTCConfiguration {
             sequence<RTCIceServer>   iceServers;
             RTCIceTransportPolicy    iceTransportPolicy = "all";
             RTCBundlePolicy          bundlePolicy = "balanced";
             DOMString                peerIdentity;
             sequence<RTCCertificate> certificates;
};
4.2.1.1 Dictionary RTCConfiguration Members
bundlePolicy of type RTCBundlePolicy, , defaulting to "balanced"

Indicates which BundlePolicy to use.

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 set of certificates are 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. Attempts to change this value MUST be rejected.

iceServers of type sequence<RTCIceServer>,

An array containing URIs of servers available to be used by ICE, such as STUN and TURN server.

iceTransportPolicy of type RTCIceTransportPolicy, , defaulting to "all"

Indicates which candidates the ICE engine is allowed to use.

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.

4.2.2 RTCIceCredentialType Enum

enum RTCIceCredentialType {
    "password",
    "token"
};
Enumeration description
passwordThe credential is a long-term authentication password, as described in [RFC5389], Section 10.2.
tokenThe credential is an access token, as described in [TRAM-TURN-THIRD-PARTY-AUTHZ], Section 6.2.
Issue

Should we have a "none" type, for cases where no authentication is needed? (e.g. STUN)

4.2.3 RTCIceServer Type

dictionary RTCIceServer {
    required (DOMString or sequence<DOMString>) urls;
             DOMString                          username;
             DOMString                          credential;
             RTCIceCredentialType               credentialType = "password";
};
4.2.3.1 Dictionary RTCIceServer Members
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.

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.

In network topologies with multiple layers of NATs, it is desirable to have a STUN server between every layer of NATs in addition to the TURN servers to minimize the peer to peer network latency.

An example array of RTCIceServer objects is:

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

4.2.4 RTCIceTransportPolicy Enum

enum RTCIceTransportPolicy {
    "none",
    "relay",
    "all"
};
Enumeration description
noneThe ICE engine MUST not send or receive any packets at this point.
relayThe ICE engine 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.
allThe ICE engine may use any type of candidates when this value is specified.

4.2.5 RTCBundlePolicy Enum

Defined in [RTCWEB-JSEP]. The following is a non-normative summary for convenience. The BundlePolicy effects 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
balancedGather 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-compatGather ICE candidates for each track. If the remote endpoint is not BUNDLE-aware, negotiate all media tracks on separate transports.
max-bundleGather ICE candidates for only one track. If the remote endpoint is not BUNDLE-aware, negotiate only one media track.

4.2.6 Offer/Answer Options

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

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

Many codecs and system 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 {
             long    offerToReceiveVideo;
             long    offerToReceiveAudio;
             boolean iceRestart = false;
};
4.2.6.2 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.

offerToReceiveAudio of type long,

In some cases, an RTCPeerConnection may wish to receive audio but not send any audio. The RTCPeerConnection needs to know if it should signal to the remote side whether it wishes to receive audio. This option allows an application to indicate its preferences for the number of audio streams to receive when creating an offer.

offerToReceiveVideo of type long,

In some cases, an RTCPeerConnection may wish to receive video but not send any video. The RTCPeerConnection needs to know if it should signal to the remote side whether it wishes to receive video or not. This option allows an application to indicate its preferences for the number of video streams to receive when creating an offer.

dictionary RTCAnswerOptions : RTCOfferAnswerOptions {
};

4.3 RTCPeerConnection Interface

The general operation of the RTCPeerConnection is described in [RTCWEB-JSEP].

4.3.1 Operation

Calling new RTCPeerConnection(configuration ) creates an RTCPeerConnection object.

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

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

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

  1. Let connection be a newly created RTCPeerConnection object.

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

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

  4. Set connection's RTCPeerConnection signalingState to stable.

  5. Set connection's RTCPeerConnection ice connection state to new.

  6. Set connection's RTCPeerConnection ice gathering state to new.

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

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

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

  10. Return connection.

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

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

  2. If the length of the operations array is exactly 1, execute the function from the front of the queue asynchronously.

  3. When the asynchronous operation completes (either successfully or with an error), remove the corresponding object from the operations array. After removal, if the array is non-empty, execute the first object queued asynchronously and repeat this step on completion.

The general idea is to have only one among createOffer, setLocalDescription, createAnswer and setRemoteDescription executing at any given time. If subsequent calls are made while one of them is still executing, they are added to a queue and processed when the previous operation is fully completed. It is valid, and expected, for normal error handling procedures to be applied.

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

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

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

  3. When the ICE Agent finishes checking all candidate pairs, if at least one connection has been found for each MediaStreamTrack, the RTCPeerConnection ice connection state is changed to "completed"; otherwise "failed".

Issue

The section above shouldn't need to reference MediaStreamTracks when discussing the ICE connection state; one problem with this is that it doesn't handle the data channel situation properly. Rewrite this to refer to m-lines or ICE "media streams" or some such (here and in the later ICE connection state discussions.)

When the ICE Agent needs to notify the script about the candidate gathering progress, the user agent MUST queue a task to run the following steps:

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

  2. If connection's RTCPeerConnection signalingState is closed, abort these steps.

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

    • A new candidate is available.

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

    • The gathering process is done.

      Set connection's ice gathering state to completed and let newCandidate be null.

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

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

Warning

To prevent network sniffing from allowing a fourth party to establish a connection to a peer using the information sent out-of-band to the other peer and thus spoofing the client, the configuration information SHOULD always be transmitted using an encrypted connection.

4.3.2 Interface Definition

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

[ Constructor (optional RTCConfiguration configuration)]
interface RTCPeerConnection : EventTarget  {
    Promise<RTCSessionDescription> createOffer (optional RTCOfferOptions options);
    Promise<RTCSessionDescription> createAnswer (optional RTCAnswerOptions options);
    Promise<void>                  setLocalDescription (RTCSessionDescription description);
    readonly    attribute RTCSessionDescription? localDescription;
    readonly    attribute RTCSessionDescription? currentLocalDescription;
    readonly    attribute RTCSessionDescription? pendingLocalDescription;
    Promise<void>                  setRemoteDescription (RTCSessionDescription description);
    readonly    attribute RTCSessionDescription? remoteDescription;
    readonly    attribute RTCSessionDescription? currentRemoteDescription;
    readonly    attribute RTCSessionDescription? pendingRemoteDescription;
    Promise<void>                  addIceCandidate (RTCIceCandidate candidate);
    readonly    attribute RTCSignalingState      signalingState;
    readonly    attribute RTCIceGatheringState   iceGatheringState;
    readonly    attribute RTCIceConnectionState  iceConnectionState;
    readonly    attribute boolean?               canTrickleIceCandidates;
    RTCConfiguration               getConfiguration ();
    void                           setConfiguration (RTCConfiguration configuration);
    void                           close ();
                attribute EventHandler           onnegotiationneeded;
                attribute EventHandler           onicecandidate;
                attribute EventHandler           onsignalingstatechange;
                attribute EventHandler           oniceconnectionstatechange;
                attribute EventHandler           onicegatheringstatechange;
};
4.3.2.1 Constructors
RTCPeerConnection
See the RTCPeerConnection constructor algorithm.
ParameterTypeNullableOptionalDescription
configurationRTCConfiguration
4.3.2.2 Attributes
canTrickleIceCandidates of type boolean, readonly , nullable

This 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 Section 4.1.9 of [RTCWEB-JSEP]. Prior to the completion of setRemoteDescription, this value is null.

currentLocalDescription of type RTCSessionDescription, readonly , nullable

The currentLocalDescription attribute represents the local RTCSessionDescription that was successfully negotiated the last time the PeerConnection transitioned into the stable state plus any local candidates that have been generated by the ICE Agent since the offer or answer was created. This attribute is updated by setLocalDescription().

The currentLocalDescription attribute MUST return the last value that previous algorithms in this specification set it to plus any local candidates that have been generated by the ICE Agent since the offer or answer was created.

currentRemoteDescription of type RTCSessionDescription, readonly , nullable

The currentRemoteDescription attribute represents the last remote RTCSessionDescription that was successfully negotiated the last time the PeerConnection transitioned into the stable state plus any remote candidates that have been supplied via addIceCandidate() since the offer or answer was created. This attribute is updated by setRemoteDescription().

The currentRemoteDescription attribute MUST return the value that previous algorithms in this specification set it to plus any remote candidates that have been supplied via addIceCandidate() since the offer or answer was created.

iceConnectionState of type RTCIceConnectionState, readonly

The iceConnectionState attribute MUST return the state of the RTCPeerConnection ICE Agent ICE state.

iceGatheringState of type RTCIceGatheringState, readonly

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

localDescription of type RTCSessionDescription, readonly , nullable

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

onicecandidate of type EventHandler,
This event handler, of event handler event type icecandidate, MUST be supported by all objects implementing the RTCPeerConnection interface.
oniceconnectionstatechange of type EventHandler,
This event handler, of event handler event type iceconnectionstatechange, MUST be fired by all objects implementing the RTCPeerConnection interface. It is called any time the RTCPeerConnection ice connection state changes.
onicegatheringstatechange of type EventHandler,
This event handler, of event handler event type icegatheringstatechange, MUST be fired by all objects implementing the RTCPeerConnection interface. It is called any time the RTCPeerConnection ice gathering state changes.
onnegotiationneeded of type EventHandler,
This event handler, of event handler event type negotiationneeded, MUST be supported by all objects implementing the RTCPeerConnection interface.
onsignalingstatechange of type EventHandler,
This event handler, of event handler event type signalingstatechange, MUST be supported by all objects implementing the RTCPeerConnection interface. It is called any time the RTCPeerConnection signaling state changes, i.e., from a call to setLocalDescription, a call to setRemoteDescription, or code. It does not fire for the initial state change into new.
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 PeerConnection is in the stable state, the value is null. This attribute is updated by setLocalDescription().

The pendingLocalDescription attribute MUST return the last value that previous algorithms in this specification set it to plus any local candidates that have been generated by the ICE Agent since the offer or answer was created.

pendingRemoteDescription of type RTCSessionDescription, readonly , nullable

The pendingRemoteDescription attribute represents a remote RTCSessionDescription that is in the process of being negotiated plus any remote candidates that have been supplied via addIceCandidate() since the offer or answer was created. If the PeerConnection is in the stable state, the value is null. This attribute is updated by setLocalDescription().

The pendingRemoteDescription attribute MUST return the value that previous algorithms in this specification set it to plus any remote candidates that have been supplied via addIceCandidate() since the offer or answer was created.

remoteDescription of type RTCSessionDescription, readonly , nullable

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

signalingState of type RTCSignalingState, readonly

The signalingState attribute MUST return the RTCPeerConnection object's RTCPeerConnection signaling state.

4.3.2.3 Methods
addIceCandidate

The addIceCandidate() method provides a remote candidate to the ICE Agent. In addition to being added to the remote description, connectivity checks will be sent to the new candidates as long as the ICE Transports setting is not set to none. This call will result in a change to the connection state of the ICE Agent, and may result in a change to media state if it results in different connectivity being established.

  1. Let p be a new promise.

  2. If this RTCPeerConnection object's signaling state is closed, the user agent MUST reject p with InvalidStateError, and jump to the step labeled Return.

  3. If the candidate parameter is malformed, reject p with SyntaxError and jump to the step labeled Return.

  4. If the candidate could not be successfully applied, reject p with a DOMError object whose name attribute has the value TBD and jump to the step labeled Return.

    Issue

    TODO: define names for DOMError ( InvalidCandidate and InvalidMidIndex)

  5. If the candidate is successfully applied, resolve p with undefined.

  6. Return: Return p.

Issue
What errors do we need here? Should we reuse the *SessionDescriptionError names or invent new ones for candidates? Should this method be queued?
ParameterTypeNullableOptionalDescription
candidateRTCIceCandidate
Return type: Promise<void>
close

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

  1. If the RTCPeerConnection object's RTCPeerConnection signalingState is closed, abort these steps.
  2. Destroy the RTCPeerConnection ICE Agent, abruptly ending any active ICE processing and any active streaming, and releasing any relevant resources (e.g. TURN permissions).

  3. Set the object's RTCPeerConnection signalingState to closed.

No parameters.
Return type: void
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 MediaStreams 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 get the ICE user name fragment and password.

An answer can be marked as provisional, as described in [RTCWEB-JSEP], 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. If the identity provider is unable to produce an identity assertion, the call to createAnswer MUST be rejected with a DOMError that has a name of IdpError.

If this RTCPeerConnection object is closed before the SDP generation process completes, the USER agent MUST suppress the result and not resolve or reject the returned promise.

If the SDP generation process completed successfully, the user agent MUST resolve the returned promise with a newly created RTCSessionDescription object, representing the generated answer.

If the SDP generation process failed for any reason, the user agent MUST reject the returned promise with a DOMError object of type TBD.

Issue

TODO: define type of error for SDP generation

ParameterTypeNullableOptionalDescription
optionsRTCAnswerOptions
Return type: Promise<RTCSessionDescription>
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 MediaStreams 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 streams. 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 get the ICE user name 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. If the identity provider is unable to produce an identity assertion, the call to createOffer MUST be rejected with a DOMError that has a name of IdpError.

If this RTCPeerConnection object is closed before the SDP generation process completes, the USER agent MUST suppress the result and not resolve or reject the returned promise.

If the SDP generation process completed successfully, the user agent MUST resolve the returned promise with a newly created RTCSessionDescription object, representing the generated offer.

If the SDP generation process failed for any other reason, the user agent MUST reject the returned promise with an DOMError object of type TBD as its argument.

Issue

To Do: Discuss privacy aspects of this from a fingerprinting point of view - it's probably around as bad as access to a canvas :-)

ParameterTypeNullableOptionalDescription
optionsRTCOfferOptions
Return type: Promise<RTCSessionDescription>
getConfiguration

Returns a RTCConfiguration object representing the current configuration of this RTCPeerConnection object.

When this method is call, the user agent MUST construct new RTCConfiguration object to be returned, and initialize it using the ICE Agent's ICE transports setting and ICE servers list.

The returned configuration MUST include a certificates attribute containing the candidate set of certificates used for connecting to peers. This attribute contains the certificates chosen by the application, or the certificates generated by the user agent for use with this RTCPeerConnection instance.

No parameters.
Return type: RTCConfiguration
setConfiguration

The setConfiguration method updates the ICE Agent process of gathering local candidates and pinging remote candidates.

This call may result in a change to the state of the ICE Agent, and may result in a change to media state if it results in connectivity being established.

When the setConfiguration() method is invoked, the user agent MUST set the configuration specified by the methods argument.

To set a configuration, run the following steps:

  1. Let configuration be the RTCConfiguration dictionary to be processed.
  2. Let the value of configuration's iceTransportPolicy member be the ICE Agent's ICE transports setting.

  3. Let the value of configuration's bundlePolicy member be the User Agent's bundle policy.

  4. Let validatedServers be an empty list.

  5. If configuration's iceServers dictionary member is present, then run the following steps for each element:

    1. Let server be the current list element.

    2. If the server.urls dictionary member an empty list, then throw an InvalidAccessError and abort these steps.

    3. If server.urls is a single string, let server.urls be a list consisting of just that string.

    4. For each url in server.urls, parse the url and obtain scheme name. If the parsing fails or if scheme name is not implemented by the browser, throw a SyntaxError and abort these steps.

    5. If scheme name is "turn" and either of the dictionary members server.username or server.credential are omitted, then throw an InvalidAccessError and abort these steps.

    6. Appendserver to validatedServers.

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

    If a new list of servers replaces the ICE Agent's existing ICE servers list, no action will taken until the RTCPeerConnection 's ice gathering state transitions to gathering. If a script wants this to happen immediately, it should do an ICE restart.

Note
The exception types throw in the above algorithm are provisional (until we decide what to do in each case).
ParameterTypeNullableOptionalDescription
configurationRTCConfiguration
Return type: void
setLocalDescription

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

Issue

To Do: specify what parts of the SDP can be changed between the createOffer and setLocalDescription

The following list describes the processing model for setting a new RTCSessionDescription.

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

    1. Let p be a new promise.

    2. If this RTCPeerConnection object's signaling state is closed, the user agent MUST reject p with InvalidStateError, and jump to the step labeled Return.

    3. If a local description contains a different set of ICE credentials, then the ICE Agent MUST trigger an ICE restart. When ICE restarts, the gathering state will be changed back to "gathering", if it was not already gathering. If the RTCPeerConnection ice connection state was "completed", it will be changed back to "connected".

    4. The user agent MUST start the process to apply the RTCSessionDescription argument.

    5. Return: Return p.

  • If the process to apply the RTCSessionDescription argument fails for any reason, then user agent MUST queue a task runs the following steps:

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

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

    3. If the reason for the failure is:

      • The content of the RTCSessionDescription argument is invalid or the type is wrong for the current signaling state of connection.

        Let reason be InvalidSessionDescriptionError.

      • The RTCSessionDescription is a valid description but cannot be applied at the media layer.

        Issue

        TODO - next few points are probably wrong. Make sure to check this in setRemote too.

        This can happen, e.g., if there are insufficient resources to apply the SDP. The user agent MUST then rollback as necessary if the new description was partially applied when the failure occurred.

        If rollback was not necessary or was completed successfully, let reason be IncompatibleSessionDescriptionError. If rollback was not possible, let reason be InternalError and set connection's signaling state to closed.

    4. Reject p with reason.

  • If the RTCSessionDescription argument is applied successfully, then user agent MUST queue a task (setLocalDescription() resolve task) that runs the following steps:

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

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

    3. If the local description was set, and the supplied description matches the state of all tracks and data channels, as defined below, clear the negotiation-needed flag.

    4. Set the connection's description attributes by executing one of the following.

      Issue

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

      • If the local description was set, and the RTCSessionDescription argument has a type of "offer", and it has a version that is later than the currentLocalDescription, then the pendingLocalDescription will be set to the argument and the state will transition to have-local-offer.

      • If the local description was set, and the RTCSessionDescription argument has a type of "answer", then this completes an offer answer negotiation and currentLocalDescription is set to the argument, currentRemoteDescription is set to the value of pendingRemoteDescription, then pendingRemoteDescription and pendingLocalDescription are set to null, and the state will transitions to stable.

      • If the remote description was set, and the RTCSessionDescription argument has a type of "offer", and it has a version that is later than the currentRemoteDescription, then the pendingRemoteDescription will be set to the argument and the state will transition to have-remote-offer.

      • If the remote description was set, and the RTCSessionDescription argument has a type of "answer", then this completes an offer answer negotiation and currentRemoteDescription is set to the argument, currentLocalDescription is set to the value of pendingLocalDescription, then pendingRemoteDescription and pendingLocalDescription are set to null, and the state will transitions to stable.

      • If the local description was set, and the RTCSessionDescription argument has a type of "rollback", then this is a rollback and the pendingLocalDescription is set to null and the state will transition to stable.

      • If the remote description was set, and the RTCSessionDescription argument has a type of "rollback", then this is a rollback and the pendingRemoteDescription is set to null and the state will transition to stable.

      • If the local description was set, and the RTCSessionDescription argument has a type of "pranswer", then pendingLocalDescription will be set to the argument and the state will transitions to have-local-pranswer unless the state was stable, have-local-offer, or have-remote-pranswer in which case an InvalidStateError error will be generated.

      • If the remote description was set, and the RTCSessionDescription argument has a type of "pranswer", then pendingRemoteDescription will be set to the argument and the state will transitions to have-remote-pranswer unless the state was stable, have-remote-offer, or have-local-pranswer in which case an InvalidStateError error will be generated.

    5. If the local description was set, connection's ice gathering state is new, and the local description contains media, then set connection's ice gathering state to gathering.

    6. If the local description was set with content that caused an ICE restart, then set connection's ice gathering state to gathering.

    7. Set connection's signalingState accordingly.

    8. If connection's signalingState changed, fire a simple event named signalingstatechange at connection.

    9. If connection's signalingState is now stable, and the negotiation-needed flag is set, fire a simple event named negotiationneeded at connection.

    10. Resolve p with undefined.

ParameterTypeNullableOptionalDescription
descriptionRTCSessionDescription
Return type: Promise<void>
setRemoteDescription

The setRemoteDescription() method instructs the RTCPeerConnection to apply the supplied RTCSessionDescription as the remote offer or answer. This API changes the local media state.

When the method is invoked, the user agent MUST follow the processing model of setLocalDescription(). In addition, a remote description is processed to determine and verify the identity of the peer.

If the RTCSessionDescription argument is applied successfully, the user agent MUST dispatch a receiver for all new media descriptions [RTCWEB-JSEP] before queuing the setLocalDescription() resolve task.

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

ParameterTypeNullableOptionalDescription
descriptionRTCSessionDescription
Return type: Promise<void>

4.3.3 Legacy Interface Extensions

Note
These methods are kept on RTCPeerConnection for legacy purposes.
partial interface RTCPeerConnection {
    void createOffer (RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback, optional RTCOfferOptions options);
    void setLocalDescription (RTCSessionDescription description, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback);
    void createAnswer (RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback);
    void setRemoteDescription (RTCSessionDescription description, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback);
    void addIceCandidate (RTCIceCandidate candidate, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback);
    void getStats (MediaStreamTrack? selector, RTCStatsCallback successCallback, RTCPeerConnectionErrorCallback failureCallback);
};
4.3.3.1 Methods
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. Invoke RTCPeerConnection.addIceCandiddate() with candidate as the sole argument, and let p be the resulting promise.

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

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

ParameterTypeNullableOptionalDescription
candidateRTCIceCandidate
successCallbackVoidFunction
failureCallbackRTCPeerConnectionErrorCallback
Return type: 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. Invoke RTCPeerConnection.createAnswer() with no arguments, and let p be the resulting promise.

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

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

ParameterTypeNullableOptionalDescription
successCallbackRTCSessionDescriptionCallback
failureCallbackRTCPeerConnectionErrorCallback
Return type: void
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. Invoke RTCPeerConnection.createOffer() with options as the sole argument, and let p be the resulting promise.

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

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

ParameterTypeNullableOptionalDescription
successCallbackRTCSessionDescriptionCallback
failureCallbackRTCPeerConnectionErrorCallback
optionsRTCOfferOptions
Return type: 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. Invoke RTCPeerConnection.getStats() with selector as the sole argument, and let p be the resulting promise.

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

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

ParameterTypeNullableOptionalDescription
selectorMediaStreamTrack
successCallbackRTCStatsCallback
failureCallbackRTCPeerConnectionErrorCallback
Return type: 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. Invoke RTCPeerConnection.setLocalDescription() with description as the sole argument, and let p be the resulting promise.

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

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

ParameterTypeNullableOptionalDescription
descriptionRTCSessionDescription
successCallbackVoidFunction
failureCallbackRTCPeerConnectionErrorCallback
Return type: 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. Invoke RTCPeerConnection.setLocalDescription() with description as the sole argument, and let p be the resulting promise.

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

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

ParameterTypeNullableOptionalDescription
descriptionRTCSessionDescription
successCallbackVoidFunction
failureCallbackRTCPeerConnectionErrorCallback
Return type: 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 RTCPeerConnection signalingState is closed, no such event handler can be triggered and it is therefore safe to garbage collect the object.

All RTCDataChannel and MediaStreamTrack objects that are connected to a RTCPeerConnection are considered to 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",
    "closed"
};
Enumeration description
stableThere 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-offerA local description, of type "offer", has been successfully applied.
have-remote-offerA remote description, of type "offer", has been successfully applied.
have-local-pranswerA remote description of type "offer" has been successfully applied and a local description of type "pranswer" has been successfully applied.
have-remote-pranswerA local description of type "offer" has been successfully applied and a remote description of type "pranswer" has been successfully applied.
closedThe connection is closed.

The non-normative peer state transitions are: The non-normative peer state transition 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
  • close(): closed

Callee transition:

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

4.4.2 RTCIceGatheringState Enum

enum RTCIceGatheringState {
    "new",
    "gathering",
    "complete"
};
Enumeration description
newThe object was just created, and no networking has occurred yet.
gatheringThe ICE engine is in the process of gathering candidates for this RTCPeerConnection.
completeThe ICE engine has completed gathering. Events such as adding a new interface or a new TURN server will cause the state to go back to gathering.

4.4.3 RTCIceConnectionState Enum

enum RTCIceConnectionState {
    "new",
    "checking",
    "connected",
    "completed",
    "failed",
    "disconnected",
    "closed"
};
Enumeration description
newThe ICE Agent is gathering addresses and/or waiting for remote candidates to be supplied.
checkingThe ICE Agent has received remote candidates on at least one component, and is checking candidate pairs but has not yet found a connection. In addition to checking, it may also still be gathering.
connectedThe ICE Agent has found a usable connection for all components but is still checking other candidate pairs to see if there is a better connection. It may also still be gathering.
completedThe ICE Agent has finished gathering and checking and found a connection for all components. Details on how the completed state in ICE is reached are covered in [ICE].
failedThe ICE Agent is finished checking all candidate pairs and failed to find a connection for at least one component. Connections may have been found for some components.
disconnectedLiveness checks have failed for one or more components. This is more aggressive than failed, and may trigger intermittently (and resolve itself without action) on a flaky network.
closedThe ICE Agent has shut down and is no longer responding to STUN requests.

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

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

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

Some example transitions might be:

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

The non-normative ICE state transitions are: The non-normative ICE state transition diagram

4.5 Callback Definitions

4.5.1 RTCPeerConnectionErrorCallback

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

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.6.2 RTCSdpError

interface RTCSdpError : DOMError {
    readonly    attribute long sdpLineNumber;
};
4.6.2.1 Attributes
sdpLineNumber of type long, readonly
The line number of an RTCSessionDescription at which the error was encountered.
Issue

Ask the DOM team to extend their list with the following errors. The error names and their descriptions are directly copied from the old RTCErrorName enum and might need some adjustment before being added to the public list of errors.

  • InvalidSessionDescriptionError: The provided RTCSessionDescription contained invalid SDP, or the type was wrong for the current state of the RTCPeerConnection. User agents SHOULD provide as much additional information in the error message as possible, including the sdpLineNumber, if appropriate.
  • IncompatibleSessionDescriptionError: The provided RTCSessionDescription contained SDP that could not be correctly applied to the RTCPeerConnection due to its current state. User agents SHOULD provide as much additional information in the error message as possible, including the sdpLineNumber, if appropriate.
  • IncompatibleConstraintsError: The provided MediaConstraints could not be correctly applied to the RTCPeerConnection due to its current state. User agents SHOULD provide as much additional information in the error message as possible.
  • InternalError: The RTCPeerConnection encountered an error that it could not recover from.

4.7 Session Description Model

4.7.1 RTCSdpType

The RTCSdpType enum describes the type of an 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 a 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 an canceling the current SDP negotiation and moving back to 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

dictionary RTCSessionDescriptionInit {
    required RTCSdpType type;
             DOMString? sdp = null;
};

[ Constructor (RTCSessionDescriptionInit descriptionInitDict)] interface RTCSessionDescription { attribute RTCSdpType type; attribute DOMString? sdp; serializer = {attribute}; };
4.7.2.1 Constructors
RTCSessionDescription
The RTCSessionDescription() constructor takes a dictionary argument, descriptionInitDict, whose content is used to initialize the new RTCSessionDescription object. This class is a future extensible carrier for the data contained in it and does not perform any substantive processing.
ParameterTypeNullableOptionalDescription
descriptionInitDictRTCSessionDescriptionInit
4.7.2.2 Attributes
sdp of type DOMString, , nullable
The string representation of the SDP [SDP] or a null value.
type of type RTCSdpType,
The type of this RTCSessionDescription.
4.7.2.3 Serializer

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

4.7.2.4 Dictionary RTCSessionDescriptionInit Members
sdp of type DOMString, , nullable, defaulting to null
type of type RTCSdpType, required
DOMString? sdp = null

4.7.3 RTCSessionDescriptionCallback

callback RTCSessionDescriptionCallback = void (RTCSessionDescription sdp);
4.7.3.1 Callback RTCSessionDescriptionCallback Parameters
sdp of type RTCSessionDescription
The object containing the SDP [SDP].

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.

4.8.1 Setting Negotiation-Needed

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

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

4.8.2 Clearing Negotiation-Needed

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

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

4.8.3 Firing An Event

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

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

4.9 Interfaces for Connectivity Establishment

4.9.1 RTCIceCandidate Type

This class is a future extensible carrier for the data contained in it and does not perform any substantive processing.

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

[ Constructor (RTCIceCandidateInit candidateInitDict)] interface RTCIceCandidate { attribute DOMString candidate; attribute DOMString? sdpMid; attribute unsigned short? sdpMLineIndex; serializer = {attribute}; };
4.9.1.1 Constructors
RTCIceCandidate
The RTCIceCandidate() constructor takes a dictionary argument, candidateInitDict, whose content is used to initialize the new RTCIceCandidate object. When constructed, values for candidate and either sdpMid or sdpMLineIndex MUST be provided.
ParameterTypeNullableOptionalDescription
candidateInitDictRTCIceCandidateInit
4.9.1.2 Attributes
candidate of type DOMString,
This carries the candidate-attribute as defined in section 15.1 of [ICE].
sdpMLineIndex of type unsigned short, , nullable
This indicates the index (starting at zero) of the m-line in the SDP this candidate is associated with.
sdpMid of type DOMString, , nullable
If present, this contains the identifier of the "media stream identification" as defined in [RFC3388] for the media section this candidate is associated with.
4.9.1.3 Serializer

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

4.9.1.4 Dictionary RTCIceCandidateInit Members
candidate of type DOMString, required
DOMString sdpMid
sdpMLineIndex of type unsigned short,
sdpMid of type DOMString,
unsigned short sdpMLineIndex

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.

dictionary RTCPeerConnectionIceEventInit : EventInit {
             RTCIceCandidate candidate;
};

[ Constructor (DOMString type, RTCPeerConnectionIceEventInit eventInitDict)] interface RTCPeerConnectionIceEvent : Event { readonly attribute RTCIceCandidate? candidate; };
4.9.2.1 Constructors
RTCPeerConnectionIceEvent
readonly attribute RTCIceCandidate? candidate
ParameterTypeNullableOptionalDescription
typeDOMString
eventInitDictRTCPeerConnectionIceEventInit
4.9.2.2 Attributes
candidate of type RTCIceCandidate, readonly , nullable

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

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

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

4.9.2.3 Dictionary RTCPeerConnectionIceEventInit Members
candidate of type RTCIceCandidate,

See RTCPeerConnectionIceEvent.candidate.

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 marketing 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 RTCRtpEncodingParamters.priority to the follwing values.

4.10.1 RTCPriorityType Enum

enum RTCPriorityType {
    "very-low",
    "low",
    "medium",
    "high"
};
Enumeration description
very-lowSee [RTCWEB-TRANSPORT], Section 4.
lowSee [RTCWEB-TRANSPORT], Section 4.
mediumSee [RTCWEB-TRANSPORT], Section 4.
highSee [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 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 RTCPeerConnection.generateCertificate 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);
};

4.11.1 Methods

generateCertificate, static

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

The keygenAlgorithm argument is used to control how the private key associated with the certificate is generated. The keygenAlgorithm argument uses the WebCrypto [WebCryptoAPI] AlgorithmIdentifier type. The keygenAlgorithm value MUST be a valid argument to 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-3] 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 DOMError 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: 65537 }, 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.

ParameterTypeNullableOptionalDescription
keygenAlgorithmAlgorithmIdentifier
Return type: Promise<RTCCertificate>

4.11.2 RTCCertificate Interface

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

interface RTCCertificate {
    readonly    attribute Date expires;
};
4.11.2.1 Attributes
expires of type Date, readonly

The expires attribute indicates the date and time 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.

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 RTCRtpSenders. Similarly, the reception and decoding of MediaStreamTracks is managed through objects called RTCRtpReceivers. Each track to be sent is associated with exactly one RTCRtpSender, and each track to be received is associated with exactly one RTCRtpReceiver.

RTCRtpSenders are created when the application attaches a MediaStreamTrack to a PeerConnection, via the addTrack method. RTCRtpReceivers, 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.

A RTCPeerConnection object contains a set of RTCRtpSenders, representing tracks to be sent, and a set of RTCRtpReceivers, representing tracks that are to be received on this RTCPeerConnection object. Both of these sets are initialized to empty sets 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 ();
    RTCRtpSender             addTrack (MediaStreamTrack track, MediaStream... streams);
    void                     removeTrack (RTCRtpSender sender);
                attribute EventHandler ontrack;
};

5.1.1 Attributes

ontrack of type EventHandler,

This event handler, of event handler event type track, MUST be fired by all objects implementing the RTCPeerConnection interface.

5.1.2 Methods

addTrack

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

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

  1. Let connection be the RTCPeerConnection object on which the MediaStreamTrack, track, is to be added.

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

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

  4. Create a new RTCRtpSender for track, add it to connection's set of senders, and return it to the caller.

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

  6. Mark connection as needing negotiation.

ParameterTypeNullableOptionalDescription
trackMediaStreamTrack
streamsMediaStream
Return type: 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 a new sequence that represents a snapshot of all the RTCRtpReceiver objects in this RTCPeerConnection object's set of receivers. The conversion from the receivers set to the sequence, to be returned, is user agent defined and the order does not have to be stable between calls.

No parameters.
Return type: sequence<RTCRtpReceiver>
getSenders

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

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

No parameters.
Return type: sequence<RTCRtpSender>
removeTrack

Removes sender, and its associated MediaStreamTrack, from the RTCPeerConnection.

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

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

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

  2. If connection's RTCPeerConnection signalingState is closed, throw an InvalidStateError exception.

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

  4. Remove sender from connection's set of senders.

  5. Mark connection as needing negotiation.

ParameterTypeNullableOptionalDescription
senderRTCRtpSender
Return type: void

5.1.3 Processing Remote MediaStreamTracks

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

To dispatch a receiver for an incoming media description [RTCWEB-JSEP], the user agent MUST queue a task that runs the following steps:

  1. Let connection be the RTCPeerConnection expecting this media.

  2. If the connection's RTCPeerConnection signalingState is closed, abort these steps.

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

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

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

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

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

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

    5. Initialize track's readyState attribute to live.

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

  5. If streams is an empty list, create a new MediaStream object and add it to streams.

  6. Add track to all MediaStream objects in streams.

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

  8. Fire an event named track with receiver, 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 the connection's RTCPeerConnection signalingState is closed, abort these steps.

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

Issue

Since the beginning of this specification, remote MediaStreamTracks have been created by the setRemoteDescription call, one track for each non-rejected m-line in the remote description. This meant that at the caller, MediaStreamTracks were not created until the answer was received, and any media received prior to a remote description (AKA "early media") would be discarded. If any form of remote description is provided (either an answer or a pranswer), this issue does not occur.

If we want to allow early media to be played out, minor changes are necessary. Fundamentally, we would need to change when tracks are created for the offerer; this would have to happen either as a result of setLocalDescription, or when media packets are received. This ensures that these objects can be created and connected to media elements for playout.

However, there are three consequences to this potential change:

  1. Media may arrive before the remote DTLS fingerprint has been received. This means that media could be played out before the validity of the DTLS fingerprint has been established, which may be hard to explain to users. As such, it is recommended that media not be played out unless some TBD RTCConfiguration property (e.g. AllowUnverifiedMedia) has been set.
  2. The information needed to correlate MediaStreamTracks with their enclosing MediaStream will not yet be present when the tracks are initially generated. Therefore, the implementation will need to create dummy MediaStream objects for each MediaStreamTrack, and then possibly change the associated MediaStream for each track when the remote description is received (e.g. if it indicates that an audio and video MediaStreamTrack should be combined into a single MediaStream). Since media elements act on MediaStreams, some complex reshuffling may need to occur when the remote description is received.
  3. The track events fired and their timing will change. For the offerer, ontrack will now fire during setLocalDescription, once for each track being offered, and track.onended will fire during setRemoteDescription for any offered tracks that were rejected. For the answerer, ontrack will continue to fire during setRemoteDescription, as it does today (this is necessary to allow the answerer to reject offered tracks by stopping them).

For now, we simply make note of this issue, until it can be considered fully by the WG.

5.2 RTCRtpSender Interface

The RTCRtpSender interface allows an application to control how a given MediaStreamTrack is encoded and transmitted to a remote RTCRtpReceiver. When methods are called on an RTCRtpSender, such as RTCRtpSender.setParameters, the encoding is changed appropriately.

dictionary RTCRtpParameters {
             sequence<RTCRtpEncodingParameters> encodings;
};

5.2.1 Dictionary RTCRtpParameters Members

encodings of type sequence<RTCRtpEncodingParameters>,

An array containing parameters for RTP encodings of media.

dictionary RTCRtpEncodingParameters {
             boolean         active;
             RTCPriorityType priority;
             unsigned long   maxBitrate;
};

5.2.2 Dictionary RTCRtpEncodingParameters Members

active of type boolean,

Indicates that this encoding is actively being sent. Setting it to false causes this encoding to no longer be sent. Setting it to true causes this encoding to be sent.

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 bandwidth limits (such as per-transport or per-session limits) below the maximum specified here.

TODO: Find or create a definition for bitrate (how much header overhead is included, for example). Should be aligned with RTCOutboundRTPStreamStats.targetBitrate in webrtc-stats.

priority of type RTCPriorityType,

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

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

5.2.3 Dictionary RTCRtpCapabilities Members

codecs of type sequence<RTCRtpCodecCapability>,

Supported codecs.

headerExtensions of type sequence<RTCRtpHeaderExtensionCapability>,

Supported RTP header extensions.

dictionary RTCRtpCodecCapability {
             DOMString mimeType;
};

5.2.4 Dictionary RTCRtpCodecCapability Members

mimeType of type DOMString,

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

dictionary RTCRtpHeaderExtensionCapability {
             DOMString uri;
};

5.2.5 Dictionary RTCRtpHeaderExtensionCapability Members

uri of type DOMString,

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

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

5.2.6 Attributes

mid of type DOMString, readonly
The RTCRtpSender.mid attribute is the value of the a=mid SDP attribute that is immutably associated, via setLocalDescription, with this RTCRtpSender object.
rtcpTransport of type RTCDtlsTransport, readonly , nullable

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

track of type MediaStreamTrack, readonly

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

transport of type RTCDtlsTransport, readonly

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

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

ParameterTypeNullableOptionalDescription
kindDOMString
Return type: RTCRtpCapabilities
getParameters

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

Example 1
var params = sender.getParameters();
// ... make changes to RtpParameters
params.encodings[0].active = false;
sender.setParameters(params)
No parameters.
Return type: RTCRtpParameters
replaceTrack

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

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

  1. Let p be a new promise.

  2. Let withTrack be the argument to this method.

  3. If withTrack's kind attribute differs from the kind of this sender's track, then reject p with TypeError, return p and abort these steps.

  4. Run the following steps in parallel:

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

    2. Have the sender switch seamlessly to transmitting withTrack in place of what it is sending, without negotiating. To avoid track identifiers changing on the remote receiving end, the sender MUST retain the original track identifier and stream associations and use these in subsequent negotiations.

    3. Set this sender's track attribute to withTrack, and resolve p with undefined.
  5. Return p.

Note

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

  1. Changing a frame rate 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.

ParameterTypeNullableOptionalDescription
withTrackMediaStreamTrack
Return type: Promise<void>
setParameters

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

ParameterTypeNullableOptionalDescription
parametersRTCRtpParameters
Return type: void

5.3 RTCRtpReceiver Interface

The RTCRtpReceiver interface allows an application to control the receipt of a MediaStreamTrack. When attributes on an RTCRtpReceiver are modified, a negotiation is triggered to signal the changes regarding what the application wants to receive to the other side.

interface RTCRtpReceiver {
    readonly    attribute MediaStreamTrack  track;
    readonly    attribute RTCDtlsTransport  transport;
    readonly    attribute RTCDtlsTransport? rtcpTransport;
    readonly    attribute DOMString         mid;
    static RTCRtpCapabilities getCapabilities (DOMString kind);
};

5.3.1 Attributes

mid of type DOMString, readonly
The RTCRtpReceiver.mid attribute is the value of the a=mid SDP attribute that is immutably associated, via setRemoteDescription, with this RTCRtpReceiver object. In the case where no a=mid attribute is present in the remote description, a random value will be generated.
rtcpTransport of type RTCDtlsTransport, readonly , nullable

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

track of type MediaStreamTrack, readonly

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

transport of type RTCDtlsTransport, readonly

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

5.3.2 Methods

getCapabilities, static

The RTCRtpReceiver.getCapabilities method returns the most optimist view on 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.

ParameterTypeNullableOptionalDescription
kindDOMString
Return type: RTCRtpCapabilities

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

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

5.4.1 Attributes

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

The state attribute MUST return the state of the transport.

transport of type RTCIceTransport, readonly

The RTCDtlsTransport.transport attribute is the underlying transport that is used to send and receive packets. The underlying transport may not be shared between multiple active RTCDtlsTransport objects.

5.4.2 Methods

getRemoteCertificates

An array containing the remote certificates in use by the remote side.

No parameters.
Return type: sequence<ArrayBuffer>

RTDtlsTransportState Enum

enum RTCDtlsTransportState {
    "new",
    "connecting",
    "connected",
    "closed",
    "failed"
};
Enumeration description
newDTLS has not started negotiating yet.
connectingDTLS is in the process of negotiating a secure connection.
connectedDTLS has completed negotiation of a secure connection.
closedThe transport has been closed.
failedThe transport has failed as the result of an error (such as a failure to validate the remote fingerprint).

5.5 RTCIceTransport Interface

The RTCIceTransport interface allows an application access to information about the ICE transport over packets are sent and received. In particular, ICE manages peer-to-peer connections which involve state which the application may want to access.

interface RTCIceTransport {
    readonly    attribute RTCIceConnectionState state;
    RTCIceCandidatePair? getSelectedCandidatePair ();
                attribute EventHandler          onstatechange;
                attribute EventHandler          onselectedcandidatepairchange;
};

5.5.1 Attributes

onselectedcandidatepairchange of type EventHandler,
This event handler, of event handler event type selectedcandidatepairchange, MUST be fired any time the RTCIceTransport's selected candidate pair changes.
onstatechange of type EventHandler,
This event handler, of event handler event type statechange, MUST be fired any time the RTCIceTransport state changes.
state of type RTCIceConnectionState, readonly

The state attribute MUST return the state of the transport.

5.5.2 Methods

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
dictionary RTCIceCandidatePair {
             RTCIceCandidate local;
             RTCIceCandidate remote;
};

5.5.3 Dictionary RTCIceCandidatePair Members

local of type RTCIceCandidate,

The local ICE candidate.

remote of type RTCIceCandidate,

The remote ICE candidate.

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

dictionary RTCTrackEventInit : EventInit {
             RTCRtpReceiver   receiver;
             MediaStreamTrack track;
             MediaStream[]    streams;
};

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

5.6.1 Constructors

RTCTrackEvent
readonly attribute RTCRtpReceiver receiver
ParameterTypeNullableOptionalDescription
typeDOMString
eventInitDictRTCTrackEventInit

5.6.2 Attributes

receiver of type RTCRtpReceiver, readonly

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

streams of type array of MediaStream, readonly

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

track of type MediaStreamTrack, readonly

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

5.6.3 Dictionary RTCTrackEventInit Members

receiver of type RTCRtpReceiver,
Issue

TODO

streams of type array of MediaStream,
Issue

TODO

track of type MediaStreamTrack,
Issue

TODO

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 {
    RTCDataChannel createDataChannel ([TreatNullAs=EmptyString] DOMString label, optional RTCDataChannelInit dataChannelDict);
                attribute EventHandler ondatachannel;
};

6.1.1 Attributes

ondatachannel of type EventHandler,
This event handler, of type datachannel, MUST be supported by all objects implementing the RTCPeerConnection interface.

6.1.2 Methods

createDataChannel

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

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

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

  2. Let channel be a newly created RTCDataChannel object.

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

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

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

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

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

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

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

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

ParameterTypeNullableOptionalDescription
labelDOMString
dataChannelDictRTCDataChannelInit
Return type: RTCDataChannel

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

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 RTCPeerConnection signalingState is closed, 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 RTCPeerConnection signalingState is closed, 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.

    Issue
    The data transport protocol will specify what happens to, e.g. buffered data, when the data transport is closed.
  2. Set channel's readyState attribute to closed.

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

  4. Fire a simple event named close at channel.

dictionary RTCDataChannelInit {
             boolean        ordered = true;
             unsigned short maxPacketLifeTime;
             unsigned short maxRetransmits;
             DOMString      protocol = "";
             boolean        negotiated = false;
             unsigned short id;
};

interface RTCDataChannel : EventTarget { readonly attribute DOMString label; readonly attribute boolean ordered; readonly attribute unsigned short? maxPacketLifeTime; readonly attribute unsigned short? maxRetransmits; readonly attribute DOMString protocol; readonly attribute boolean negotiated; readonly attribute unsigned short id; 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 (DOMString data); void send (Blob data); void send (ArrayBuffer data); void send (ArrayBufferView data); };

6.2.1 Attributes

binaryType of type DOMString,

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

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

bufferedAmount of type unsigned long, readonly

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

bufferedAmountLowThreshold of type unsigned long,

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

id of type unsigned short, readonly

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

label of type DOMString, readonly

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

maxPacketLifeTime of type unsigned short, readonly , nullable

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

negotiated of type boolean, readonly

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

onbufferedamountlow of type EventHandler,
This event handler, of type bufferedamountlow, MUST be supported by all objects implementing the RTCDataChannel interface.
onclose of type EventHandler,
This event handler, of type close, MUST be supported by all objects implementing the RTCDataChannel interface.
onerror of type EventHandler,
This event handler, of type error, MUST be supported by all objects implementing the RTCDataChannel interface.
onmessage of type EventHandler,
This event handler, of type message, MUST be supported by all objects implementing the RTCDataChannel interface.
onopen of type EventHandler,
This event handler, of type open, MUST be supported by all objects implementing the RTCDataChannel interface.
ordered of type boolean, readonly

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

protocol of type DOMString, readonly

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

readyState of type RTCDataChannelState, readonly

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

6.2.2 Methods

close

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

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

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

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

  3. Set channel's readyState attribute to closing.

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

No parameters.
Return type: void
send

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

ParameterTypeNullableOptionalDescription
dataDOMString
Return type: void
send

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

ParameterTypeNullableOptionalDescription
dataBlob
Return type: void
send

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

ParameterTypeNullableOptionalDescription
dataArrayBuffer
Return type: void
send

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

ParameterTypeNullableOptionalDescription
dataArrayBufferView
Return type: void

6.2.3 Dictionary RTCDataChannelInit Members

id of type unsigned short,

Overrides the default selection of id for this channel.

maxPacketLifeTime of type unsigned short,

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

maxRetransmits of type unsigned short,

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

negotiated of type boolean, , defaulting to false

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

ordered of type boolean, , defaulting to true

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

protocol of type DOMString, , defaulting to ""

Subprotocol name used for this channel.

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 result of converting the argument object to a sequence of Unicode characters 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.

dictionary RTCDataChannelEventInit : EventInit {
             RTCDataChannel channel;
};

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

6.3.1 Constructors

RTCDataChannelEvent
readonly attribute RTCDataChannel channel
ParameterTypeNullableOptionalDescription
typeDOMString
eventInitDictRTCDataChannelEventInit

6.3.2 Attributes

channel of type RTCDataChannel, readonly

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

6.3.3 Dictionary RTCDataChannelEventInit Members

channel of type RTCDataChannel,
Issue

TODO

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 RTCPeerConnection {
    readonly    attribute RTCDTMFSender? dtmf;
};

7.1.1 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

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

7.2.1 Attributes

duration of type long, readonly

The duration attribute MUST return the current tone duration value. This value will be the value last set via the insertDTMF() method, or the default value of 100 ms if insertDTMF() was called without specifying the duration.

interToneGap of type long, readonly

The interToneGap attribute MUST return the current value of the between-tone gap. This value will be the value last set via the insertDTMF() method, or the default value of 70 ms if insertDTMF() was called without specifying the interToneGap.

ontonechange of type EventHandler,

This event handler uses the RTCDTMFToneChangeEvent interface to return the character for each tone as it is played out. See RTCDTMFToneChangeEvent for details.

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.

7.2.2 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 are equivalent to A to D. The character ',' indicates a delay of 2 seconds before processing the next character in the tones parameter. All 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. It MUST be 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.

Issue

How are invalid values handled?

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

  1. Set the object's toneBuffer attribute to the value of the first argument, the duration attribute to the value of the second argument, and the interToneGap attribute to the value of the third argument.
  2. If toneBuffer contains any unrecognized characters, throw an InvalidCharacterError exception and abort these steps.
  3. If toneBuffer is an empty string, return.
  4. If the value of the duration attribute is less than 40, set it to 40. If, on the other hand, the value is greater than 6000, set it to 6000.
  5. If the value of the interToneGap attribute is less than 30, set it to 30.
  6. 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 toneBuffer is an empty string, fire an event named tonechange with an empty string at the RTCDTMFSender object and abort these steps.
    2. Remove the first character from toneBuffer and let that character be tone.
    3. Start playout of tone for duration ms on the associated RTP media stream, using the appropriate codec.
    4. Queue a task to be executed in duration + interToneGap ms from now that runs the steps labelled Playout task.
    5. 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.

ParameterTypeNullableOptionalDescription
tonesDOMString
durationlong = 100
interToneGaplong = 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.

dictionary RTCDTMFToneChangeEventInit : EventInit {
             DOMString tone;
};

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

7.3.1 Constructors

RTCDTMFToneChangeEvent
readonly attribute DOMString tone
ParameterTypeNullableOptionalDescription
typeDOMString
eventInitDictRTCDTMFToneChangeEventInit

7.3.2 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 previous tone has completed playback.

7.3.3 Dictionary RTCDTMFToneChangeEventInit Members

tone of type DOMString,
Issue

TODO

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 member of a MediaStream 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
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);
};

8.2.1 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 p be a new promise.

  2. Let selectorArg be the methods first argument.

  3. Run the following steps in parallel:

    1. If selectorArg is an invalid selector, reject p with a new DOMError with name TypeError.

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

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

  4. Return p.

ParameterTypeNullableOptionalDescription
selectorMediaStreamTrack
Return type: Promise<RTCStatsReport>

8.3 RTCStatsCallback

callback RTCStatsCallback = void (RTCStatsReport report);

8.3.1 Callback RTCStatsCallback Parameters

report of type RTCStatsReport

A RTCStatsReport representing the gathered stats.

8.4 RTCStatsReport Object

The getStats() method delivers a successful result in the form of a RTCStatsReport object. A RTCStatsReport object represents a map between strings, identifying the inspected objects (RTCStats.id), and their corresponding RTCStats objects.

An RTCStatsReport may be composed of several RTCStats objects, 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 object per SSRC (which can be distinguished by the value of the "ssrc" stats attribute).

interface RTCStatsReport {
    getter RTCStats (DOMString id);
};

8.4.1 Methods

RTCStats

Getter to retrieve the RTCStats objects that this stats report is composed of.

The set of supported property names [WEBIDL] is defined as the ids of all the RTCStats objects that has been generated for this stats report. The order of the property names is left to the user agent.

ParameterTypeNullableOptionalDescription
idDOMString
Return type: getter

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

Issue
Need to define an IANA registry for this and populate with pointers to existing things such as the RTCP statistics.

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 a RTCStats object.

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

8.5.1 Dictionary RTCStats Members

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.

Issue
Consider naming id something that indicates that the id refers to the underlying object that was inspected to produce the stats, instead of being an id for the JavaScript object. Suggestions: statsObjectId, reporterId, srcId.
timestamp of type DOMHiResTimeStamp,

The timestamp, of type DOMHiResTimeStamp [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.

enum RTCStatsType {
    "inbound-rtp",
    "outbound-rtp"
};
Enumeration description
inbound-rtpInbound RTP.
outbound-rtpOutbund RTP.

8.6 Derived Stats Dictionaries

dictionary RTCRTPStreamStats : RTCStats {
             DOMString ssrc;
             DOMString remoteId;
};

8.6.1 Dictionary RTCRTPStreamStats Members

remoteId of type DOMString,

The remoteId can be used to look up the corresponding RTCStats object that represents stats reported by the other peer.

ssrc of type DOMString,

...

dictionary RTCInboundRTPStreamStats : RTCRTPStreamStats {
             unsigned long packetsReceived;
             unsigned long bytesReceived;
};

8.6.2 Dictionary RTCInboundRTPStreamStats Members

bytesReceived of type unsigned long,

...

packetsReceived of type unsigned long,

...

dictionary RTCOutboundRTPStreamStats : RTCRTPStreamStats {
             unsigned long packetsSent;
             unsigned long bytesSent;
};

8.6.3 Dictionary RTCOutboundRTPStreamStats Members

bytesSent of type unsigned long,

...

packetsSent of type unsigned long,

...

8.7 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 2
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
    for (var i in currentReport) {
        var now = currentReport[i];
        if (now.type != "outboundrtp")
            continue;

        // get the corresponding stats from the baseline report
        base = baselineReport[now.id];

        if (base) {
            remoteNow = currentReport[now.remoteId];
            remoteBase = baselineReport[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 WorkerGlobalScope [WEBWORKERS].

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.

A global property can only be set by the user agent or the IdP proxy itself. Therefore, the IdP proxy can be assured that requests it receives originate from the user agent. This ensures that an arbitrary origin is unable to instantiate an IdP proxy and impersonate this API in order obtain identity assertions.

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

9.2 Registering an IdP Proxy

An IdP proxy implements the RTCIdentityProvider callback interface, which is 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.

interface RTCIdentityProviderRegistrar {
    void register (RTCIdentityProvider idp);
};

9.2.1 Methods

register

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

ParameterTypeNullableOptionalDescription
idpRTCIdentityProvider
Return type: void

9.2.2 Interface Exposed by Identity Providers

The RTCIdentityProvider interface is exposed by identity providers and is called by RTCPeerConnection to acquire or validate identity assertions.

callback interface RTCIdentityProvider {
    Promise<RTCIdentityAssertionResult>  generateAssertion (DOMString contents, DOMString origin, optional DOMString usernameHint);
    Promise<RTCIdentityValidationResult> validateAssertion (DOMString assertion, DOMString origin);
};
9.2.2.1 Methods
generateAssertion

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

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.

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.

The IdP selects the identity to assert. The optional usernameHint parameter is the same value that was passed to setIdentityProvider.

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.

ParameterTypeNullableOptionalDescription
contentsDOMString
originDOMString
usernameHintDOMString
Return type: Promise<RTCIdentityAssertionResult>
validateAssertion

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

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.

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.

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.

ParameterTypeNullableOptionalDescription
assertionDOMString
originDOMString
Return type: Promise<RTCIdentityValidationResult>

9.2.3 Identity Assertion and Validation Results

dictionary RTCIdentityAssertionResult {
    required RTCIdentityProviderDetails idp;
    required DOMString                  assertion;
};
9.2.3.1 Dictionary RTCIdentityAssertionResult Members
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.

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.

dictionary RTCIdentityProviderDetails {
    required DOMString domain;
             DOMString protocol = "default";
};
9.2.3.2 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;
};
9.2.3.3 Dictionary RTCIdentityValidationResult Members
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.

identity of type DOMString, required

The validated identity of the peer.

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 instance 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 returns a Promise to the RTCPeerConnection. If the user has been authenticated by the IdP, and the IdP is willing 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. 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.

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

This process can fail. The IdP proxy MAY reject the promise, or the process of loading and registering the IdP could fail. If assertion generation fails, then the promise for the corresponding function call is rejected.

The browser SHOULD limit the time that it will allow for this process. This includes both the loading of the IdP proxy and the identity assertion generation. Failure to do so potentially causes the corresponding operation to take an indefinite amount of time. This timer can be cancelled when the IdP produces a response. The timer running to completion can be treated as equivalent to an error from the IdP.

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 object that has a name attribute set to "IdpLoginError".

If the rejection object also contains a loginUrl attribute, this value will be passed to the application in the idpLoginUrl attribute. This URL might link to page where a user can enter their (IdP) username and password, or otherwise provide any information the IdP needs to authorize a assertion request.

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 on the RTCIdentityProvider instance 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. 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.

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

    If a peer offers a certificate that doesn't match an a=fingerprint line in the negotiated session description, the user agent MUST NOT permit communication with that peer.

  8. The RTCPeerConnection validates that the domain portion of the identity matches the domain of the IdP as described in [RTCWEB-SECURITY-ARCH].

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

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

This process can fail at any step above. If identity validation fails, the peerIdentity promise is rejected with a DOMError that has a name of IdpError.

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

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.

The browser SHOULD limit the time that it will allow for identity validation. This includes both the loading of the IdP proxy and the identity assertion validation. Failure to do so potentially causes the operation to take an indefinite amount of time. This timer can be cancelled when the IdP produces a response. The timer running to completion is treated as equivalent to an error from the IdP.

9.5 RTCPeerConnection Interface Extensions

The Identity API extends the RTCPeerConnection interface as described below.

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

9.5.1 Attributes

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.

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 there a target peer identity has been established. If this promise successfully resolves, the value will not change.

9.5.2 Methods

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 connection's RTCPeerConnection signalingState is closed, 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>
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 connection's RTCPeerConnection signalingState is closed, throw an InvalidStateError exception and abort these steps.

  2. Set the current identity provider values to the triplet (provider, protocol, usernameHint).

  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.

ParameterTypeNullableOptionalDescription
providerDOMString
protocolDOMString
usernameHintDOMString
Return type: void
[Constructor(DOMString idp, DOMString name)]
interface RTCIdentityAssertion {
                attribute DOMString idp;
                attribute DOMString name;
};

9.5.3 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.6 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 and protocol.

Example 3
pc.setIdentityProvider("example.com", "default", "alice@example.com");

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

Example 4
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 stream 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, 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.2.2 Events on MediaStream

A new media track may be associated with an existing MediaStream. For example, if a remote peer adds a new MediaStreamTrack object to a RTCPeerConnection, and indicates that the MediaStreamTrack is a member of a MediaStream that has already been created locally by the RTCPeerConnection, this is observed on the local user agent. If this happens for the reason exemplified, or for any other reason than the addTrack() method being invoked locally on a MediaStream or tracks being added as the stream is created (i.e. the stream is initialized with tracks), the user agent MUST run the following steps:

  1. Let stream be the target MediaStream object.

  2. Let track be the MediaStreamTrack object representing the media component about to be added.

  3. Add track to stream's track set.

  4. Fire a track event named addtrack with the newly created MediaStreamTrack object at stream.

An existing media track may also be disassociated from a MediaStream. If this happens for any other reason than the removeTrack() method being invoked locally on a MediaStream or the stream being destroyed, the user agent MUST run the following steps:

  1. Let stream be the target MediaStream object.

  2. Let track be the MediaStreamTrack object representing the media component about to be removed.

  3. Remove track from stream's track set.

  4. Fire a track event named removetrack with track at stream.

The event source for the onended event in the networked case is the RTCPeerConnection object.

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 a MediaStream 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

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

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)

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;
};

10.4.1 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.2 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;
};
10.4.2.1 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.3 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.4 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 5
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) {
        if (evt.candidate)
            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({ "sdp": 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 }, function (stream) {
        selfView.srcObject = stream;
        if (stream.getAudioTracks().length > 0)
            pc.addTrack(stream.getAudioTracks()[0], stream);
        if (stream.getVideoTracks().length > 0)
            pc.addTrack(stream.getVideoTracks()[0], stream);
    }, logError);
}

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

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

        // 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 () {
                signalingChannel.send(JSON.stringify({ "sdp": pc.localDescription }));
            })
            .catch(logError);
        } else
            pc.setRemoteDescription(desc).catch(logError);
    } else
        pc.addIceCandidate(new RTCIceCandidate(message.candidate)).catch(logError);
};

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

11.2 Advanced Peer-to-peer Example

This example shows the more complete functionality.

Issue

TODO

Example 6

11.3 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 7
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) {
        if (evt.candidate)
            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({ "sdp": 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.sdp) {
        var desc = new RTCSessionDescription(message.sdp);

        // 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 () {
                signalingChannel.send(JSON.stringify({ "sdp": pc.localDescription }));
            })
            .catch(logError);
        } else
            pc.setRemoteDescription(desc).catch(logError);
    } else
        pc.addIceCandidate(new RTCIceCandidate(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.4 Call Flow Browser to Browser

Issue

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.5 DTMF Example

Examples assume that sender is an RTCRtpSender.

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

Example 8
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 9
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 10
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 11
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 12
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. 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 Event
Issue

TODO

.
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

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 RTCPeerConnection signalingState has changed. This state change is the result of either setLocalDescription() or setRemoteDescription() being invoked.
iceconnectionstatechange Event The RTCPeerConnection ice connection state has changed.
icegatheringstatechange Event The RTCPeerConnection ice gathering state has changed.
icecandidate RTCPeerConnectionIceEvent A new RTCIceCandidate is made available to the script.
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.

The following events fire on RTCDTMFSender objects:

Event name Interface Fired when...
tonechange Event 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.
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.

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

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.

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.

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.

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

Mitigating the exposure of IP addresses to the application 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 working group is actively discussing what additional text regarding exposure of IP addresses is appropriate for this section.

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.

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.

14. Change Log

This section will be removed before publication.

Changes since June 11, 2015

  1. [#234] Add RTCRtpParameters, RTCRtpSender.getParameters, and RTCRtpSender.setParameters
  2. [#225] Support for pending and current SDP
  3. [#229] Removing the weird optionality from RTCSessionDescription and its constructor.
  4. [#235] Modernize getStats() with promises
  5. [#243] Mark candidate property of RTCIceCandidateInit required
  6. [#248] Fix error handling for certificate management
  7. [#259] Change type of RtpEncodingParameters.priority to an enum
  8. [#21, #262] Sort out 2119 MUSTs and SHOULDs
  9. [#268] Add RtpEncodingParameters.maxBitrate
  10. [#241] Add RtpSender.transport, RtpReceiver.transport, RTCDtlsTransport, RTCIceTransport, etc
  11. [#224, #261] Sort out when responding PeerConnection reaches iceConnetionState completed
  12. [#303] Replace track without renegotiation
  13. [#269] Add RTCRtpSender.getCapabilities and RTCRtpReceiver.getCapabilities

Changes since March 6, 2015

  1. [PR #167] Removed RTCPeerConnection.createDTMFSender and added RTCRtpSender.dtmf, along with corresponding examples.
  2. [PR #184] RTCPeerConnection will NOT connect unless identity is verified.
  3. [PR #27] Documenting practice with candidate events
  4. [PR #203] Rewrote mitigations text for security considerations section
  5. [PR #192] Added support for auth tokens. Fixes #190
  6. [PR #207] Update ice config examples to use multiple urls and *s schemes
  7. [PR #210] Optional RTCConfiguration in RTCPC constructor
  8. [PR #171] Add RTCAnswerOptions (with common RTCOfferAnswerOptions dictionary)
  9. [PR #178] Identity provider interface redesign
  10. [PR #193] Add .mid property to sender/receiver. Fixes #191
  11. [PR #218] Enqueue addIceCandidate
  12. [PR #213 (1)] Rename updateIce() to setConfiguration()
  13. [PR #213 (2)] Make RTCPeerConnection.setConfiguration() replace the existing configuration
  14. [PR #214] Certificate management API (Bug 21880)
  15. [PR #220] Clarify muted state (proposed fix for issue #139)
  16. [PR #221] Define when RTCRtpReceivers are created and dispatced (issue #198)
  17. [PR #215] Adding expires attribute to certificate management
  18. [PR #233] Add a "bufferedamountlow" event

Changes since December 5, 2014

  1. Properly define the negotiationneeded event, and its interactions with other API calls.
  2. Add support for RTCRtpSender and RTCRtpReceiver.
  3. Update misleading local/RemoteDescription attribute text.
  4. Add RTCBundlePolicy.
  5. All callback-based methods have been moved to a legacy section, and replaced by same-named overloads using Promises instead.
  6. [PR #194] Added first version of Security Considerations (more work needed)
  7. Updated identity provider structure.

Changes since June 4, 2014

  1. Bug 25724: Allow garbage collection of closed PeerConnections
  2. Bug 27214: Add onicegatheringstatechange event
  3. Bug 26644: Fixing end of candidates event

Changes since April 10, 2014

  1. Bug 25774: Mixed isolation

Changes since April 10, 2014

  1. Bug 25855: Clarification about conformance requirements phrased as algorithms
  2. Bug 25892: SignalingStateChange event should be fired only if there is a change in signaling state.
  3. Bug 25152: createObjectURL used in examples is no longer supported by Media Capture and Streams.
  4. Bug 25976: DTMFSender.insertDTMF steps should validate the values of duration and interToneGap.
  5. Bug 25189: Mandatory errorCallback is missing in examples for getStats.
  6. Bug 25840: Creating DataChannel with same label.
  7. Updated comment above example ice state transitions (discussed in Bug 25257).
  8. Updated insertDTMF() algorithm to ignore unrecognized characters (as discussed in bug 25977).
  9. Made formatting of references to ice connection state consistent.
  10. Made insertDTMF() throw on unrecognized characters (used to ignore).
  11. Removed requestIdentity from RTCConfiguration and RTCOfferAnswerOptions. Removed RTCOfferAnswerOptions as a result.
  12. Adding isolated property and associated event to MediaStreamTrack.

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. Bug 25155: maxRetransmitTime is not the name of the SCTP concept it points to.

Changes since January 27, 2014

  1. Refined identity assertion generation and validation.
  2. Default DTMF gap changed from 50 to 70 ms.
  3. Bug 24875: Examples in the WebRTC spec are not updated As per the modified API.

Changes since August 30, 2013

  1. Make RTCPeerConnection close method be idempotent.
  2. Clarified ICE server configuration could contain URI types other than STUN and TURN.
  3. Changed the DTMF timing values.
  4. Allow offerToReceiveAudio/video indicate number of streams to offer.
  5. ACTION-98: Added text about clamping of maxRetransmitTime and maxRetransmits.
  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. InvalidMediaStreamTrackError changed to InvalidParameter.
  8. Fire NetworkError when the data transport is closed with an error.
  9. Add an exception for data channel with trying to use existing code.
  10. Change maxRetransmits to be an unsigned type.
  11. Clarify state changes when ICE restarts.
  12. Added InvalidStateError exception for operations on a RTCPeerConnection that is closed.
  13. Major changes to Identity Proxy section.
  14. (ACTION: 95) Moved IceTransports (constraint) to RTCConfiguration dictionary.
  15. (ACTION: 95) Introduced RTCOfferAnswerOptions and RTCOfferOptions dictionaries.
  16. (ACTION: 95) Removed constraints argument from addStream() (and removed IANA Constraints section).
  17. Added validation of the RTCConfiguration dictionary argument(s).
  18. Added getConfiguration() on RTCPeerConnection.

Changes since June 3, 2013

  1. Removed synchronous section left-overs.
  2. RTCIceServer now accepts multiple URLs.
  3. Redefined the meaning of negotiated for DataChannel.
  4. Made iceServers a sequence (instead of an Array).
  5. Updated error reporting (to use DOMError and camel cased names).
  6. Added success and failure callbacks to addIceCandidate().
  7. Made local/remoteDescription attributes nullable.
  8. Added username member to RTCIceServer dictionary.

Changes since March 22, 2013

  1. Added IceRestart constraint.
  2. Big updates on DataChannel API to use new channel setup procedures.

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. Updated RTCPeerConnection state machine. Added a shared processing model for setLocalDescription()/setRemoteDescription().
  3. Updated simple callflow to match the current API.

Changes since Jan 16, 2013

  1. Initial import of Statistics API to version 2.
  2. Integration of Statistics API version 2.5 started.
  3. Updated Statistics API to match Boston/list discussions.
  4. Extracted API extensions introduced by features, such as the P2P Data API, from the RTCPeerConnection API.
  5. Updated DTMF algorithm to dispatch an event when insertDTMF() is called with an empty string to cancel future tones.
  6. Updated DTMF algorithm to not cancel and reschedule if a playout task is running (only update toneBuffer and other values).

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. Replaced the localStreams and remoteStreams attributes with functions returning sequences of MediaStream objects.
  3. Added spec text for attributes and methods adopted from the WebSocket interface.
  4. Changed the state ENUMs and transition diagrams.
  5. Aligned the data channel processing model a bit more with WebSockets (mainly closing the underlying transport).

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. Introduced new representation of tracks in a stream (removed MediaStreamTrackList). Added algorithm for creating a track to represent an incoming network media component.
  3. Renamed MediaStream.label to MediaStream.id (the definition needs some more work).

Changes since Nov 03, 2012

  1. Added text describing the queuing mechanism for RTCPeerConnection.
  2. Updated simple P2P example to include all mandatory (error) callbacks.
  3. Updated P2P data example to include all mandatory (error) callbacks. Also added some missing RTC prefixes.

Changes since Oct 19, 2012

  1. Clarified how createOffer() and createAnswer() use their callbacks.
  2. Made all failure callbacks mandatory.
  3. Added error object types, general error handling principles, and rules for when errors should be thrown.

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.

Changes since Aug 16, 2012

  1. Replaced stringifier with serializer on RTCSessionDescription and RTCIceCandidate (used when JSON.stringify() is called).
  2. Removed offer and createProvisionalAnswer arguments from the createAnswer() method.
  3. Removed restart argument from the updateIce() method.
  4. Made RTCDataChannel an EventTarget
  5. Updated simple RTCPeerConnection example to match spec changes.
  6. Added section about RTCDataChannel garbage collection.
  7. Added stuff for identity proxy.
  8. Added stuff for stats.
  9. Added stuff peer and ice state reporting.
  10. Minor changes to sequence diagrams.
  11. Added a more complete RTCDataChannel example
  12. Various fixes from Dan's Idp API review.
  13. Patched the Stats API.

Changes since Aug 13, 2012

  1. Made the RTCSessionDescription and RTCIceCandidate constructors take dictionaries instead of a strings. Also added detailed stringifier algorithm.
  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. Incorporate changes proposed by Li Li.
  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.

Changes since Jul 20, 2012

  1. Added RTC Prefix to names (including the notes below).
  2. Moved to new definition of configuration and ice servers object.
  3. Added correlating lines to candidate structure.
  4. Converted setLocalDescription and setRemoteDescription to be asynchronous.
  5. Added call flows.

Changes since Jul 13, 2012

  1. Removed peer attribute from RTCPeerConnectionIceEvent (duplicates functionality of Event.target attribute).
  2. Removed RTCIceCandidateCallback (no longer used).
  3. Removed RTCPeerConnectionEvent (we use a simple event instead).
  4. Removed RTCSdpType argument from setLocalDescription() and setRemoteDescription(). Updated simple example to match.

Changes since May 28, 2012

  1. Changed names to use RTC Prefix.
  2. Changed the data structure used to pass in STUN and TURN servers in configuration.
  3. Updated simple RTCPeerConnection example (RTCPeerConnection constructor arguments; use icecandidate event).
  4. Initial import of new Data API.
  5. Removed some left-overs from the old Data Stream API.
  6. Renamed "underlying data channel" to "underlying data transport". Fixed closing procedures. Fixed some typos.

Changes since April 27, 2012

  1. Major rewrite of RTCPeerConnection section to line up with IETF JSEP draft.
  2. Added simple RTCPeerConnection example. Initial update of RTCSessionDescription and RTCIceCandidate to support serialization and construction.

Changes since 21 April 2012

  1. Moved MediaStream and related definitions to getUserMedia.
  2. Removed section "Obtaining local multimedia content".
  3. Updated getUserMedia() calls in examples (changes in Media Capture TF spec).
  4. Introduced MediaStreamTrackList interface with support for adding and removing tracks.
  5. Updated the algorithm that is run when RTCPeerConnection receives a stream (create new stream when negotiated instead of when data arrives).

Changes since 12 January 2012

  1. Clarified the relation of Stream, Track, and Channel.

Changes since 17 October 2011

  1. Tweak the introduction text and add a reference to the IETF RTCWEB group.
  2. Changed the first argument to getUserMedia to be an object.
  3. Added a MediaStreamHints object as a second argument to RTCPeerConnection.addStream.
  4. Added AudioMediaStreamTrack class and DTMF interface.

Changes since 23 August 2011

  1. Separated the SDP and ICE Agent into separate agents and added explicit state attributes for each.
  2. Removed the send method from PeerConenction and associated callback function.
  3. Modified MediaStream() constructor to take a list of MediaStreamTrack objects instead of a MediaStream. Removed text about MediaStream parent and child relationship.
  4. Added abstract.
  5. Moved a few paragraphs from the MediaStreamTrack.label section to the MediaStream.label section (where they belong).
  6. Split MediaStream.tracks into MediaStream.audioTracks and MediaStream.videoTracks.
  7. Removed a sentence that implied that track access is limited to LocalMediaStream.
  8. Updated a few getUserMedia()-examples to use MediaStreamOptions.
  9. Replaced calls to URL.getObjectURL() with URL.createObjectURL() in example code.
  10. Fixed some broken getUserMedia() links.
  11. Introduced state handling on MediaStreamTrack (removed state handling from MediaStream).
  12. Reintroduced onended on MediaStream to simplify checking if all tracks are ended.
  13. Aligned the MediaStreamTrack ended event dispatching behavior with that of MediaStream.
  14. Updated the LocalMediaStream.stop() algorithm to implicitly use the end track algorithm.
  15. Replaced an occurrence the term finished track with ended track (to align with rest of spec).
  16. Moved (and extended) the explanation about track references and media sources from LocalMediaStream to MediaStreamTrack.

A. Acknowledgements

The editors wish to thank the Working Group chairs and Team Contact, Harald Alvestrand, Stefan Håkansson 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, and Eric Rescorla.

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

[FIPS-180-3]
FIPS PUB 180-3 Secure Hash Standard. U.S. Department of Commerce/National Institute of Standards and Technology. URL: http://csrc.nist.gov/publications/fips/fips180-3/fips180-3_final.pdf
[GETUSERMEDIA]
Daniel Burnett; Adam Bergkvist; Cullen Jennings; Anant Narayanan. Media Capture and Streams. 14 April 2015. W3C Last Call Working Draft. URL: http://www.w3.org/TR/mediacapture-streams/
[HIGHRES-TIME]
Jatinder Mann. High Resolution Time Specification. 18 October 2012. W3C Editor's Draft. URL: http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/HighResolutionTime/Overview.html
[HTML]
Ian Hickson. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[HTML5]
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5. 28 October 2014. W3C Recommendation. URL: http://www.w3.org/TR/html5/
[ICE]
J. Rosenberg. 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
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC3388]
G. Camarillo; G. Eriksson; J. Holler; H. Schulzrinne. Grouping of Media Lines in the Session Description Protocol (SDP). December 2002. Proposed Standard. URL: https://tools.ietf.org/html/rfc3388
[RFC5389]
J. Rosenberg; R. Mahy; P. Matthews; D. Wing. Session Traversal Utilities for NAT (STUN). October 2008. Proposed Standard. URL: https://tools.ietf.org/html/rfc5389
[RFC6236]
I. Johansson; K. Jung. Negotiation of Generic Image Attributes in the Session Description Protocol (SDP). May 2011. Proposed Standard. URL: https://tools.ietf.org/html/rfc6236
[RFC7064]
S. Nandakumar; G. Salgueiro; P. Jones; M. Petit-Huguenin. 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. Traversal Using Relays around NAT (TURN) Uniform Resource Identifiers. November 2013. Proposed Standard. URL: https://tools.ietf.org/html/rfc7065
[RTCWEB-ALPN]
M. Thomson. 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. 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. 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. RTCWeb Data Channel Protocol. 21 October 2013. Active Internet-Draft. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-data-protocol/
[RTCWEB-JSEP]
Justin Uberti; Cullen Jennings. Javascript Session Establishment Protocol. 22 October 2013. Active Internet-Draft. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-jsep/
[RTCWEB-RTP]
C. Perkins; M. Westerlund; J. Ott. 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. WebRTC Security Architecture. 22 January 2014. Active Internet-Draft. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-security-arch/
[RTCWEB-TRANSPORT]
H. Alvestrand. Transports for RTCWEB. 22 January 2014. Active Internet-Draft. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-transports/
[SDP]
J. Rosenberg; H. Schulzrinne. 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. 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. 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]
Cameron McCormack; Boris Zbarsky. WebIDL Level 1. 4 August 2015. W3C Working Draft. URL: http://www.w3.org/TR/WebIDL-1/
[WEBWORKERS]
Ian Hickson. Web Workers. 1 May 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/workers/
[WebCryptoAPI]
Ryan Sleevi; Mark Watson. Web Cryptography API. 11 December 2014. W3C Candidate Recommendation. URL: http://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.
[webmessaging]
Ian Hickson. HTML5 Web Messaging. 19 May 2015. W3C Recommendation. URL: http://www.w3.org/TR/webmessaging/

B.2 Informative references

[INDEXEDDB]
Nikunj Mehta; Jonas Sicking; Eliot Graff; Andrei Popescu; Jeremy Orlow; Joshua Bell. Indexed Database API. 8 January 2015. W3C Recommendation. URL: http://www.w3.org/TR/IndexedDB/
[RFC5322]
P. Resnick, Ed.. Internet Message Format. October 2008. Draft Standard. URL: https://tools.ietf.org/html/rfc5322
[RTCWEB-OVERVIEW]
H. Alvestrand. 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. Security Considerations for WebRTC. 22 January 2014. Active Internet-Draft. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-security/
[TRICKLE-ICE]
E. Ivov; E. Rescorla; J. Uberti. 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. The WebSocket API. 20 September 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/websockets/
[XMLHttpRequest]
Anne van Kesteren; Julian Aubourg; Jungkee Song; Hallvord Steen et al. XMLHttpRequest Level 1. 30 January 2014. W3C Working Draft. URL: http://www.w3.org/TR/XMLHttpRequest/