W3C

WebRTC 1.0: Real-time Communication Between Browsers

W3C Editor's Draft 13 February 2013

This version:
http://dev.w3.org/2011/webrtc/editor/webrtc.html
Latest published version:
http://www.w3.org/TR/webrtc/
Latest editor's draft:
http://dev.w3.org/2011/webrtc/editor/webrtc.html
Previous editor's draft:
http://dev.w3.org/2011/webrtc/editor/archives/20120920/webrtc.html
Editors:
Adam Bergkvist, Ericsson
Daniel C. Burnett, Voxeo
Cullen Jennings, Cisco
Anant Narayanan, Mozilla (until November 2012)

Abstract

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

Status of This Document

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

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

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

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

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

Table of Contents

1. Introduction

This section is non-normative.

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

This document defines the APIs used for these features. This specification is being developed in conjunction with a protocol specification developed by the IETF RTCWEB group and an API specification to get access to local media devices developed by the Media Capture Task Force.

2. Conformance

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

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

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

3. Terminology

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

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

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

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.

4.2 Configuration

4.2.1 RTCConfiguration Type

dictionary RTCConfiguration {
    RTCIceServer[] iceServers;
};
4.2.1.1 Dictionary RTCConfiguration Members
iceServers of type array of RTCIceServer

An array containing STUN and TURN servers available to be used by ICE.

4.2.2 RTCIceServer Type

dictionary RTCIceServer {
    DOMString  url;
    DOMString? credential;
};
4.2.2.1 Dictionary RTCIceServer Members
credential of type DOMString, nullable

If the url element of the internal array is a TURN URI, then this is the credential to use with that TURN server.

url of type DOMString

A STUN or TURN URI as defined in [STUN-URI] and [TURN-URI].

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:

[ { url:"stun:stun.example.net" } , { url:"turn:user@turn.example.org", credential:"myPassword"} ]

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 [STUN] and [TURN] servers. 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. This algorithm has a synchronous section (which is triggered as part of the event loop algorithm).

  1. Create an ICE Agent as defined in [ICE] and let connection's RTCPeerConnection ICE Agent be that ICE Agent and provide it the STUN and TURN servers from the configuration array. The ICE Agent will proceed with gathering as soon as the IceTransports constraint 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.

  2. Set connection's RTCPeerConnection signalingState to stable.

  3. Set connection's RTCPeerConnection ice connection state to starting.

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

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

  6. Return connection, but continue these steps asynchronously.

  7. Await a stable state. The synchronous section consists of the remaining steps of this algorithm.

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

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

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

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

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

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

  1. If iceConnectionState is "starting" and the IceTransports constraint is not set to "none", it must queue a task to start gathering ICE addresses and set the iceConnectionState to "gathering".

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

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

  4. If the iceConnectionState is "connected" or "completed" and both the local and remote session descriptions have received a valid SDP offer / answer pair, the RTCPeerConnection state is set to "stable".

  5. If the iceConnectionState is "failed", a task is queued to call the close method.

    Issue 1

    Open Issue: CJ - this seems wrong to me - just because a network connection failed does not mean the PC should be put into a dead state it can not recover from.

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:

  1. Let connection be the RTCPeerConnection expecting this media.

  2. Create a MediaStream object stream, to represent the incoming media stream.

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

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

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

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

  3. By definition, stream is now finished.

    Note

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

  4. Queue a task to run the following substeps:

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

    2. Remove 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, optional MediaConstraints constraints)]
interface RTCPeerConnection : EventTarget  {
    void                  createOffer (RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback, optional MediaConstraints constraints);
    void                  createAnswer (RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback, optional MediaConstraints constraints);
    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 (optional RTCConfiguration configuration, optional MediaConstraints constraints);
    void                  addIceCandidate (RTCIceCandidate candidate);
    readonly attribute RTCIceGatheringState  iceGatheringState;
    readonly attribute RTCIceConnectionState iceConnectionState;
    sequence<MediaStream> getLocalStreams ();
    sequence<MediaStream> getRemoteStreams ();
    MediaStream?          getStreamById (DOMString streamId);
    void                  addStream (MediaStream stream, optional MediaConstraints constraints);
    void                  removeStream (MediaStream stream);
    void                  close ();
             attribute EventHandler          onnegotiationneeded;
             attribute EventHandler          onicecandidate;
             attribute EventHandler          onopen;
             attribute EventHandler          onstatechange;
             attribute EventHandler          onaddstream;
             attribute EventHandler          onremovestream;
             attribute EventHandler          ongatheringchange;
             attribute EventHandler          onicechange;
};
4.3.2.1 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 connection state.

localDescription of type RTCSessionDescription, readonly

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.
ongatheringchange of type EventHandler
This event handler, of event handler event type icechange, must be fired by all objects implementing the RTCPeerConnection interface. It is called any time the iceGatheringState changes. NOTE: Is this really of type icechange??
onicecandidate of type EventHandler
This event handler, of event handler event type icecandidate, must be supported by all objects implementing the RTCPeerConnection interface. It is called any time there is a new ICE candidate added to a previous offer or answer.
onicechange of type EventHandler
This event handler, of event handler event type icechange, must be fired by all objects implementing the RTCPeerConnection interface. It is called any time the iceConnectionState changes.
onnegotiationneeded of type EventHandler
This event handler, of event handler event type negotiationneeded , must be supported by all objects implementing the RTCPeerConnection interface.
onopen of type EventHandler
This event handler, of event handler event type open, must be supported by all objects implementing the RTCPeerConnection interface.
Note

Open issue if the "onopen" is needed or not.

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.
onstatechange of type EventHandler
This event handler, of event handler event type statechange, 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

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.2 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 "IceTransports" constraint 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.

An exception with an RTCError object of type INVALID_CANDIDATE_TYPE is thrown if candidate parameter is malformed.

ParameterTypeNullableOptionalDescription
candidateRTCIceCandidate
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:

  1. If the RTCPeerConnection object's RTCPeerConnection signalingState is closed, abort these steps, and throw an exception with an RTCError object of type INVALID_STATE.

  2. If stream is already in the RTCPeerConnection object's local streams set, then abort these steps.

  3. Add stream to the RTCPeerConnection object's local streams set.

  4. Parse the constraints provided by the application and apply them to the MediaStream, if possible. If the constraints could not be successfully applied, provide an RTCError object of type INCOMPATIBLE_CONSTRAINTS to the failure callback.

  5. Fire a negotiationneeded event.

    Issue 3

    ISSUE: Should this fire if the RTCPeerConnection is in "new"?

ParameterTypeNullableOptionalDescription
streamMediaStream
constraintsMediaConstraints
Return type: void
close

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

  1. If the RTCPeerConnection object's RTCPeerConnection signalingState is closed, throw an INVALID_STATE exception.

  2. Destroy the RTCPeerConnection ICE Agent, abruptly ending any active ICE processing and any active streaming, and releasing any relevant resources (e.g. TURN permissions).

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

No parameters.
Return type: void
createAnswer

The createAnswer method generates an [SDP] answer with the supported configuration for the session that is compatible with the parameters in the remote configuration. Like createOffer, the returned blob contains descriptions of the local MediaStreams attached to this RTCPeerConnection, the codec/RTP/RTCP options negotiated for this session, and any candidates that have been gathered by the ICE Agent. The constraints 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 errorCallback with an RTCError object of type TBD as its argument.

An exception with an RTCError object of type INVALID_CONSTRAINTS_TYPE is thrown if the constraints parameter is malformed, and an RTCError object of type INCOMPATIBLE_CONSTRAINTS is provided to the failure callback if the constraints could not be successfully applied.

ParameterTypeNullableOptionalDescription
successCallbackRTCSessionDescriptionCallback
failureCallbackRTCPeerConnectionErrorCallback
constraintsMediaConstraints
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 constraints parameter may be supplied to provide additional control over the offer generated. More information about constraints can be found in [RTCWEB-CONSTRAINTS].

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 setLocalDiscription 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 completed successfully, the user agent must queue a task to invoke successCallback with a newly created RTCSessionDescription object, representing the generated offer, as its argument.

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

An exception with an RTCError object of type INVALID_CONSTRAINTS_TYPE is thrown if the constraints parameter is malformed, and an RTCError object of type INCOMPATIBLE_CONSTRAINTS is provided to the failure callback if the constraints could not be successfully applied.

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

ParameterTypeNullableOptionalDescription
successCallbackRTCSessionDescriptionCallback
failureCallbackRTCPeerConnectionErrorCallback
constraintsMediaConstraints
Return type: void
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 trackId, 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 PeerConnection. 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.

ParameterTypeNullableOptionalDescription
streamIdDOMString
Return type: MediaStream, nullable
removeStream

Removes the given stream from the localStream array in the RTCPeerConnection and fires the negotiationneeded event.

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:

  1. If the RTCPeerConnection object's RTCPeerConnection signalingState is closed, throw an INVALID_STATE exception.

  2. If stream is not in the RTCPeerConnection object's local streams set, then abort these steps.

  3. Remove stream from the RTCPeerConnection object's local streams set.

  4. Fire a negotiationneeded event.

ParameterTypeNullableOptionalDescription
streamMediaStream
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 roll back to the old description if the remote side denied the change.

Issue 2

ISSUE: how to indicate to roll back?

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

Changes to the state of media transmission will occur when a final answer is successfully applied. localDescription must return the previous description until the new description is successfully applied.

The failureCallback will be called if the RTCSessionDescription is a valid description but cannot be applied at the media layer, e.g., if there are insufficient resources to apply the SDP. The user agent must roll back as necessary if the new description was partially applied when the failure occurred.

An RTCError object of type INVALID_SESSION_DESCRIPTION is provided to the failure callback if the SDP content is invalid.

ParameterTypeNullableOptionalDescription
descriptionRTCSessionDescription
successCallbackVoidFunction
failureCallbackRTCPeerConnectionErrorCallback
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.

If a=identity attributes are present, the browser verifies the identity following the procedures in [XREF sec.identity-proxy-assertion-request].

Changes to the state of media transmission will occur when a final answer is successfully applied. remoteDescription must return the previous description until the new description is successfully applied.

The failureCallback will be called if the RTCSessionDescription is a valid description but cannot be applied at the media layer, e.g., if there are insufficient resources to apply the SDP. The user agent must roll back as necessary if the new description was partially applied when the failure occurred.

An RTCError object of type INVALID_SESSION_DESCRIPTION is provided to the failure callback if the SDP content is invalid.

ParameterTypeNullableOptionalDescription
descriptionRTCSessionDescription
successCallbackVoidFunction
failureCallbackRTCPeerConnectionErrorCallback
Return type: void
updateIce

The updateIce method updates the ICE Agent process of gathering local candidates and pinging remote candidates. If there is a mandatory constraint called "IceTransports" it will control how the ICE engine can act. This can be used to limit the use to TURN candidates by a callee to avoid leaking location information prior to the call being accepted.

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.

Note
This method was previously used to restart ICE. We should document the new procedure in the correct place.

An exception with an RTCError object of type INVALID_CONSTRAINTS_TYPE is thrown if the constraints parameter is malformed, and an RTCError object of type INCOMPATIBLE_CONSTRAINTS is provided to the failure callback if the constraints could not be successfully applied.

ParameterTypeNullableOptionalDescription
configurationRTCConfiguration
constraintsMediaConstraints
Return type: void

4.3.3 Garbage collection

A Window object has a strong reference to any RTCPeerConnection objects created from the constructor whose global object is that Window 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
stableThere is no offer­answer exchange in progress. This is also the initial state in which case the local and remote descriptions are empty.
have-local-offerA local description, of type "offer", has been supplied.
have-remote-offerA remote description, of type "offer", has been supplied.
have-local-pranswerA remote description of type "offer" has been supplied and a local description of type "pranswer" has been supplied.
have-remote-pranswerA local description of type "offer" has been supplied and a remote description of type "pranswer" has been supplied.
closedThe connection is closed.

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

An example set of transitions might be:

Caller transition:

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

Callee transition:

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

4.4.2 RTCIceGatheringState Enum

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

4.4.3 RTCIceConnectionState Enum

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

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

  • checking occurs if ANY component has received a candidate and can start checking
  • connected occurs if ALL components have established a working connection
  • completed occurs if ALL components have finalized the running of their ICE processes
  • failed occurs if ANY component has given up trying to connect
  • disconnected occurs if ANY component has failed liveness checks
  • closed occurs only if PeerConnection.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.

An example transition might look like:

  • new PeerConnection(): Starting
  • (Starting, 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): Starting
  • close(): Closed

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

4.5 Callback Definitions

4.5.1 RTCPeerConnectionErrorCallback

callback RTCPeerConnectionErrorCallback = void (RTCError error);
4.5.1.1 Callback RTCPeerConnectionErrorCallback Parameters
error of type RTCError
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. Both forms of error reporting must provide an object of type RTCError. An exception must be thrown in the following cases:

  • The type of any argument passed to a function did not match what was expected. An appropriate string from the RTCExceptionName enum must be used as the error name.
  • A function call was made when the RTCPeerConnection is in an invalid state, or a state in which that particular function is not allowed to be executed. In this case, the string INVALID_STATE must be used as the error name.

In all other cases, an error object must be provided to the failure callback. The error name in the object provided must be picked from either the RTCExceptionName or RTCErrorName enums.

4.6.2 RTCError

interface RTCError {
    readonly attribute DOMString  name;
    readonly attribute DOMString? message;
};
4.6.2.1 Attributes
message of type DOMString, readonly, nullable
A human readable description of the error. This string may vary between different user agents.
name of type DOMString, readonly
A string representing the type of error. This string must be one of those defined by the RTCExceptionName or RTCErrorName enums for the error object to be valid.

4.6.3 RTCSdpError

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

4.6.4 RTCExceptionName

enum RTCExceptionName {
    "INVALID_CONSTRAINTS_TYPE",
    "INVALID_CANDIDATE_TYPE",
    "INVALID_MEDIASTREAM_TRACK",
    "INVALID_STATE"
};
Enumeration description
INVALID_CONSTRAINTS_TYPEThe provided constraints object is not a dictionary with either the mandatory or optional keys.
INVALID_CANDIDATE_TYPEThe provided candidate is not an object of type RTCIceCandidate.
INVALID_MEDIASTREAM_TRACKThe provided track is not an object of type MediaStreamTrack.
INVALID_STATEThe function was called on a RTCPeerConnection that is an invalid state, or a state in which the function is not allowed to be executed.

4.6.5 RTCErrorName

enum RTCErrorName {
    "INVALID_SESSION_DESCRIPTION",
    "INCOMPATIBLE_CONSTRAINTS",
    "INCOMPATIBLE_MEDIASTREAMTRACK"
};
Enumeration description
INVALID_SESSION_DESCRIPTIONThe provided RTCSessionDescription either contained invalid SDP, or 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.
INCOMPATIBLE_CONSTRAINTSThe 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.
INCOMPATIBLE_MEDIASTREAMTRACKThe provided MediaStreamTrack is not an element of a MediaStream that is currently in the RTCPeerConnection's localStreams attribute.

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

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.

Objects implementing the RTCSessionDescription interface must serialize with the serialization pattern "{ attribute }".

dictionary RTCSessionDescriptionInit {
    RTCSdpType type;
    DOMString  sdp;
};

[Constructor (optional RTCSessionDescriptionInit descriptionInitDict)] interface RTCSessionDescription { attribute RTCSdpType? type; attribute DOMString? sdp; serializer = {attribute}; };
4.7.2.1 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.2 Serializer

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

4.7.2.3 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

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. This class is a future extensible carrier for the data contained in it and does not perform any substantive processing.

Objects implementing the RTCIceCandidate interface must serialize with the serialization pattern "{ attribute }".

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 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 [RFC 3388] for the m-line this candidate is associated with.
4.8.1.2 Serializer

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

4.8.1.3 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 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.2 Dictionary RTCPeerConnectionIceEventInit Members
candidate of type RTCIceCandidate

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.

Issue 4: More Open Issues
  • Data channel setup signaling (signaling via SDP and application specific signaling channel or first channel via SDP and consecutive channels via internal signaling).
  • What can be shared with the WebSocket API specification regarding actual interfaces.

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. A corresponding RTCDataChannel object is dispatched at the other peer if the channel setup was successful.

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

  1. If the RTCPeerConnection object’s RTCPeerConnection signalingState is closed, throw an INVALID_STATE exception.

  2. Let channel be a newly created RTCDataChannel object.

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

  4. Initialize channel's reliable attribute to true.

  5. If the second argument is present and it contains a reliable dictionary member, then set channel's reliable attribute to the dictionary member value.

  6. Return channel and continue these steps in the background.

  7. Create channel's associated underlying data transport.

ParameterTypeNullableOptionalDescription
labelDOMString
dataChannelDictRTCDataChannelInit
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 corresponding RTCDataChannel object is then dispatched at the other peer if the channel setup was successful.

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 reliability mode, are configured by the peer taking the initiative to create the channel. The other peer cannot change any transport properties of an offered data channel. The actual wire protocol between the peers is out of the scope for this specification.

A RTCDataChannel created with createDataChannel() must initially be in the connecting state. If the RTCDataChannel object’s underlying data transport is successfully set up, the user agent must announce the RTCDataChannel as open.

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

  1. If the associated RTCPeerConnection object's RTCPeerConnection signalingState is closed, abort these steps.

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

  3. Set channel's readyState attribute to open.

  4. Fire a simple event named open at channel.

When an underlying data transport has been established, the user agent of the peer that did not initiate the creation process must queue a task to run the following steps:

  1. If the associated RTCPeerConnection object's RTCPeerConnection signalingState is closed, abort these steps.

  2. Let configuration be an information bundle with key-value pairs, received from the other peer as a part of the process to establish the underlying data channel.

  3. Let channel be a newly created RTCDataChannel object.

  4. Initialize channel's label attribute to value that corresponds to the "label" key in configuration.

  5. Initialize channel's reliable attribute to true.

  6. If configuration contains a key named "reliable", set channel's reliable attribute to the corresponding value.

  7. Set channel's readyState attribute to open.

  8. 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 spec 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:

  1. 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.
  2. Set channel's readyState attribute to closed.

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

  4. Fire a simple event named close at channel.

dictionary RTCDataChannelInit {
    boolean reliable;
};

interface RTCDataChannel : EventTarget { readonly attribute DOMString label; readonly attribute boolean reliable; 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).

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. The attribute must return the value to which it was set when the RTCDataChannel object 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.
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).

reliable of type boolean, readonly

The RTCDataChannel.reliable attribute returns true if the RTCDataChannel is reliable, and false otherwise. The attribute must return the value to which it was set when the RTCDataChannel was created.

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 close() method is called, the user agent must run the following steps:

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

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

  3. Set channel's readyState attribute to closing.

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

No parameters.
Return type: void
send

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

ParameterTypeNullableOptionalDescription
dataDOMString
Return type: void
send

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

ParameterTypeNullableOptionalDescription
dataBlob
Return type: void
send

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

ParameterTypeNullableOptionalDescription
dataArrayBuffer
Return type: void
send

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

ParameterTypeNullableOptionalDescription
dataArrayBufferView
Return type: void

5.2.3 Dictionary RTCDataChannelInit Members

reliable of type boolean

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

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

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

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

    • string object:

      Let data be the result of converting the argument object to a sequence of Unicode characters and increase the bufferedAmount attribute by the number of bytes needed to express data as UTF-8.

    • Blob object:

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

    • ArrayBuffer object:

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

    • ArrayBufferView object:

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

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

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

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

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

open

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

closing

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

closed

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

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 Attributes

channel of type RTCDataChannel, readonly

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

5.3.2 Dictionary RTCDataChannelEventInit Members

channel of type RTCDataChannel

TODO

5.4 Garbage Collection

A RTCDataChannel object must not be garbage collected if its

6. Peer-to-peer DTMF

In order to send DTMF (phone keypad) values across an RTCPeerConnection, the user agent needs to know which MediaStreamTrack on which RTCPeerConnection will carry the DTMF. This section describes an interface on RTCPeerConnection to associate DTMF capability with a MediaStreamTrack for that RTCPeerConnection.

6.1 RTCPeerConnection Interface Extensions

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

partial interface RTCPeerConnection {
    RTCDTMFSender createDTMFSender (MediaStreamTrack track);
};

6.1.1 Methods

createDTMFSender

The createDTMFSender() method creates an RTCDTMFSender that references the given MediaStreamTrack. The MediaStreamTrack must be an element of a MediaStream that's currently in the RTCPeerConnection object's local streams set; if not, throw an exception with an RTCError object of type INVALID_MEDIASTREAMTRACK.

ParameterTypeNullableOptionalDescription
trackMediaStreamTrack
Return type: RTCDTMFSender

6.2 RTCDTMFSender

An RTCDTMFSender is created by calling the createDTMFSender() method on an RTCPeerConnection. This constructs an object that exposes the functions required to send DTMF on the given MediaStreamTrack.

[NoInterfaceObject]
interface RTCDTMFSender {
    readonly attribute boolean          canInsertDTMF;
    void insertDTMF (DOMString tones, optional long duration, optional long interToneGap);
    readonly attribute MediaStreamTrack track;
             attribute EventHandler     ontonechange;
    readonly attribute DOMString        toneBuffer;
    readonly attribute long             duration;
    readonly attribute long             interToneGap;
};

6.2.1 Attributes

canInsertDTMF of type boolean, readonly

The canInsertDTMF attribute must indicate if the RTCDTMFSender is capable of sending DTMF.

duration of type long, readonly

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

interToneGap of type long, readonly

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

ontonechange of type EventHandler

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

toneBuffer of type DOMString, readonly

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

track of type MediaStreamTrack, readonly

The track attribute must return the MediaStreamTrack given as argument to the RTCDTMFSender constructor.

6.2.2 Methods

insertDTMF

An RTCDTMFSender object’s insertDTMF() method is used to send DTMF tones.

The tones parameter is treated as a series of characters. The characters 0 through 9, A through D, #, and * generate the associated DTMF tones. The characters a to d are equivalent to A to D. The character ',' indicates a delay of 2 seconds before processing the next character in the tones parameter. Unrecognized characters are ignored.

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

The interToneGap parameter indicates the gap between tones. It must be at least 50 ms. The default value is 50 ms.

Issue 5

ISSUE: How are invalid values handled?

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

  1. If the associated MediaStreamTrack is not connected to the associated RTCPeerConnection, return.
  2. If the canInsertDTMF attribute is false, return.
  3. Set the value of the toneBuffer attribute to the value of the tones argument, the value of the duration attribute to the duration argument if specified, and the value of the interToneGap to the interToneGap argument, if specified.
  4. If a previous invocation of insertDTMF() is active, mark it as cancelled.
  5. If toneBuffer is an empty string, return.
  6. Queue a task that runs the following steps (Playout task):
    1. If this invocation of insertDTMF() has been marked as cancelled, abort these steps.
    2. If toneBuffer is an empty string, fire an event named tonechange with an empty string at the RTCDTMFSender object and abort these steps.
    3. Remove the first character from toneBuffer and let that character be tone.
    4. Start playout of tone for duration ms on the associated RTP media stream, using the appropriate codec.
    5. Queue a task to be executed in duration + interToneGap ms from now that runs the steps labelled "Playout task".
    6. Fire an event named tonechange with a string consisting of tone at the RTCDTMFSender object.

If insertDTMF is called on the same object while an existing task for this object to generate DTMF is still running, the previous task is canceled. Calling insertDTMF with an empty tones parameter can be used to cancel any tones currently being sent.

ParameterTypeNullableOptionalDescription
tonesDOMString
durationlong
interToneGaplong
Return type: void

6.3 RTCDTMFToneChangeEvent

The tonechange event uses the RTCDTMFToneChangeEvent interface.

Firing a tonechange event named e with a DOMString tone means that an event with the name e, which does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated), and which uses the RTCDTMFToneChangeEvent interface with the tone attribute set to tone, must be created and dispatched at the given target.



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

6.3.1 Attributes

tone of type DOMString, readonly

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

7. 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 RTCStatsElement id attribute. 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:

  1. If the RTCPeerConnection object's RTCPeerConnection signalingState is closed, throw an INVALID_STATE exception.

  2. Let selectorArg be the methods first argument.

  3. Return, but continue the following steps in the background.

  4. If selectorArg is an invalid selector, the user agent must queue a task to invoke the failure callback (the method's third argument).

  5. Start gathering the stats indicated by selectorArg. In case selectorArg is null, stats must be gathered for the whole RTCPeerConnection object.

  6. 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 as its argument.

ParameterTypeNullableOptionalDescription
selectorMediaStreamTrack
successCallbackRTCStatsCallback
failureCallbackRTCPeerConnectionErrorCallback
Return type: void

7.3 RTCStatsCallback

callback RTCStatsCallback = void (RTCStatsReport report);

7.3.1 Callback RTCStatsCallback Parameters

report of type RTCStatsReport

A RTCStatsReport object representing the gathered stats.

7.4 RTCStatsReport Object

The getStats() method delivers a successful result in the form of a RTCStatsReport object. A RTCStatsReport is composed of a set of RTCStatsElement objects, each reporting stats for one object that the implementation thinks is relevant for the selector. One achieves the total for the selector by summing over all the elements of a certain type; for instance, if a MediaStreamTrack is carried by multiple SSRCs over the network, the RTCStatsReport may contain one RTCStatsElement per SSRC (which can be distinguished by the value of the “ssrc” stats attribute).

interface RTCStatsReport {
    sequence<RTCStatsElement> filterElements (optional DOMString type);
    RTCStatsElement?          getElement (DOMString id);
};

7.4.1 Methods

filterElements

Returns the contents of the report as a sequence of RTCStatsElement objects.

If the argument is present, filterElements() must only return the elements whose type attribute is equal to the type specified in the argument. If the argument is omitted, the method must return all RTCStatsElement objects in the report.

ParameterTypeNullableOptionalDescription
typeDOMString
Return type: sequence<RTCStatsElement>
getElement

The getElement() method must return the first RTCStatsElement object in this report whose id is equal to id. The method must return null if no element matches the id argument.

ParameterTypeNullableOptionalDescription
idDOMString
Return type: RTCStatsElement, nullable

7.5 RTCStatsElement Object

An RTCStatsElement represents the stats gathered by inspecting a specific object relevant to a selector. Each RTCStatsElement has a set of default attributes such as timestamp and type. Individual statistics are accessed by passing string names to the getValue() method. 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 RTCStatsElement.

interface RTCStatsElement {
    readonly attribute DOMTimeStamp timestamp;
    readonly attribute DOMString    type;
    readonly attribute DOMString    id;
    sequence<DOMString> getNames ();
    any                 getValue (DOMString statName);
};

7.5.1 Attributes

id of type DOMString, readonly

Returns a unique id that is associated with the object that was inspected to produce this RTCStatsElement object. Two RTCStatsElement 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.

The id attribute must return the value it was set to when the object was created.

timestamp of type DOMTimeStamp, readonly

Returns the timestamp associated with this RTCStatsElement. The time is relative to the UNIX epoch (Jan 1, 1970, UTC) to make it easy to construct a Date object if needed.

The timestamp attribute must return the value it was set to when the object was created.

type of type DOMString, readonly

Returns the type of the object that was inspected to produce this RTCStatsElement object.

The type attribute must return the value it was set to when the object was created.

7.5.2 Methods

getNames

The getNames() method must return a sequence of strings representing the names of all stats in this RTCStatsElement that can be looked up with the getValue() method.

No parameters.
Return type: sequence<DOMString>
getValue

The getValue() method returns the value for the statistic that corresponds to statName. If there is no statistics value associated with statName (i.e. the name is not a member of the sequence returned by the getNames() method), then this method must return null.

ParameterTypeNullableOptionalDescription
statNameDOMString
Return type: any

7.6 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 sound track is audio track 0 of remote stream 0 of pc1. The following example code might be used:

Example 1
var baselineReport, nowReport;
var selector = pc.getRemoteStreams()[0].getAudioTracks()[0];

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

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

function processStats() {
    // grab the relevant elements
    var nowElements = nowReport.filterElements("rtp-stream");

    // compare the elements from the current report with the baseline
    for (i = 0; i < nowElements.length; i++) {
        now = nowElements[i];
        // get the corresponding stats element from the baseline report
        prev = baselineReport.getElement(now.id);

        if (prev) {
            remoteNow = now.getValue("remoteElement");
            remotePrev = prev.getValue("remoteElement");

            var packetsSent = now.getValue("packetsSent") -
                    prev.getValue("packetsSsent");
            var packetsReceived = remoteNow.getValue("packetsReceived") -
                    remotePrev.getValue("packetsReceived");

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

8. Identity

8.1 Identity Provider Interaction

WebRTC offers and answers (and hence the channels established by RTCPeerConnection objects) can be authenticated by using web-based Identity Providers. 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 Peer-Connection/IdP Communications

In order to communicate with the IdP, the browser must instantiate an isolated interpreted context [TODO: What's the technical term?], such as an invisible IFRAME. The initial contents of the context are loaded from a URI derived from the IdP's domain name. [RTCWEB-SECURITY-ARCH; Section XXX].

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

  1. If the setIdentityProvider() method has been called, the IdP provided shall be used.
  2. If the setIdentityProvider() method has not been called, then the browser shall use an IdP configured into the browser. If more than one such IdP is configured, the browser should provide the user with a chooser interface.

In order to verify assertions, the IdP domain name and protocol shall be equal to the "domain" and "protocol" fields of the identity assertion.

The context must have a MessageChannel named window.TBD which is "entangled" to the RTCPeerConnection and is unique to that subcontext. This channel is used for messaging between the RTCPeerConnection and the IdP. All messages sent via this channel are strings, specifically the JSONified versions of JavaScript structs.

All messages sent from the RTCPeerConnection to the IdP context must have an origin of rtcweb://peerconnection/. The fact that ordinary Web pages cannot set their origin values arbitrarily is an essential security feature, as it stops attackers from requesting WebRTC-compatible identity assertions from IdPs. For this reason, the origin must be included in the identity assertion and verified by the consuming RTCPeerConnection.

8.1.2 Requesting Assertions

The identity assertion request process involves the following steps.

  1. The RTCPeerConnection instantiates an IdP context as described in the previous section.
  2. The IdP serves up the IdP JavaScript code to the IdP context.
  3. Once the IdP is loaded and ready to receive messages it sends a "READY" message [RTCWEB-SECURITY-ARCH; Section 5.6.5.2]. Note that this does not imply that the user is logged in, merely that enough IdP state is booted up to be ready to handle PostMessage calls.
  4. The IdP sends a "SIGN" message (Section 5.6.5.2.2) to the IdP proxy context. This message includes the material the RTCPeerConnection desires to be bound to the user's identity.
  5. If the user is not logged in, at this point the IdP will initiate the login process. For instance, it might pop up a dialog box inviting the user to enter their (IdP) username and password.
  6. Once the user is logged in (potentially after the previous step), the IdP proxy generates an identity assertion (depending on the authentication protocol this may involve interacting with the IDP server).
  7. Once the assertion is generated, the IdP proxy sends a response (Section 5.6.5.2.2) containing the assertion to the RTCPeerConnection over the message channel.
  8. The RTCPeerConnection stores the 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.

8.1.3 Verifying Assertions

The identity assertion request process involves the following steps.

  1. The RTCPeerConnection instantiates an IdP context as described in the previous section.
  2. The IdP serves up the IdP JavaScript code to the IdP context.
  3. Once the IdP is loaded and ready to receive messages it sends a "READY" message [RTCWEB-SECURITY-ARCH; Section 5.6.5.2]. Note that this does not imply that the user is logged in, merely that enough IdP state is booted up to be ready to handle PostMessage calls.
  4. The IdP sends a "VERIFY" message (Section 5.6.5.2.2) to the IdP proxy context. This message includes assertion from the offer/answer which is to be verified.
  5. The IdP proxy verifies the identity assertion (depending on the authentication protocol this may involve interacting with the IDP server).
  6. Once the assertion is verified the IdP proxy sends a response containing the verified assertion results (Section 5.6.5.2.3) to the RTCPeerConnection over the message channel.
  7. The RTCPeerConnection displays the assertion information in the browser UI and stores the assertion in the peerIdentity attribute for availability to the JavaScript application. The assertion information to be displayed shall contain the domain name of the IdP and the identity returned by the IdP and must be displayed via some mechanism which cannot be spoofed by content. [[OPEN ISSUE: The identity information should also be available in the inspector interface defined in [RTCWEB-SECURITY-ARCH; Section 5.5].

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

8.2.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. It is called any time an identity verification succeeds or fails.
peerIdentity of type RTCIdentityAssertion, readonly, nullable

Contains the peer identity assertion information if an identity assertion was provided and verified.

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

Queue a task to run the following substeps.

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

  2. Instantiate a new IdP proxy and request an identity assertion.

No parameters.
Return type: void
setIdentityProvider

Sets the identity provider to be used for a given PeerConnection 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:

  1. Set the current identity values to the triplet (provider, protocol, username).

  2. If the RTCPeerConnection object's RTCPeerConnection signalingState is stable, and any of the identity settings have changed, queue a task to run the following substeps:

    1. If the connection's RTCPeerConnection signalingState is closed, abort these steps, and throw an exception with an RTCError object of type INVALID_STATE.

    2. Instantiate a new IdP proxy and request an identity assertion.

    3. If/when the assertion is obtained, fire a negotiationneeded event.

ParameterTypeNullableOptionalDescription
providerDOMString
protocolDOMString
usernameDOMString
Return type: void

8.3 RTCIdentityAssertion Type

dictionary RTCIdentityAssertion {
    DOMString idp;
    DOMString name;
};

8.3.1 Dictionary RTCIdentityAssertion Members

idp of type DOMString

A domain name representing the identity provider.

name of type DOMString

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

8.4 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.onidentityresult = function(result) {
  console.log("IdP= " + pc.peerIdentity.idp +
              " identity=" + pc.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 document.

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:

  1. Let stream be the target MediaStream object.

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

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

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

  1. Let stream be the target MediaStream object.

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

  3. Remove track from stream’s track set.

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

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

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 6

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 7

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 Attributes

stream of type MediaStream, readonly, nullable

The stream attribute represents the MediaStream object associated with the event.

9.4.2 Dictionary MediaStreamEventInit Members

stream of type MediaStream

10. Examples and Call Flows

This section is non-normative.

10.1 Simple Peer-to-peer Example

This section is non-normative.

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

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

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

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

    // let the "negotiationneeded" event trigger offer generation
    pc.onnegotiationneeded = function () {
        pc.createOffer(localDescCreated, logError);
    }

    // once remote stream arrives, show it in the remote video element
    pc.onaddstream = function (evt) {
        remoteView.src = URL.createObjectURL(evt.stream);
    };

    // get a local stream, show it in a self-view and add it to be sent
    navigator.getUserMedia({ "audio": true, "video": true }, function (stream) {
        selfView.src = URL.createObjectURL(stream);
        pc.addStream(stream);
    });
}

function localDescCreated(desc) {
    pc.setLocalDescription(desc, function () {
        signalingChannel.send(JSON.stringify({ "sdp": pc.localDescription }));
    }, logError);
}

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

    var message = JSON.parse(evt.data);
    if (message.sdp)
        pc.setRemoteDescription(new RTCSessionDescription(message.sdp), function () {
            // if we received an offer, we need to answer
            if (pc.remoteDescription.type == "offer")
                pc.createAnswer(localDescCreated, logError);
        }, logError);
    else
        pc.addIceCandidate(new RTCIceCandidate(message.candidate));
};

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

10.2 Advanced Peer-to-peer Example

This example shows the more complete functionality.

Example 5
TODO

10.3 Peer-to-peer Data Example

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

Note

This example uses the negotiationneeded event to initiate the offer/answer dialog. The exact behavior surrounding the negotiationneeded event is not specified in detail at the moment. This example can hopefully help to drive that discussion. An assumption made in this example is that the event only triggeres when a new negotiation should be started. This means that an action (such as addStream()) that normally would have fired the negotiationneeded event will not do so during an ongoing offer/answer dialog.

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

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

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

    // let the "negotiationneeded" event trigger offer generation
    pc.onnegotiationneeded = function () {
        pc.createOffer(localDescCreated, logError);
    }

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

function localDescCreated(desc) {
    pc.setLocalDescription(desc, function () {
        signalingChannel.send(JSON.stringify({ "sdp": pc.localDescription }));
    }, logError);
}

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

    var message = JSON.parse(evt.data);
    if (message.sdp)
        pc.setRemoteDescription(new RTCSessionDescription(message.sdp), function () {
            // if we received an offer, we need to answer
            if (pc.remoteDescription.type == "offer")
                pc.createAnswer(localDescCreated, logError);
        }, logError);
    else
        pc.addIceCandidate(new RTCIceCandidate(message.candidate));
};

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

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

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

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

10.4 Call Flow Browser to Browser

Note

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

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

A message sequence chart detailing a call flow between two browsers

10.5 DTMF Example

Examples assume that “pc” is a connected RTCPeerConnection, and “track” is an audio track on that connection.

Sending the DTMF signal “1234” with 500 ms per tone:

Example 7
sender = pc.createDTMFSender(track);
if (sender.canSendDTMF) {
  sender.insertDTMF(“1234”, 500);
} else {
  alert(‘DTMF function not available’);
}

Sending the DTMF signal “1234”, and lighting up a key using “lightKey(x)” while the tone is playing (assuming that lightKey(‘’) will darken all the keys):

Example 8
sender = pc.createDTMFSender(track);
sender.ontonechange = function(e) {
  lightKey(e.tone);
}
sender.insertDTMF(‘1234’);

Sending a 1-second “1” tone followed by a 2-second “2” tone:

Example 9
sender = pc.createDTMFSender(track);
sender.ontonechange = function(e) {
  if (e.tone == ‘’) {
    sender.insertDTMF(‘2’, 2000);
  }
}
sender.insertDTMF(‘1’, 1000);

Sending the tone string ‘12345’, and appending the tone string ‘6789’ before the tone finishes playing:

Example 10
sender = pc.createDTMFSender(track);
sender.insertDTMF(‘12345’);
// Other things happen.....
sender.insertDTMF(sender.toneBuffer + 6789’);

This is safe due to the Javascript threading model.

11. Event summary

This section is non-normative.

The following events fire on RTCDataChannel objects:

Event name Interface Fired when...
open Event The RTCDataChannel object's underlying data transport has been established (or re-established).
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.

The following events fire on RTCPeerConnection objects:

Event name Interface Fired when...
connecting Event TODO
open 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.
statechange Event TODO
icechange Event TODO
icecandidate RTCPeerConnectionIceEvent TODO
identityresult RTCIdentityEvent TODO

The following events fire on RTCDTMFSender objects:

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

12. Security Considerations

TBD.

13. IANA Registrations

IANA is requested to register the constraints defined in Constraints Section as specified in [RTCWEB-CONSTRAINTS].

13.1 Constraints

TOOD: Need to change the naming and declaration of these constraints to match the constraints draft once that is a bit further along. The names here now are likely not quite right but they serve as a place holder.

Issue 8

ISSUE: there are multiple ways to add constraints. How are multiple values reconciled?

The following new constraints are defined that can be used with an RTCPeerConnection object:

OfferToReceiveVideo

This is an enum type constraint that can take the values "true" and "false". The default is a non mandatory "true" for an RTCPeerConnection object that has a video stream at the point in time when the constraints are being evaluated and is non mandatory "false" otherwise.

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 constraint allows an application to indicate its preferences for receiving video when creating an offer.

OfferToReceiveAudio

This is an enum type constraint that can take the values "true" and "false". The default is a non mandatory "true".

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 constraints allows an application to indicate its preferences for receiving audio when creating an offer.

VoiceActivityDetection

This is an enum type constraint that can take the values "true" and "false". The default is a non mandatory "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 sounds other than spoken voice or emergency calling, it is desirable to be able to turn off this behavior. This constraint allows the application to provide information about whether it wishes this type of processing enabled or disabled.

IceTransports

This is an enum type constraint that can take the values "none", "relay", and "all". The default is a non mandatory "all".

This constraint indicates which candidates the ICE engine is allowed to use. The value "none" means the ICE engine must not send or receive any packets at this point. The value "relay" indicates 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. The value of "all" indicates all values can be used.

RequestIdentity

This is an enum type constraint that can take the values "yes", "no", and "ifconfigured". The default is a non mandatory "ifconfigured".

This constraint indicates whether an identity should be requested. The constraint may be used with either of the createOffer() or createAnswer() calls or with the constructor. The value "yes" means that an identity must be requested. The value "no" means that no identity is to be requested. 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. Note that as long as DTLS-SRTP is in used, fingerprints will be sent regardless of the value of this constraint.

TODO items - need to register with IANA.

14. Change Log

This section will be removed before publication.

Changes since Jan 16, 2013

  1. Initial import of Statistics API to version 2.
  2. Extracted API extensions introduced by features, such as the P2P Data API, from the PeerConnection API.

Changes since Dec 12, 2012

  1. Changed AudioMediaStreamTrack to RTCDTMFSender and gave it its own section. Updated text to reflect most recent agreements. Also added examples section.
  2. Replaced the localStreams and remoteStreams attributes with functions returning sequences of MediaStream objects.
  3. Added spec text for attributes and methods adopted from the WebSocket interface.
  4. Changed the state ENUMs and transition diagrams.
  5. Aligned the data channel processing model a bit more with WebSockets (mainly closing the underlying transport).

Changes since Nov 13, 2012

  1. Made some clarifications as to how operation queuing works, and fixed a few errors with the error handling description.
  2. Introduced new representation of tracks in a stream (removed MediaStreamTrackList). Added algorithm for creating a track to represent an incoming network media component.
  3. Renamed MediaStream.label to MediaStream.id (the definition needs some more work).

Changes since Nov 03, 2012

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

Changes since Oct 19, 2012

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

Changes since Sept 23, 2012

  1. Restructured the document layout and created separate sections for features like Peer-to-peer Data API, Statistics and Identity.

Changes since Aug 16, 2012

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

Changes since Aug 13, 2012

  1. Made the RTCSessionDescription and RTCIceCandidate constructors take dictionaries instead of a strings. Also added detailed stringifier algorithm.
  2. Went through the list of issues (issue numbers are only valid with HEAD at fcda53c460). Closed (fixed/wontfix): 1, 8, 10, 13, 14, 16, 18, 19, 22, 23, 24. Converted to notes: 4, 12. Updated: 9.
  3. Incorporate changes proposed by Li Li.
  4. Use an enum for DataChannelState and fix IDLs where using an optional argument also requires all previous optional arguments to have a default value.

Changes since Jul 20, 2012

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

Changes since Jul 13, 2012

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

Changes since May 28, 2012

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

Changes since April 27, 2012

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

Changes since 21 April 2012

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

Changes since 12 January 2012

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

Changes since 17 October 2011

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

Changes since 23 August 2011

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

A. Acknowledgements

The editors wish to thank the Working Group chairs and Team Contact, Harald Alvestrand, Stefan Håkansson and Dominique Hazaël-Massieux, for their support. Substantial text in this specification was provided by many people including Harald Alvestrand, Justin Uberti, and Eric Rescorla.

B. References

B.1 Normative references

[GETUSERMEDIA]
D. Burnett; A. Narayanan. Media Capture and Streams. 28 June 2012. W3C Working Draft. URL: http://www.w3.org/TR/2012/WD-mediacapture-streams-20120628/
[HTML5]
Robin Berjon et al. HTML5. 17 December 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/html5/
[ICE]
J. Rosenberg. Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT) Traversal for Offer/Answer Protocols. April 2010. RFC 5245. URL: http://tools.ietf.org/html/rfc5245
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[RTCWEB-CONSTRAINTS]
D. Burnett. IANA Registry for RTCWeb Media Constraints. URL: http://datatracker.ietf.org/doc/draft-burnett-rtcweb-constraints-registry/
[SDP]
J. Rosenberg; H. Schulzrinne. An Offer/Answer Model with the Session Description Protocol (SDP). June 2002. RFC 3264. URL: http://tools.ietf.org/html/rfc3264
[STUN]
J. Rosenberg; R. Mahy; P. Matthews; D. Wing. Session Traversal Utilities for NAT (STUN). October 2008. RFC 5389. URL: http://tools.ietf.org/html/rfc5389
[STUN-URI]
S. Nandakumar; G. Salgueiro; P. Jones; and M. Petit-Huguenin. URI Scheme for Session Traversal Utilities for NAT (STUN) Protocol. 12 March 2012. Internet Draft (work in progress). URL: http://tools.ietf.org/html/draft-nandakumar-rtcweb-stun-uri
[TURN]
P. Mahy; P. Matthews; J. Rosenberg. Traversal Using Relays around NAT (TURN): Relay Extensions to Session Traversal Utilities for NAT (STUN). April 2010. RFC 5766. URL: http://tools.ietf.org/html/rfc5766
[TURN-URI]
M. Petit-Huguenin; S. Nandakumar; G. Salgueiro; and P. Jones. Traversal Using Relays around NAT (TURN) Uniform Resource Identifiers. 12 March 2012. Internet Draft (work in progress). URL: http://tools.ietf.org/html/draft-petithuguenin-behave-turn-uris
[WEBIDL]
Cameron McCormack. Web IDL. 27 September 2011. W3C Working Draft. URL: http://www.w3.org/TR/2011/WD-WebIDL-20110927/
[WEBSOCKETS-API]
I. Hickson. The WebSocket API. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/websockets/

B.2 Informative references

[RTCWEB-JSEP]
J. Uberti, C. Jennings. Javascript Session Establishment Protocol. URL: http://datatracker.ietf.org/doc/draft-ietf-rtcweb-jsep/