WebRTC 1.0: Real-time Communication Between Browsers

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.

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;
    RTCIceTransports       iceTransports = "all";
    DOMString              peerIdentity;
};

4.2.1.1 Dictionary `RTCConfiguration` Members

iceServers of type sequence<RTCIceServer>: An array containing URIs of servers available to be used by ICE, such as STUN and TURN server.
iceTransports of type RTCIceTransports, 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 establish a connection to a remote peer unless it can be successfully authenticated with the provided name.

4.2.2 RTCIceServer Type

dictionary RTCIceServer {
    (DOMString or sequence<DOMString>) urls;
    DOMString                          username;
    DOMString                          credential;
};

4.2.2.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.
urls of type (DOMString or sequence<DOMString>): 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": "turn:turn.example.org", "username": "user", "credential": "myPassword" } ]

4.2.3 RTCIceTransports Enum

enum RTCIceTransports {
    "none",
    "relay",
    "all"
};

Enumeration description
`none`	The ICE engine MUST not send or receive any packets at this point.
`relay`	The 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.
`all`	The ICE engine may use any type of candidates when this value is specified.

4.2.4 Offer/Answer Options

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

dictionary RTCOfferOptions {
    long    offerToReceiveVideo;
    long    offerToReceiveAudio;
    boolean voiceActivityDetection = true;
    boolean iceRestart = false;
};

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

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.

enum RTCIdentityOption {
    "yes",
    "no",
    "ifconfigured"
};

Enumeration description
`yes`	An identity MUST be requested.
`no`	No identity is to be requested.
`ifconfigured`	The value "ifconfigured" means that an identity will be requested if either the user has configured an identity in the browser or if the `setIdentityProvider()` call has been made in JavaScript. As this is the default value, an identity will be requested if and only if the user has configured an IdP in some way.

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.

An RTCPeerConnection object has two associated stream sets. A local streams set, representing streams that are currently sent, and a remote streams set, representing streams that are currently received with this RTCPeerConnection object. The stream sets are initialized to empty sets when the RTCPeerConnection object is created.

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

Validate the RTCConfiguration argument by running the steps defined by the updateIce() method.
Let connection be a newly created RTCPeerConnection object.
Create an ICE Agent as defined in [ICE] and let connection's RTCPeerConnection ICE Agent be that ICE Agent and provide it the the ICE servers list. 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.
Set connection's RTCPeerConnection signalingState to stable.
Set connection's RTCPeerConnection ice connection state to new.
Set connection's RTCPeerConnection ice gathering state to new.
Initialize an internal variable to represent a queue of operations with an empty set.
Return connection.

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

Append an object representing the current call being handled (i.e. function name and corresponding arguments) to the operations array.
If the length of the operations array is exactly 1, execute the function from the front of the queue asynchronously.
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:

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

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:

Let connection be the RTCPeerConnection object associated with this ICE Agent.
If connection's RTCPeerConnection signalingState is closed, abort these steps.
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.
Fire a icecandidate event named icecandidate with newCandidate at connection.

User agents negotiate the codec resolution, bitrate, and other media parameters. It is RECOMMENDED that user agents initially negotiate for the maximum resolution of a video stream. For streams that are then rendered (using a video element), it is RECOMMENDED that user agents renegotiate for a resolution that matches the rendered display size.

The word "components" in this context refers to an RTP media flow and does not have anything to do with how [ICE] uses the term "component".

When a user agent has reached the point where a MediaStream can be created to represent incoming components, the user agent MUST run the following steps:

Let connection be the RTCPeerConnection expecting this media.
Create a MediaStream object stream, to represent the incoming media stream.
Run the algorithm to represent an incoming component with a track for each incoming component.

Note
The creation of new incoming MediaStreams may be triggered either by SDP negotiation or by the receipt of media on a given flow.
Queue a task to run the following substeps:
1. If the connection's RTCPeerConnection signalingState is closed, abort these steps.
2. Add stream to connection's remote streams set.
3. Fire a stream event named addstream with stream at the connection object.

When a user agent has negotiated media for a component that belongs to a media stream that is already represented by an existing MediaStream object, the user agent MUST associate the component with that MediaStream object.

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

Let connection be the RTCPeerConnection associated with the stream being removed.
Let stream be the MediaStream object that represents the media stream being removed, if any. If there isn't one, then abort these steps.
By definition, stream is now ended.

Note
A task is thus queued to update stream and fire an event.
Queue a task to run the following substeps:
1. If the connection's RTCPeerConnection signalingState is closed, abort these steps.
2. Remove stream from connection's remote streams set.
3. Fire a stream event named removestream with stream at the connection object.

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

If something in the browser changes that causes the RTCPeerConnection object to need to initiate a new session description negotiation, a negotiationneeded event is fired at the RTCPeerConnection object.

In particular, if an RTCPeerConnection object is consuming a MediaStream on which a track is added, by, e.g., the addTrack() method being invoked, the RTCPeerConnection object MUST fire the "negotiationneeded" event. Removal of media components must also trigger "negotiationneeded".

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

[ Constructor (RTCConfiguration configuration)]
interface RTCPeerConnection : EventTarget  {
    void                  createOffer (RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback, optional RTCOfferOptions options);
    void                  createAnswer (RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback);
    void                  setLocalDescription (RTCSessionDescription description, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback);
    readonly    attribute RTCSessionDescription? localDescription;
    void                  setRemoteDescription (RTCSessionDescription description, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback);
    readonly    attribute RTCSessionDescription? remoteDescription;
    readonly    attribute RTCSignalingState      signalingState;
    void                  updateIce (RTCConfiguration configuration);
    void                  addIceCandidate (RTCIceCandidate candidate, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback);
    readonly    attribute RTCIceGatheringState   iceGatheringState;
    readonly    attribute RTCIceConnectionState  iceConnectionState;
    RTCConfiguration      getConfiguration ();
    sequence<MediaStream> getLocalStreams ();
    sequence<MediaStream> getRemoteStreams ();
    MediaStream?          getStreamById (DOMString streamId);
    void                  addStream (MediaStream stream);
    void                  removeStream (MediaStream stream);
    void                  close ();
                attribute EventHandler           onnegotiationneeded;
                attribute EventHandler           onicecandidate;
                attribute EventHandler           onsignalingstatechange;
                attribute EventHandler           onaddstream;
                attribute EventHandler           onremovestream;
                attribute EventHandler           oniceconnectionstatechange;
                attribute EventHandler           onicegatheringstatechange;
};

4.3.2.1 Constructors

RTCPeerConnection

See the RTCPeerConnection constructor algorithm.

Parameter	Type	Nullable	Optional	Description
configuration	`RTCConfiguration`	âœ˜	âœ˜

4.3.2.2 Attributes

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 the RTCSessionDescription that was most recently passed to setLocalDescription(), plus any local candidates that have been generated by the ICE Agent since then.

A null object will be returned if the local description has not yet been set.

onaddstream of type EventHandler,

This event handler, of event handler event type addstream, MUST be fired by all objects implementing the RTCPeerConnection interface. It is called any time a MediaStream is added by the remote peer. This will be fired only as a result of setRemoteDescription. Onnaddstream happens as early as possible after the setRemoteDescription. This callback does not wait for a given media stream to be accepted or rejected via SDP negotiation.

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.

onremovestream of type EventHandler,

This event handler, of event handler event type removestream, MUST be fired by all objects implementing the RTCPeerConnection interface. It is called any time a MediaStream is removed by the remote peer. This will be fired only as a result of setRemoteDescription.

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

remoteDescription of type RTCSessionDescription, readonly , nullable

The remoteDescription attribute MUST return the RTCSessionDescription that was most recently passed to setRemoteDescription(), plus any remote candidates that have been supplied via addIceCandidate() since then.

A null object will be returned if the remote description has not yet been set.

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.

If the candidate parameter is malformed, throw a SyntaxError exception and abort these steps.

If the candidate is successfully applied, the user agent MUST queue a task to invoke successCallback.

If the candidate could not be successfully applied, the user agent MUST queue a task to invoke failureCallback with a DOMError object whose name attribute has the value TBD (TODO InvalidCandidate and InvalidMidIndex).

Note

What errors do we need here? Should we reuse the *SessionDescriptionError names or invent new ones for candidates? Should this method be queued?

Parameter	Type	Nullable	Optional
candidate	`RTCIceCandidate`	âœ˜	âœ˜
successCallback	`VoidFunction`	âœ˜	âœ˜
failureCallback	`RTCPeerConnectionErrorCallback`	âœ˜	âœ˜

Return type: void

addStream

Adds a new stream to the RTCPeerConnection.

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

Let connection be the RTCPeerConnection object on which the MediaStream, stream, is to be added.
If connection's RTCPeerConnection signalingState is closed, throw an InvalidStateError exception and abort these steps.
If stream is already in connection's local streams set, then abort these steps.
Add stream to connection's local streams set.
A stream 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 stream CORS cross-origin. These streams can be added to the local streams set but content MUST NOT be transmitted, though streams marked with peerIdentity can be transmitted if they meet the requirements for sending (see ).

All other streams 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 stream content.

Note that this property can change over time.

If connection's RTCPeerConnection signalingState is stable, then fire a negotiationneeded event at connection.

Parameter	Type	Nullable	Optional	Description
stream	`MediaStream`	âœ˜	âœ˜

Return type: void

close

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

If the RTCPeerConnection object's RTCPeerConnection signalingState is closed, abort these steps.
Destroy the RTCPeerConnection ICE Agent, abruptly ending any active ICE processing and any active streaming, and releasing any relevant resources (e.g. TURN permissions).
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 generating an error if setLocalDescription is called from the successCallback function. 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 successCallback function. 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, then the session description SHALL contain an appropriate assertion.

If this RTCPeerConnection object is closed before the SDP generation process completes, the USER agent MUST suppress the result and not call any of the result callbacks.

If the SDP generation process completed successfully, the user agent MUST queue a task to invoke successCallback with a newly created RTCSessionDescription object, representing the generated answer, as its argument.

If the SDP generation process failed for any reason, the user agent MUST queue a task to invoke failureCallback with an DOMError object of type TBD as its argument.

Parameter	Type	Nullable	Optional	Description
successCallback	`RTCSessionDescriptionCallback`	âœ˜	âœ˜
failureCallback	`RTCPeerConnectionErrorCallback`	âœ˜	âœ˜

Return type: void

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 within the successCallback function. 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 end of the successCallback function. Calling this method is needed to get the ICE user name fragment and password.

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

If this RTCPeerConnection object is closed before the SDP generation process completes, the USER agent MUST suppress the result and not call any of the result callbacks.

If the SDP generation process failed for any reason, the user agent MUST queue a task to invoke failureCallback with an DOMError object of type TBD as its argument.

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

Parameter	Type	Nullable	Optional
successCallback	`RTCSessionDescriptionCallback`	âœ˜	âœ˜
failureCallback	`RTCPeerConnectionErrorCallback`	âœ˜	âœ˜
options	`RTCOfferOptions`	âœ˜	âœ”

Return type: void

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.

No parameters.

Return type: RTCConfiguration

getLocalStreams

Returns a sequence of MediaStream objects representing the streams that are currently sent with this RTCPeerConnection object.

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

No parameters.

Return type: sequence<MediaStream>

getRemoteStreams

Returns a sequence of MediaStream objects representing the streams that are currently received with this RTCPeerConnection object.

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

No parameters.

Return type: sequence<MediaStream>

getStreamById

If a MediaStream object, with an id equal to streamId, exists in this RTCPeerConnection object's stream sets (local streams set or remote streams set), then the getStreamById() method MUST return that MediaStream object. The method MUST return null if no stream matches the streamId argument.

Note

For this method to make sense, we need to make sure that ids are unique within the two stream sets of a RTCPeerConnection. This is not the case today when a peer re-adds a stream that is received. Two different stream instances will now have the same id at both peers; one in the remote stream set and one in the local stream set.

One way to resolve this is to not allow re-adding a stream instance that is received (guard on id). If an application really needs this functionality it's really easy to make a clone of the stream, which will give it a new id, and send the clone.

Parameter	Type	Nullable	Optional	Description
streamId	`DOMString`	âœ˜	âœ˜

Return type: MediaStream, nullable

removeStream

Removes the given stream from the RTCPeerConnection.

When the other peer stops sending a stream in this manner, a removestream event is fired at the RTCPeerConnection object.

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

Let connection be the RTCPeerConnection object on which the MediaStream, stream, is to be removed.
If connection's RTCPeerConnection signalingState is closed, throw an InvalidStateError exception.
If stream is not in connection's local streams set, then abort these steps.
Remove stream from connection's local streams set.
If connection's RTCPeerConnection signalingState is stable, then fire a negotiationneeded event at connection.

Parameter	Type	Nullable	Optional	Description
stream	`MediaStream`	âœ˜	âœ˜

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 old and new 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 new local description, or rollback to the old description if the remote side denied the change.

Issue 1

ISSUE: how to indicate to rollback?

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

When the method is invoked, the user agent must follow the processing model described by the following list:

If this RTCPeerConnection object's signaling state is closed, the user agent MUST throw an InvalidStateError exception and abort this operation.
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".
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 errorType be InvalidSessionDescriptionError.
  - The RTCSessionDescription is a valid description but cannot be applied at the media layer.
    
    TODO ISSUE - 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 errorType be IncompatibleSessionDescriptionError. If rollback was not possible, let errorType be InternalError and set connection's signaling state to closed.
4. Invoke the failureCallback with an DOMError object, whose name attribute is errorType, as its argument.
If the RTCSessionDescription argument is applied successfully, 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. Set connection's description attribute ( localDescription or remoteDescription depending on the setting operation) to the RTCSessionDescription argument.
4. 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.
5. If the local description was set with content that caused an ICE restart, then set connection's ice gathering state to gathering.
6. Set connection's signalingState accordingly.
7. If connection's signalingState changed, fire a simple event named signalingstatechange at connection.
8. Queue a new task that, if connection's signalingState is not closed, invokes the successCallback.

Parameter	Type	Nullable	Optional
description	`RTCSessionDescription`	âœ˜	âœ˜
successCallback	`VoidFunction`	âœ˜	âœ˜
failureCallback	`RTCPeerConnectionErrorCallback`	âœ˜	âœ˜

Return type: 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(), with the following additional conditions:

If an a=identity attribute is present in the session description, the browser validates the identity assertion.. Identity validation completes asynchronously and does not block the completion of setRemoteDescription, unless there is 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 throw an InvalidStateError exception and abort this operation.
If the "peerIdentity" configuration is applied to the RTCPeerConnection, this establishes a target peer identity. 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.

If there is a target peer identity, then setRemoteDescription fails unless it contains an identity assertion that matches the target peer identity. The RTCPeerConnection MAY be closed if the validated peer identity does not match the target peer identity.

Parameter	Type	Nullable	Optional
description	`RTCSessionDescription`	âœ˜	âœ˜
successCallback	`VoidFunction`	âœ˜	âœ˜
failureCallback	`RTCPeerConnectionErrorCallback`	âœ˜	âœ˜

Return type: void

updateIce

The updateIce 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 updateIce() method is invoked, the user MUST run the following steps to process the RTCConfiguration dictionary:

If the iceTransports member is present, let its value be the ICE Agent's ICE transports setting.
If the iceTransports member was omitted and the ICE Agent's ICE transports setting is unset, set the ICE Agent's ICE transports setting to the iceTransports dictionary member default value.
If the iceServers dictionary member is present, but its value is an empty list, then throw an InvalidAccessError and abort these steps. If the list, on the other hand, has elements, each element must be validated by running the following sub-steps:
1. Let server be the current list element.
2. If the server.urls dictionary member is omitted or an empty list, then throw an InvalidAccessError and abort these steps.
3. If server.urls is a string, let urls be a list consisting of just that string. Otherwise, let urls refer to the server.urls list.
4. For each url in 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.
After passing the validation, let the iceServers dictionary member 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.
If the iceServers dictionary member was omitted, and the ICE Agent's ICE servers list is unset, throw an InvalidAccessError and abort these steps.

Note

The exception types throw in the above algorithm are provisional (until we decide what to do in each case).

Parameter	Type	Nullable	Optional	Description
configuration	`RTCConfiguration`	âœ˜	âœ˜

Return type: void

4.3.3 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 RTCDTMFSender, 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 RTCPeerState Enum

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

Enumeration description
`stable`	There is no offeranswer exchange in progress. This is also the initial state in which case the local and remote descriptions are empty.
`have-local-offer`	A local description, of type "offer", has been successfully applied.
`have-remote-offer`	A remote description, of type "offer", has been successfully applied.
`have-local-pranswer`	A remote description of type "offer" has been successfully applied and a local description of type "pranswer" has been successfully applied.
`have-remote-pranswer`	A local description of type "offer" has been successfully applied and a remote description of type "pranswer" has been successfully applied.
`closed`	The connection is closed.

The non-normative peer state transitions are:

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
`new`	The object was just created, and no networking has occurred yet.
`gathering`	The ICE engine is in the process of gathering candidates for this RTCPeerConnection.
`complete`	The 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
`new`	The ICE Agent is gathering addresses and/or waiting for remote candidates to be supplied.
`checking`	The 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.
`connected`	The 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.
`completed`	The ICE Agent has finished gathering and checking and found a connection for all components. Open issue: it is not clear how the non controlling ICE side knows it is in the state.
`failed`	The 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.
`disconnected`	Liveness 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.
`closed`	The 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:

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

Errors are indicated in two ways: exceptions and objects passed to error callbacks. Exceptions are thrown to indicate invalid state and other programming errors. For example when a 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. In all other cases, an error object MUST be provided 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.

Note

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.
IncompatibleMediaStreamTrackError: The provided MediaStreamTrack is not an element of a MediaStream that is currently in the RTCPeerConnection's localStreams attribute.
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"
};

Enumeration description
`offer`	An RTCSdpType of "offer" indicates that a description should be treated as an [SDP] offer.
`pranswer`	An RTCSdpType of "pranswer" indicates that a description should 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 should be treated as an [SDP] final answer, and the offer-answer exchange should 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".

4.7.2 RTCSessionDescription Class

dictionary RTCSessionDescriptionInit {
    RTCSdpType type;
    DOMString  sdp;
};

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

4.7.2.1 Constructors

RTCSessionDescription

The RTCSessionDescription() constructor takes an optional dictionary argument, descriptionInitDict, whose content is used to initialize the new RTCSessionDescription object. If a dictionary key is not present in descriptionInitDict, the corresponding attribute will be initialized to null. If the constructor is run without the dictionary argument, all attributes will be initialized to null. This class is a future extensible carrier for the data contained in it and does not perform any substantive processing.

Parameter	Type	Nullable	Optional	Description
descriptionInitDict	`RTCSessionDescriptionInit`	âœ˜	âœ”

4.7.2.2 Attributes

sdp of type DOMString, , nullable: The string representation of the SDP [SDP]
type of type RTCSdpType, , nullable: The type of SDP this RTCSessionDescription represents.

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
type of type RTCSdpType: DOMString sdp

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 Interfaces for Connectivity Establishment

4.8.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 {
    DOMString      candidate;
    DOMString      sdpMid;
    unsigned short sdpMLineIndex;
};

[ Constructor (optional RTCIceCandidateInit candidateInitDict)]
interface RTCIceCandidate {
                attribute DOMString?      candidate;
                attribute DOMString?      sdpMid;
                attribute unsigned short? sdpMLineIndex;
    serializer = {attribute};
};

4.8.1.1 Constructors

RTCIceCandidate

The RTCIceCandidate() constructor takes an optional dictionary argument, candidateInitDict, whose content is used to initialize the new RTCIceCandidate object. If a dictionary key is not present in candidateInitDict, the corresponding attribute will be initialized to null. If the constructor is run without the dictionary argument, all attributes will be initialized to null.

Parameter	Type	Nullable	Optional	Description
candidateInitDict	`RTCIceCandidateInit`	âœ˜	âœ”

4.8.1.2 Attributes

candidate of type DOMString, , nullable: 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 m-line this candidate is associated with.

4.8.1.3 Serializer

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

4.8.1.4 Dictionary `RTCIceCandidateInit` Members

candidate of type DOMString: DOMString sdpMid
sdpMLineIndex of type unsigned short
sdpMid of type DOMString: unsigned short sdpMLineIndex

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

dictionary RTCPeerConnectionIceEventInit : EventInit {
    RTCIceCandidate candidate;
};

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

4.8.2.1 Constructors

RTCPeerConnectionIceEvent

readonly attribute RTCIceCandidate candidate

Parameter	Type	Nullable	Optional	Description
type	`DOMString`	âœ˜	âœ˜
eventInitDict	`RTCPeerConnectionIceEventInit`	âœ˜	âœ˜

4.8.2.2 Attributes

candidate of type RTCIceCandidate, readonly: The candidate attribute is the RTCIceCandidate object with the new ICE candidate that caused the event.

4.8.2.3 Dictionary `RTCPeerConnectionIceEventInit` Members

candidate of type RTCIceCandidate: TODO

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

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

5.1.1 Attributes

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

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

If the RTCPeerConnection object's RTCPeerConnection signalingState is closed, throw an InvalidStateError exception and abort these steps.
Let channel be a newly created RTCDataChannel object.
Initialize channel's label attribute to the value of the first argument.
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).
If both the maxPacketLifeTime and maxRetransmits attributes are set (not null), then throw a SyntaxError exception and abort these steps.
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.
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.
Return channel and continue the following steps in the background.
Create channel's associated underlying data transport and configure it according to the relevant properties of channel.

Parameter	Type	Nullable	Optional	Description
label	`DOMString`	âœ˜	âœ˜
dataChannelDict	`RTCDataChannelInit`	âœ˜	âœ”

Return type: RTCDataChannel

5.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 (TODO: reference needed).

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:

If the associated RTCPeerConnection object's RTCPeerConnection signalingState is closed, abort these steps.
Let channel be the RTCDataChannel object to be announced.
Set channel's readyState attribute to open.
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:

If the associated RTCPeerConnection object's RTCPeerConnection signalingState is closed, abort these steps.
Let channel be a newly created RTCDataChannel object.
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.
Initialize channel's label, ordered, maxPacketLifeTime, maxRetransmits, protocol, negotiated and id attributes to their corresponding values in configuration.
Set channel's readyState attribute to connecting.
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.

Note

References to protocol specification are needed.

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

Let channel be the RTCDataChannel object whose transport was closed.

Note
The data transport protocol will specify what happens to, e.g. buffered data, when the data transport is closed.
Set channel's readyState attribute to closed.
If the transport was closed with an error, fire an NetworkError event at channel.
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 EventHandler        onopen;
                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);
};

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

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.

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

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

Let channel be the RTCDataChannel object which is about to be closed.
If channel's readyState is closing or closed, then abort these steps.
Set channel's readyState attribute to closing.
If the closing procedure has not started yet, start it.

No parameters.

Return type: void

send

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

Parameter	Type	Nullable	Optional	Description
data	`DOMString`	âœ˜	âœ˜

Return type: void

send

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

Parameter	Type	Nullable	Optional	Description
data	`Blob`	âœ˜	âœ˜

Return type: void

send

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

Parameter	Type	Nullable	Optional	Description
data	`ArrayBuffer`	âœ˜	âœ˜

Return type: void

send

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

Parameter	Type	Nullable	Optional	Description
data	`ArrayBufferView`	âœ˜	âœ˜

Return type: void

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

Let channel be the RTCDataChannel object on which data is to be sent.
If channel's readyState attribute is connecting, throw an InvalidStateError exception and abort these steps.
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.
If channel's underlying data transport is not established yet, or if the closing procedure has started, then abort these steps.
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.

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

5.3.1 Constructors

RTCDataChannelEvent

readonly attribute RTCDataChannel channel

Parameter	Type	Nullable	Optional	Description
type	`DOMString`	âœ˜	âœ˜
eventInitDict	`RTCDataChannelEventInit`	âœ˜	âœ˜

5.3.2 Attributes

channel of type RTCDataChannel, readonly: The channel attribute represents the RTCDataChannel object associated with the event.

5.3.3 Dictionary `RTCDataChannelEventInit` Members

channel of type RTCDataChannel: TODO

5.4 Garbage Collection

A RTCDataChannel object MUST not be garbage collected if its

readyState is connecting and at least one event listener is registered for open events, message events, error events, or close events.
readyState is open and at least one event listener is registered for message events, error events, or close events.
readyState is closing and at least one event listener is registered for error events, or close events.
underlying data transport is established and data is queued to be transmitted.

Parameter	Type	Nullable	Optional	Description
track	`MediaStreamTrack`	âœ˜	âœ˜

Parameter	Type	Nullable	Optional
tones	`DOMString`	âœ˜	âœ˜
duration	`long = 100`	âœ˜	âœ”
interToneGap	`long = 70`	âœ˜	âœ”

7. Statistics Model

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

Note

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.

7.2 RTCPeerConnection Interface Extensions

The Statistics API extends the RTCPeerConnection interface as described below.

partial interface RTCPeerConnection {
    void getStats (MediaStreamTrack? selector, RTCStatsCallback successCallback, RTCPeerConnectionErrorCallback failureCallback);
};

7.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 queue a task to run the following steps:

If the RTCPeerConnection object's RTCPeerConnection signalingState is closed, throw an InvalidStateError exception.
Return, but continue the following steps in the background.
Let selectorArg be the methods first argument.
If selectorArg is an invalid selector, the user agent MUST queue a task to invoke the failure callback (the method's third argument).
Start gathering the stats indicated by selectorArg. In case selectorArg is null, stats MUST be gathered for the whole RTCPeerConnection object.
When the relevant stats have been gathered, queue a task to invoke the success callback (the method's second argument) with a new RTCStatsReport object, representing the gathered stats, as its argument.

Parameter	Type	Nullable	Optional
selector	`MediaStreamTrack`	âœ”	âœ˜
successCallback	`RTCStatsCallback`	âœ˜	âœ˜
failureCallback	`RTCPeerConnectionErrorCallback`	âœ˜	âœ˜

Return type: void

7.3 RTCStatsCallback

callback RTCStatsCallback = void (RTCStatsReport report);

7.3.1 Callback `RTCStatsCallback` Parameters

report of type RTCStatsReport: A RTCStatsReport representing the gathered stats.

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

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

Parameter	Type	Nullable	Optional	Description
id	`DOMString`	âœ˜	âœ˜

Return type: getter

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

Note

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

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

Note

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-rtp`	Inbound RTP.
`outbound-rtp`	Outbund RTP.

7.6 Derived Stats Dictionaries

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

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

7.6.2 Dictionary `RTCInboundRTPStreamStats` Members

bytesReceived of type unsigned long: ...
packetsReceived of type unsigned long: ...

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

7.6.3 Dictionary `RTCOutboundRTPStreamStats` Members

bytesSent of type unsigned long: ...
packetsSent of type unsigned long: ...

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

var baselineReport, currentReport;
var selector = pc.getRemoteStreams()[0].getAudioTracks()[0];

pc.getStats(selector, function (report) {
    baselineReport = report;
}, logError);

// ... wait a bit
setTimeout(function () {
    pc.getStats(selector, function (report) {
        currentReport = report;
        processStats();
    }, logError);
}, aBit);

function processStats() {
    // compare the elements from the current report with the baseline
    for (var i in currentReport) {
        var now = currentReport[i];
        if (now.type != "outbund-rtp")
            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;
        }
    }
}

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

8. Identity

8.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 the offer/answer acts as the Authenticating Party (AP) and obtains an identity assertion from the IdP which it attaches to the offer/answer. The consumer of the offer/answer (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, which is deterministic from the IdP's identity, and the generic protocol for requesting and verifying 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. The generic protocol details are described in [RTCWEB-SECURITY-ARCH]. This document specifies the procedures required to instantiate the IdP proxy, request identity assertions, and consume the results.

8.1.1 Identity Provider Selection

In order to communicate with the IdP, the browser instantiates an isolated interpreted context, effectively an invisible IFRAME. The initial contents of the context are loaded from a URI derived from the IdP's domain name, as described in [RTCWEB-SECURITY-ARCH].

For purposes of generating assertions, the IdP shall be chosen as follows:

If the setIdentityProvider() method has been called, the IdP provided shall be used.
If the setIdentityProvider() method has not been called, then the browser can 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.

8.1.2 Instantiating an IdP Proxy

The browser creates an IdP proxy by loading an isolated, invisible IFRAME with HTML content from the IdP URI. The URI for the IdP is a well-known URI formed from the domain and protocol fields, as specified in [RTCWEB-SECURITY-ARCH].

When an IdP proxy is requiured, the browser performs the following steps:

An invisible, sandboxed IFRAME is created within the browser context. The IFRAME sandbox attribute is set to "allow-forms allow-scripts allow-same-origin" to limit the capabilities available to the IdP. The browser MUST prevent the IdP proxy from navigating the browsing context to a different location. The browser MUST prevent the IdP proxy from interacting with the user (this includes, in particular, popup windows and user dialogs).
Once the IdP proxy is created, the browser creates a MessageChannel [webmessaging] within the context of the IdP proxy and assigns one port from the channel to a variable named rtcwebIdentityPort on the window. This message channel forms the basis of communication between the browser and the IdP proxy. Since it is an essential security property of the web sandbox that a page is unable to insert objects into content from another origin, this ensures that the IdP proxy can trust that messages originating from window.rtcwebIdentityPort are from RTCPeerConnection and not some other page. This protection ensures that pages from other origins are unable to instantiate IdP proxies and obtain identity assertions.
The IdP proxy completes loading and informs the RTCPeerConnection that it is ready by sending a "READY" message to the message channel port [RTCWEB-SECURITY-ARCH]. Once this message is received by the RTCPeerConnection, the IdP is considered ready to receive requests to generate or verify identity assertions.

[TODO: This is not sufficient unless we expect the IdP to protect this information. Otherwise, the a=identity information can be copied from a session with "good" properties to any other session with the same fingerprint information. Since we want to reuse credentials, that would be bad.] The identity mechanism MUST provide an indication to the remote side of whether it requires the stream contents to be protected. Implementations MUST have an user interface that indicates the different cases and identity for these.

8.2 Requesting Identity Assertions

The identity assertion request process involves the following steps:

The RTCPeerConnection instantiates an IdP proxy as described in Identity Provider Selection section and waits for the IdP to signal that it is ready.
The RTCPeerConnection sends a "SIGN" message to the IdP proxy. This message includes the material the RTCPeerConnection desires to be bound to the user's identity.
If the user has been authenticated by the IdP, and the IdP is willing to generate an identity assertion, the IdP generates an identity assertion. This step depends entirely on the IdP. The methods by which an IdP authenticates users or generates assertions is not specified, though this could involve interacting with the IdP server or other servers.
The IdP proxy sends a response containing the identity assertion to the RTCPeerConnection over the message channel.
The RTCPeerConnection MAY store the identity assertion for use with future offers or answers.
If the identity request was triggered by a createOffer() or createAnswer(), then the assertion is inserted in the offer/answer SDP.

The format and contents of the messages that are exchanged are described in detail in [RTCWEB-SECURITY-ARCH].

The IdP proxy can return an "ERROR" response. If an error is encountered, the browser MUST generate an idpassertionerror event. No "a=identity" attribute is added to SDP as a result.

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.

8.2.1 User Login Procedure

An IdP could respond to a request to generate an identity assertion with a "LOGINNEEDED" error. This indicates that the site does not have the necessary information available to it (such as cookies) to authorize the creation of an identity assertion.

The "LOGINNEEDED" response includes a URL for a page where the authorization process can be completed. This URL is exposed to the application through the loginUrl attribute of the idpassertionerror event. This URL might be to a page where a user is able to 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; the resulting page then provides the user with an opportunity to provide 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 be the DOMString "LOGINDONE". This message informs the application that another attempt at generating an identity assertion is likely to be successful.

8.3 Verifying Identity Assertions

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

The identity assertion request process involves the following steps:

The RTCPeerConnection instantiates an IdP proxy as described in Identity Provider Selection section and waits for the IdP to signal that it is ready.
The RTCPeerConnection sends a "VERIFY" message to the IdP proxy. This message includes the assertion from the offer/answer which is to be verified.
The IdP proxy verifies the identity assertion (depending on the authentication protocol this could involve interacting with the IDP server).
Once the assertion is verified, the IdP proxy sends a response containing the verified assertion results to the RTCPeerConnection over the message channel.
The RTCPeerConnection validates that the fingerprint provided by the IdP in the validation response matches the certificate fingerprint that is, or will be, used for communications. This is either by:
- Ensuring that there is only a single a=fingerprint value across all media sections in the SDP that matches the fingerprint provided by the IdP.
- Waiting for all DTLS connections to be establishes and checking that the certificate fingerprints on all connections matches the one provided by the IdP.
The RTCPeerConnection validates that the domain portion of the identity matches the domain of the IdP as described in [RTCWEB-SECURITY-ARCH].
The RTCPeerConnection stores the assertion in the peerIdentity attribute and raises a simple event named peeridentity at itself. The assertion information to be displayed MUST contain the domain name of the IdP as provided in the assertion.
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.

The IdP might fail to validate the identity assertion by providing an "ERROR" response to the validation request. Validation can also fail due to the additional checks performed by the browser. In both cases, the process terminates and no identity information is exposed to the application or the user.

The browser MUST raise an idpvalidationerror event if validation of an identity assertion fails for any reason.

If the "peerIdentity" constraint is applied to the RTCPeerConnection, any error MUST cause setRemoteDescription to fail.

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

The format and contents of the messages that are exchanged are described in detail in [RTCWEB-SECURITY-ARCH].

8.4 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 username);
    void getIdentityAssertion ();
    readonly    attribute RTCIdentityAssertion? peerIdentity;
                attribute EventHandler          onidentityresult;
                attribute EventHandler          onpeeridentity;
                attribute EventHandler          onidpassertionerror;
                attribute EventHandler          onidpvalidationerror;
};

8.4.1 Attributes

onidentityresult of type EventHandler,: This event handler, of event handler event type identityresult, MUST be fired by all objects implementing the RTCPeerConnection interface. This event is fired when an identity assertion is successfully generated. Note: this event is fired when an identity assertion is generated during the creation of an offer or answer.
onidpassertionerror of type EventHandler,: This event handler of type idpassertionerror MUST be fired when an IdP encounters an error in generating an identity assertion.
onidpvalidationerror of type EventHandler,: This event handler of type idvalidationperror MUST be fired when an IdP encounters an error in validating an identity assertion.
onpeeridentity of type EventHandler,: This simple event handler of type peeridentity MUST be fired when a peer identity from a peer is successfully validated.
peerIdentity of type RTCIdentityAssertion, readonly , nullable: Contains the peer identity assertion information if an identity assertion was provided and verified. Once this value is set to a non-null value, it cannot change.

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

If the connection's RTCPeerConnection signalingState is closed, abort these steps.
Request an identity assertion from the IdP.

No parameters.

Return type: void

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 will be used to get an assertion.

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

If the connection's RTCPeerConnection signalingState is closed, throw an InvalidStateError exception and abort these steps.
Set the current identity provider values to the triplet (provider, protocol, username).
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 the need to generate SDP with either createOffer or createAnswer.

Parameter	Type	Nullable	Optional
provider	`DOMString`	âœ˜	âœ˜
protocol	`DOMString`	âœ˜	âœ”
username	`DOMString`	âœ˜	âœ”

Return type: void

8.5 RTCIdentityAssertion Type

dictionary RTCIdentityAssertion {
    DOMString idp;
    DOMString name;
};

8.5.1 Dictionary `RTCIdentityAssertion` Members

idp of type DOMString: A domain name representing the identity provider.
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].

8.6 RTCIdentityEvent Type

The RTCIdentiytEvent is raised when an IdP produces an identity assertion.

[NoInterfaceObject]
interface RTCIdentityEvent : Event {
                attribute DOMString assertion;
};

8.6.1 Attributes

assertion of type DOMString,: A string containing the encoded identity assertion (the information that would be added to the "a=identity" line in SDP [RTCWEB-SECURITY-ARCH]).

8.7 RTCIdentityErrorEvent Type

The RTCIdentityErrorEvent is raised when an IdP fails to successfully produce an identity assertion.

[NoInterfaceObject]
interface RTCIdentityErrorEvent : Event {
                attribute DOMString  idp;
                attribute DOMString  protocol;
                attribute DOMString? loginUrl;
};

8.7.1 Attributes

idp of type DOMString,: The domain name of the identity provider that is providing the error response.
loginUrl of type DOMString, , nullable: An IdP that is unable to generate an identity assertion due to a lack of sufficient user authentication information can provide a URL to a page where the user can complete authentication. If the IdP provides this URL, this attribute includes the value provided by the IdP.
protocol of type DOMString,: The IdP protocol that is in use.

8.8 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 2

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

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

Example 3

pc.onpeeridentity = function(e) {
  console.log("IdP= " + e.target.peerIdentity.idp +
              " identity=" + e.target.peerIdentity.name);
};

9. Media Stream API Extensions for Network Use

9.1 Introduction

The MediaStream interface, as defined in the [GETUSERMEDIA] specification, typically represents a stream of data of audio and/or video. A MediaStream may be extended to represent a stream that either comes from or is sent to a remote node (and not just the local camera, for instance). The extensions required to enable this capability on the MediaStream 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 MediaStream as defined in [GETUSERMEDIA] may contain zero or more MediaStreamTrack objects. 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.

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 MediaStream apply in the case of MediaStream objects transmitted over the network as well. A MediaStream created by an RTCPeerConnection object (described later in this document) will take as input the data received from a remote peer. Similarly, a MediaStream 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 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 tracks from different MediaStream objects into a new MediaStream 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.

9.2 MediaStream

9.2.1 id

The id attribute specified in MediaStream returns an id that is unique to this stream, so that streams can be recognized after they are sent through 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).

9.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 MediaStream that is being sent over an 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:

Let stream be the target MediaStream object.
Represent component with track: Run the following steps to create a track representing the incoming component:
1. Create a MediaStreamTrack object track to represent the component.
2. Initialize track's kind attribute to "audio" or "video" depending on the media type of the incoming component.
3. Initialize track's id attribute to the component track id.
4. Initialize track's label attribute to "remote audio" or "remote video" depending on the media type of the incoming component.
5. Initialize track's readyState attribute to muted.
6. Add track to stream's track set.
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:

Let stream be the target MediaStream object.
Let track be the MediaStreamTrack object representing the media component about to be removed.
Remove track from stream's track set.
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.

9.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 a track belongs to a MediaStream that 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 3

ISSUE: How do you know when it has stopped? This seems like an SDP question, not a media-level question.

A track in a MediaStream, received with an RTCPeerConnection, MUST have its readyState attribute [GETUSERMEDIA] set to muted until media data arrives.

In addition, a MediaStreamTrack has its readyState set to muted on the remote peer if the local user agent disables the corresponding MediaStreamTrack in the MediaStream that is being sent. When the addstream event triggers on an RTCPeerConnection, all MediaStreamTrack objects in the resulting MediaStream are muted until media data can be read from the RTP source.

Issue 4

ISSUE: How do you know when it has been disabled? This seems like an SDP question, not a media-level question.

9.4 MediaStreamEvent

The addstream and removestream events use the MediaStreamEvent interface.

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

dictionary MediaStreamEventInit : EventInit {
    MediaStream stream;
};

[ Constructor (DOMString type, MediaStreamEventInit eventInitDict)]
interface MediaStreamEvent : Event {
    readonly    attribute MediaStream? stream;
};

9.4.1 Constructors

MediaStreamEvent

readonly attribute MediaStream? stream

Parameter	Type	Nullable	Optional	Description
type	`DOMString`	âœ˜	âœ˜
eventInitDict	`MediaStreamEventInit`	âœ˜	âœ˜

9.4.2 Attributes

stream of type MediaStream, readonly , nullable: The stream attribute represents the MediaStream object associated with the event.

9.4.3 Dictionary `MediaStreamEventInit` Members

stream of type MediaStream: TODO

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

dictionary MediaStreamConstraints {
    DOMString peerIdentity;
};

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

Displayed in an appropriate media tag (e.g., a video or audio element). The browser MUST ensure that content is inaccessible to the application by ensuring that the resulting content is given the same protections as content that is CORS cross-origin, as described in the relevant Security and privacy considerations section of [HTML5].
Used as the argument to addStream() on an RTCPeerConnection instance, subject to the restrictions in .

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.

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

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

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

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

Event name	Interface	Fired when...
`open`	`Event`	The `RTCDataChannel` object's underlying data transport has been established (or re-established).
`MessageEvent`	`Event`	A message was successfully received. TODO: Ref where MessageEvent is defined?
`error`	`Event`	TODO.
`close`	`Event`	The `RTCDataChannel` object's underlying data transport has bee closed.

Event name	Interface	Fired when...
`connecting`	`Event`	TODO
`addstream`	`MediaStreamEvent`	A new stream has been added to the remote streams set.
`removestream`	`MediaStreamEvent`	A stream has been removed from the remote streams set.
`negotiationneeded`	`Event`	The browser wishes to inform the application that session negotiation needs to be done at some point in the near future.
`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.
`identityresult`	`RTCIdentityEvent`	A new `RTCIdentityEvent` is dispatched to the script when an identity assertion is successfully generated by an IdP.
`peeridentity`	`Event`	A new `Event` is dispatched to the script when an identity assertion provided by a peer is successfully validated.
`idpassertionerror`	`RTCIdentityErrorEvent`	A new `RTCIdentityErrorEvent` is dispatched to the script when an IdP encounters an error while generating an identity assertion.
`idpvalidationerror`	`RTCIdentityErrorEvent`	A new `RTCIdentityErrorEvent` is dispatched to the script when an IdP encounters an error while validating an identity assertion.

Abstract

Status of This Document

Table of Contents

1. Introduction

2. Conformance

3. Terminology

4. Peer-to-peer connections

4.1 Introduction

4.2 Configuration

4.2.1 RTCConfiguration Type

4.2.1.1 Dictionary RTCConfiguration Members

4.2.2 RTCIceServer Type

4.2.2.1 Dictionary RTCIceServer Members

4.2.3 RTCIceTransports Enum

4.2.4 Offer/Answer Options

4.2.4.1 Dictionary RTCOfferOptions Members

4.3 RTCPeerConnection Interface

4.3.1 Operation

4.3.2 Interface Definition

4.3.2.1 Constructors

4.3.2.2 Attributes

4.3.2.3 Methods

4.3.3 Garbage collection

4.4 State Definitions

4.4.1 RTCPeerState Enum

4.4.2 RTCIceGatheringState Enum

4.4.3 RTCIceConnectionState Enum

4.5 Callback Definitions

4.5.1 RTCPeerConnectionErrorCallback

4.5.1.1 Callback RTCPeerConnectionErrorCallback Parameters

4.6 Error Handling

4.6.1 General Principles

4.6.2 RTCSdpError

4.6.2.1 Attributes

4.7 Session Description Model

4.7.1 RTCSdpType

4.7.2 RTCSessionDescription Class

4.7.2.1 Constructors

4.7.2.2 Attributes

4.7.2.3 Serializer

4.7.2.4 Dictionary RTCSessionDescriptionInit Members

4.7.3 RTCSessionDescriptionCallback

4.7.3.1 Callback RTCSessionDescriptionCallback Parameters

4.8 Interfaces for Connectivity Establishment

4.8.1 RTCIceCandidate Type

4.8.1.1 Constructors

4.8.1.2 Attributes

4.8.1.3 Serializer

4.8.1.4 Dictionary RTCIceCandidateInit Members

4.8.2 RTCPeerConnectionIceEvent

4.8.2.1 Constructors

4.8.2.2 Attributes

4.8.2.3 Dictionary RTCPeerConnectionIceEventInit Members

5. Peer-to-peer Data API

5.1 RTCPeerConnection Interface Extensions

5.1.1 Attributes

5.1.2 Methods

5.2 RTCDataChannel

5.2.1 Attributes

5.2.2 Methods

5.2.3 Dictionary RTCDataChannelInit Members

5.3 RTCDataChannelEvent

5.3.1 Constructors

5.3.2 Attributes

5.3.3 Dictionary RTCDataChannelEventInit Members

5.4 Garbage Collection

6. Peer-to-peer DTMF

6.1 RTCPeerConnection Interface Extensions

6.1.1 Methods

6.2 RTCDTMFSender

6.2.1 Attributes

6.2.2 Methods

6.3 RTCDTMFToneChangeEvent

6.3.1 Constructors

6.3.2 Attributes

6.3.3 Dictionary RTCDTMFToneChangeEventInit Members

7. Statistics Model

7.1 Introduction

7.2 RTCPeerConnection Interface Extensions

7.2.1 Methods

4.2.1.1 Dictionary `RTCConfiguration` Members

4.2.2.1 Dictionary `RTCIceServer` Members

4.2.4.1 Dictionary `RTCOfferOptions` Members

4.5.1.1 Callback `RTCPeerConnectionErrorCallback` Parameters

4.7.2.4 Dictionary `RTCSessionDescriptionInit` Members

4.7.3.1 Callback `RTCSessionDescriptionCallback` Parameters

4.8.1.4 Dictionary `RTCIceCandidateInit` Members

4.8.2.3 Dictionary `RTCPeerConnectionIceEventInit` Members

5.2.3 Dictionary `RTCDataChannelInit` Members

5.3.3 Dictionary `RTCDataChannelEventInit` Members

6.3.3 Dictionary `RTCDTMFToneChangeEventInit` Members

7.3.1 Callback `RTCStatsCallback` Parameters

7.5.1 Dictionary `RTCStats` Members

7.6.1 Dictionary `RTCRTPStreamStats` Members

7.6.2 Dictionary `RTCInboundRTPStreamStats` Members

7.6.3 Dictionary `RTCOutboundRTPStreamStats` Members

8.5.1 Dictionary `RTCIdentityAssertion` Members

9.4.3 Dictionary `MediaStreamEventInit` Members

9.5.1 Dictionary `MediaStreamConstraints` Members