W3C

WebRTC 1.0: Real-time Communication Between Browsers

W3C Editor's Draft 20 July 2012

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 version:
http://dev.w3.org/2011/webrtc/editor/webrtc-20120530.html
Editors:
Adam Bergkvist, Ericsson
Daniel C. Burnett, Voxeo
Cullen Jennings, Cisco
Anant Narayanan, Mozilla

Initial Author of this Specification was Ian Hickson, Google Inc., with the following copyright statement:
© Copyright 2004-2011 Apple Computer, Inc., Mozilla Foundation, and Opera Software ASA. You are granted a license to use, reproduce and create derivative works of this document.

All subsequent changes since 26 July 2011 done by the W3C WebRTC Working Group are under the following Copyright:
© 2011-2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. Document use rules apply.

For the entire publication on the W3C site the liability and trademark rules apply.

Abstract

This document defines a set of APIs to represent streaming media, including audio and video, in JavaScript, to allow media to be sent over the network to another browser or device implementing the appropriate set of real-time protocols, and media received from another browser or device to be processed and displayed locally. 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 not complete. It is subject to major changes and, while early experimentation is encouraged, it is therefore not intended for implementation. 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 feedback is 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. Network Stream API

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

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 a RTCPeerConnection object (later described 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 a 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 cases.

4.2 Interface definitions

Note

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

4.2.1 MediaStream

4.2.1.1 label

The label attribute specified in MediaStream returns a label 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 label attribute is initialized from information provided by the remote source.

Note

The label 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 to a remote peer using RTCPeerConnection , and then sent back to the original user in the same manner, in which case the original user will have multiple streams with the same label (the locally-generated one and the one received from the remote peer).

4.2.1.2 Events on MediaStream

A new media component may be associated with an existing MediaStream . This happens, e.g., on the A-side when the B-side adds a new MediaStreamTrack object to one of the track lists of a MediaStream that is being sent over a RTCPeerConnection . If this happens for the reason exemplified, or for any other reason than the add() [GETUSERMEDIA] method being invoked locally on a MediaStreamTrackList or tracks are being added as the stream is created (i.e. the stream is initialized with tracks), the user agent must run the following steps:

  1. Create a MediaStreamTrack object track to represent the new media component.

  2. If track’s kind attribute equals "audio", add it to the MediaStream object’s audioTracks MediaStreamTrackList object.

    Issue 1

    ISSUE: Is there a way to generalize this so that if we add a "smell" track this continues to work.

  3. If track’s kind attribute equals "video", add it to the MediaStream object’s videoTracks MediaStreamTrackList object.

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

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

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

  2. Remove track from the MediaStreamTrackList object.

  3. Fire a track event named removetrack with track at the MediaStreamTrackList object.

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

4.2.2 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 a 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 2

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

A track in a MediaStream , received with a RTCPeerConnection , must have its readyState attribute [GETUSERMEDIA] set to MUTED (1) until media data arrives.

In addition, a MediaStreamTrack has its readyState set to MUTED on the B-side if the A-side disables the corresponding MediaStreamTrack in the MediaStream that is being sent. When the addstream event triggers on a RTCPeerConnection , all MediaStreamTrack objects in the resulting MediaStream are muted until media data can be read from the RTP source.

Issue 3

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

4.3 AudioMediaStreamTrack

The AudioMediaStreamTrack is a specialization of of a normal MediaStreamTrack that only carries audio and is extended to have the capability to send and/or receive DTMF codes.

interface AudioMediaStreamTrack : MediaStreamTrack {
    readonly attribute boolean canInsertDTMF;
    void insertDTMF (DOMString tones, optional long duration);
};

4.3.1 Attributes

canInsertDTMF of type boolean, readonly

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

4.3.2 Methods

insertDTMF

When a AudioMediaStreamTrack object’s insertDTMF() method is invoked, the user agent must queue a task that that sends the DTMF tones.

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

The duration parameters indicates the duration in ms to play the each DTMF passed in the tones parameters. The duration can not be more than 6000 or less than 70. The default duration is 100 ms for each tone. The gap between tones must be at least 50 ms but should be as short as possible.

Issue 4

ISSUE: How are invalid values handled?

If insertDTMF is called on the same object while an existing task for this object is 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 send.

Note

Editor Note: We need to add a callback that is set on the object that is called after the tones are sent. This is needed to allow the application to know when it can send new tones without canceling the tones that are currently being sent.

Note

Editor Note: It seems we would want a callback or event for incoming tones. The proposal sent to the list had them played as audio to the speaker but I don’t see how that is useful.

ParameterTypeNullableOptionalDescription
tonesDOMString✘✘
durationlong✘✔
Return type: void

5. Peer-to-peer connections

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

Calling new RTCPeerConnection(configuration ) creates a 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.

A RTCPeerConnection object has an associated ICE Agent, RTCPeerConnection state, and ICE State. These are initialized when the 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 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] 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 and as the RTCPeerConnection object gets more information, it can adjust the number of components.

  2. Set connection’s RTCPeerConnection readiness state to "new" .

  3. Set connection’s RTCPeerConnection ice state to "new" .

  4. Let connection’s localStreams attribute be an empty read-only MediaStream array.

  5. Let connection’s remoteStreams attribute be an empty read-only MediaStream array.

  6. Return connection, but continue these steps asynchronously.

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

During the lifetime of the RTCPeerConnection object, the following procedures are followed:

  1. If the ice state is "new" and the IceTransports constraint is not set to "none", it must queue a task to start gathering ICE address and set the ice state to "gathering".

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

  3. When the ICE Agent finishes checking all candidate pairs, if at least one connection has been found for some MediaTrack, the iceState is changed to "completed" and if no connection has been found for any MediaTrack, the iceState is changed to "failed".

    Issue 5

    ISSUE: Note that this means that if I was able to negotiate audio but not video via ICE, then iceState == "completed". Is this really what is desired?

  4. If the iceState is "connected" or "completed" and both the local and remote session descriptions are set, the peerState is set to "active".

  5. If the iceState is "failed", a task is queued to calls the close method.

    Issue 6

    ISSUE:: CJ - this seems wrong to me.

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

Note

Starting with the native resolution means that if the Web application notifies its peer of the native resolution as it starts sending data, and the peer prepares its video element accordingly, there will be no need for a renegotiation once the stream is flowing.

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 to represent the media stream.

    Issue 7

    ISSUE: What if one already exists?

  3. Run the following steps for each component in the media stream.

    1. Create a MediaStreamTrack object track to represent the component. [[EDITORIAL: Can we just reference 3.2.1.2 here?]]

    2. If track's kind attribute equals "audio", add it to the MediaStream object's audioTracks MediaStreamTrackList object.

    3. If track's kind attribute equals "video", add it to the MediaStream object's videoTracks MediaStreamTrackList object.

    Note

    The creation of new incoming MediaStreams may be triggered either by SDP negotiation or by the receipt of media on a given flow.

    Note

    The internal order in the MediaStreamTrackList objects on the receiving side should reflect the order on the sending side. One way to enforce this is to specify the order in the SDP.

  4. Queue a task to run the following substeps:

    1. If the connection’s RTCPeerConnection readiness state is CLOSED (3), abort these steps.

    2. Add the newly created MediaStream object to the end of connection’s remoteStreams array.

    3. Fire a stream event named addstream with the newly created MediaStream object 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 a 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 readiness state is CLOSED (3), abort these steps.

    2. Remove stream from connection’s remoteStreams array.

    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 descipriton negotiation, an renegotiationneeded event is fired at the RTCPeerConnection object.

In particular, if a RTCPeerConnection object is consuming a MediaStream and a track is added to one of the stream's MediaStreamTrackList objects, by, e.g., the add() method being invoked, the RTCPeerConnection object must fire the "renegotiationneeded" event. Removal of media components must also trigger "renegotianneeded".

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.

5.1 RTCPeerConnection

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

5.1.1 RTCSdpType

The RTCSdpType enum describes the type of a 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 a 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 a SDP answer may be applied as a response to a SDP offer, or an update to a previously send SDP "pranswer".

5.1.2 RTCSessionDescription Class

The RTCSessionDescription() constructor takes one argument, description, whose content is used to construct the new RTCSessionDescription object. This class is a future extensible carrier for for the data contained in it and does not perform any substantive processing.

[Constructor (DOMString description)]
interface RTCSessionDescription {
             attribute RTCSdpType type;
             attribute DOMString  sdp;
    stringifier DOMString ();
};
5.1.2.1 Attributes
sdp of type DOMString
The string representation of the SDP [SDP]
type of type RTCSdpType
What type of SDP this RTCSessionDescription represents.
5.1.2.2 Methods
DOMString

Objects that implement the RTCSessionDescription interface must stringify as [SDP].

No parameters.
Return type: stringifier

5.1.3 RTCSessionDescriptionCallback

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

5.1.4 RTCVoidCallback

callback RTCVoidCallback = void ();

5.1.5 RTCPeerConnectionErrorCallback

callback RTCPeerConnectionErrorCallback = void (DOMString errorInformation);
5.1.5.1 Callback RTCPeerConnectionErrorCallback Parameters
errorInformation of type DOMString
Information about what went wrong.
Issue 8

ISSUE: How does this work? Is it human readable? I18N? ENUM?

Issue 9

ISSUE: should this be defined as event like NavigatorUserMediaErrorCallback in getusermedia

5.1.6 RTCPeerState Enum

enum RTCPeerState {
    "new",
    "opening",
    "active",
    "closing",
    "closed"
};
Enumeration description
newThe object was just created, and no networking has yet occurred.
opening The user agent is attempting to establish an connection with the ICE Agent and waiting for local and remote SDP to be set.
Issue 10

ISSUE: do we need more states between "opening" and "active"?

activeThe ICE Agent has found a connection both the local and remote SDP have been set. It is possible for media to flow.
closingThe RTCPeerConnection object is terminating all media and is in the process of closing the connection.
closedThe connection is closed.

5.1.7 RTCIceState Enum

Issue 11

ISSUE: There is active discussion around changing these states.

enum RTCIceState {
    "new",
    "gathering",
    "waiting",
    "checking",
    "connected",
    "completed",
    "failed",
    "closed"
};
Enumeration description
newThe RTCPeerConnection object was just created, and no networking has yet occurred.
gatheringThe ICE Agent is attempting to gather addresses.
waitingThe ICE Agent is not gathering any addresses and is waiting for candidates from the other side before it can start checking.
checkingThe ICE Agent 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 connection 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.
failedThe ICE Agent is finished checking all candidate pairs and failed to find a connection.
closedThe ICE Agent has shut down and is no longer responding to STUN requests.

5.1.8 RTCIceCandidate Type

The RTCIceCandidate() constructor takes one argument, candidate, whose content is used to construct the new RTCIceCandidate object. This class is a future extensible carrier for for the data contained in it and does not perform any substantive processing.

Note: TODO - the constructor needs some work here

[Constructor (DOMString candidate)]
interface RTCIceCandidate {
             attribute DOMString      candidate;
             attribute DOMString?     sdpMid;;
             attribute unsigned short sdpMLineIndex;;
    stringifier DOMString ();
};
5.1.8.1 Attributes
candidate of type DOMString
This carries the candidate-attribute as defined in section 15.1 of [ICE].
sdpMLineIndex; of type unsigned short
This indeicates the index (starting at zero) of m-line in the SDP this candidate is assocated with.
sdpMid; of type DOMString, nullable
If present, this contains the identierfier of the "media stream identification" as defined in [RFC 3388] for m-line this candidate is assocated with.
5.1.8.2 Methods
DOMString
Objects that implement the RTCIceCandidate interface must stringify as the candidate-attribute as defined in section 15.1 of [ICE].
No parameters.
Return type: stringifier

5.1.9 RTCIceServer Type

dictionary RTCIceServer {
    DOMString          url;
    nullable DOMString credential;
};
5.1.9.1 Dictionary RTCIceServer Members
credential of type nullable DOMString

If the url element of the internal array is 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 servers between every layer of NATs in addition to the TURN servers to minimize the number 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"} ]

5.1.10 RTCConfiguration Type

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

An array of containing the STUN and TURN servers provided by the JS that can be used by ICE.

5.1.11 RTCPeerConnection Interface

[Constructor (RTCConfiguration configuration, optional MediaConstraints constraints)]
interface RTCPeerConnection {
    void        createOffer (RTCSessionDescriptionCallback successCallback, optional RTCPeerConnectionErrorCallback failureCallback, optional optional MediaConstraints constraints);
    void        createAnswer (RTCSessionDescription offer, RTCSessionDescriptionCallback successCallback, optional RTCPeerConnectionErrorCallback failureCallback, optional optional MediaConstraints constraints, optional optional boolean createProvisionalAnswer = false);
    void        setLocalDescription (RTCSessionDescription description, optional RTCVoidCallback successCallback, optional optional RTCPeerConnectionErrorCallback failureCallback);
    readonly attribute RTCSessionDescription localDescription;
    void        setRemoteDescription (RTCSessionDescription description, optional RTCVoidCallback successCallback, optional optional RTCPeerConnectionErrorCallback failureCallback);
    readonly attribute RTCSessionDescription remoteDescription;
    readonly attribute RTCPeerState          readyState;
    void        updateIce (optional RTCConfiguration configuration, optional optional MediaConstraints constraints, optional optional boolean restart=false);
    void        addIceCandidate (RTCIceCandidate candidate);
    readonly attribute RTCIceState           iceState;
    readonly attribute MediaStreamArray      localStreams;
    readonly attribute MediaStreamArray      remoteStreams;
    DataChannel createDataChannel ([TreatNullAs=EmptyString] DOMString? label, optional DataChannelInit? dataChannelDict);
             attribute EventHandler          ondatachannel;
    void        addStream (MediaStream stream, optional MediaConstraints constraints);
    void        removeStream (MediaStream stream);
    void        close ();
             attribute EventHandler          onrenegotationneeded;
             attribute EventHandler          onicecandidate;
             attribute EventHandler          onopen;
             attribute EventHandler          onstatechange;
             attribute EventHandler          onaddstream;
             attribute EventHandler          onremovestream;
             attribute EventHandler          onicechange;
};
5.1.11.1 Attributes
iceState of type RTCIceState, readonly

The iceState attribute must return the state of the RTCPeerConnection ICE Agent ICE 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.

localStreams of type MediaStreamArray, readonly
Issue 14

ISSUE: Specifying "readonly attribute MediaStream[]" breaks rendering of methods in this interface. Using MediaStreamArray temporarily.

Returns a live array containing the local streams (those that were added with addStream() ).

onaddstream of type EventHandler
This event handler, of event handler event type addstream , must be supported by all objects implementing the RTCPeerConnection interface.
Issue 17

ISSUE: It seems like this even handler needs to be fired when the first of two things happens - the remote side sends signaling indicating a media will be sent, or the side that sent an offer start receiving media in reply to that offer.

ondatachannel of type EventHandler
This event handler, of type datachannel , must be supported by all objects implementing the RTCPeerConnection interface.
onicecandidate of type EventHandler
This event handler, of event handler event type onicecandidate , must be supported by all objects implementing the RTCPeerConnection interface. It is called any time there is a new ICE candiate can be added to the a previos offer or answer.
onicechange of type EventHandler
This event handler, of event handler event type icechange , must be supported by all objects implementing the RTCPeerConnection interface. It is called any time the iceState changes.
onopen of type EventHandler
This event handler, of event handler event type open , must be supported by all objects implementing the RTCPeerConnection interface.
onremovestream of type EventHandler
This event handler, of event handler event type removestream , must be supported by all objects implementing the RTCPeerConnection interface.
onrenegotationneeded of type EventHandler
This event handler, of event handler event type renegotiationneeded , must be supported by all objects implementing the RTCPeerConnection interface.
Issue 16

ISSUE: Need to sort out which things should be Function and which should be a Callback.

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.
readyState of type RTCPeerState, readonly

The readyState attribute must return the RTCPeerConnection object's RTCPeerConnection readiness state.

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.

remoteStreams of type MediaStreamArray, readonly

Returns a live array containing the streams that the remote streams. (those that were added by the remote side).

This array is updated when addstream and removestream events are fired.

5.1.11.2 Methods
addIceCandidate

The addIceCandidate() method provides a remote candidate to the ICE Agent, which will be 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 state of the ICE Agent, and may result in a change to media state if it results in different connectivity being established.

A TBD exception will be 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 readiness state is CLOSED (3), throw an INVALID_STATE_ERR exception.

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

  3. Add stream to the end of the RTCPeerConnection object's localStreams object.

  4. Parse the constraints provided by the application and apply them to the MediaStream, if possible. NOTE - need to deal with throwing an exception here.

  5. Fire a renegotiationneeded event.

    Issue 15

    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 readiness state is CLOSED (3), throw an INVALID_STATE_ERR 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 readiness state to CLOSED (3).

No parameters.
Return type: void
createAnswer

The createAnswer method generates a [SDP] answer with the supported configuration for the session that is compatible with the parameters supplied in offer. 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 offer, specifies how the media plane should be established. The generation of the SDP must follow the appropriate process for generating an answer or provisional 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 is needed to get the ICE user name fragment and password. Provisional offers, as described in [RTCWEB-JSEP], are created if and only if the createProvisionalOffer flag is true.

The failureCallback will be called if the system can not generate an appropriate answer given the offer.

A TBD exception is thrown if the constraints parameter is malformed.

ParameterTypeNullableOptionalDescription
offerRTCSessionDescription✘✘
successCallbackRTCSessionDescriptionCallback✘✘
failureCallbackRTCPeerConnectionErrorCallback✘✔
constraintsoptional MediaConstraints✘✔
falseoptional boolean createProvisionalAnswer =✘✔
Return type: void
createDataChannel

Creates a new DataChannel object with the given label. The DataChannelInit dictionary can be used to configure properties of underlying channel such as data reliability. A corresponding DataChannel 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 readiness state is CLOSED (3), throw an INVALID_STATE_ERR exception.

  2. Let channel be a newly created DataChannel 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✔✘
dataChannelDictDataChannelInit✔✔
Return type: DataChannel
createOffer

The createOffer method generates a blob of SDP that contains a RFC 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.

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

The failureCallback will be called if the system can not generate an appropriate offer given the state of the RTCPeerConnection.

A TBD exception is thrown if the constraints parameter is malformed.

Issue 12

ISSUE: How are errors reported?

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

ParameterTypeNullableOptionalDescription
successCallbackRTCSessionDescriptionCallback✘✘
failureCallbackRTCPeerConnectionErrorCallback✘✔
constraintsoptional MediaConstraints✘✔
Return type: void
removeStream

Removes the given stream from the localStream array in the RTCPeerConnection and fires 'renegotiationneeded.

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 readiness state is CLOSED (3), throw an INVALID_STATE_ERR exception.

  2. If stream is not in the RTCPeerConnection object's localStreams object, then abort these steps. TODO: Do we need an exception here?

  3. Remove stream from the RTCPeerConnection object's localStreams object.

  4. Fire a renegotiationneeded 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 13

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.

A TBD exception is thrown if the SDP content is invalid.

ParameterTypeNullableOptionalDescription
descriptionRTCSessionDescription✘✘
successCallbackRTCVoidCallback✘✔
failureCallbackoptional RTCPeerConnectionErrorCallback✘✔
Return type: void
setRemoteDescription

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

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.

A TBD exception is thrown if the SDP content is invalid.

ParameterTypeNullableOptionalDescription
descriptionRTCSessionDescription✘✘
successCallbackRTCVoidCallback✘✔
failureCallbackoptional RTCPeerConnectionErrorCallback✘✔
Return type: void
updateIce

The updateIce method restarts or updates the ICE Agent process of gathering local candidates and pinging remote candidates. If there is a mandatory constraint called "IceTransports" it will control which 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.

If the restart parameter is set to true, the ICE state machine discards all candidates it has gathered, allocates new ports for the host candidates, and restarts ICE as if there had been no previos ICE session. Applications can use this to reset all ICE negotiation when something has gone terribly wrong.

A TBD exception will be thrown if constraints parameter is malformed.

ParameterTypeNullableOptionalDescription
configurationRTCConfiguration✘✔
constraintsoptional MediaConstraints✘✔
restart=falseoptional boolean✘✔
Return type: void
RTCPeerConnection implements EventTarget;

All instances of the RTCPeerConnection type are defined to also implement the EventTarget interface.

6. IANA Registrations

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

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

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

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

OfferToReceiveVideo

This is a enum type constraint that can take the values "true" and "false". The default is a non mandatory "true" for a 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, a RTCPeerConnection may wish to receive video but it is not going to send any video. The RTCPeerConnection needs to know if it should signal to the remote side if it wishes to receive video or not. This constraints allows an application to indicate its preferences for receiving video when creating an offer.

OfferToReceiveAudio

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

In some cases, a RTCPeerConnection may wish to receive audio but it is not going to send any audio. The RTCPeerConnection needs to know if it should signal to the remote side if it wishes to receive audio. This constraints allows an application to indicate its preferences for receiving audio when creating an offer.

VoiceActivityDetection

This is a 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 there 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 constraints allows the application to provide information about if it wishes this type of processing enable or disabled.

IceTransports

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

This constraints indicates which candidates the ICE engine is restricted 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 using 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.

TODO items - need to register with IANA.

7. Simple Example

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

NOTE: TODO - This code does not match the API yet and might have a few other problems.

Example 1
var signalingChannel = createSignalingChannel();
var pc;
var configuration = ...;

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

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

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

    // get the local stream, show it in the local video element and send it
    navigator.getUserMedia({ "audio": true, "video": true }, function (stream) {
        selfView.src = URL.createObjectURL(stream);
        pc.addStream(stream);

        if (isCaller)
            pc.createOffer(gotDescription);
        else
            pc.createAnswer(pc.remoteDescription, gotDescription);

        function gotDescription(desc) {
            pc.setLocalDescription(desc);
            signalingChannel.send(JSON.stringify({ "sdp": desc }));
        }
    });
}

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

    var signal = JSON.parse(evt.data);
    if (signal.sdp)
        pc.setRemoteDescription(new RTCSessionDescription(signal.sdp));
    else
        pc.addIceCandidate(new RTCIceCandidate(signal.candidate));
};

8. Advanced Example

This example shows the more comples functionality.

Example 2
TODO

9. 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 19: hello

ISSUES (this should not be considered as a complete list of open issues)

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

9.1 DataChannel

The DataChannel interface represents a bi-directional data channel between two peers. A DataChannel is created via a factory method on a RTCPeerConnection object. The corresponding DataChannel object is then dispatched at the other peer if the channel setup was successful.

Each DataChannel 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 a offered data channel. The actual wire protocol between the peers is out of the scope for this specification.

Issue 20

ISSUE: this needs to explain how the configuration state is passed between the peers.

Issue 21

ISSUE: this type of design where one side can pick anything and the other side much support everything has proven to make future upgrades very difficult.

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

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

  1. If the associated RTCPeerConnection object’s RTCPeerConnection readiness state is CLOSED (3), abort these steps.

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

  3. Set channel’s readyState attribute to OPEN (1).

  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 readiness state is CLOSED (3), 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 DataChannel 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 (1).

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

When the process of tearing down a DataChannel object’s underlying data transport is initiated, the user agent must run the following steps:

  1. If the associated RTCPeerConnection object’s RTCPeerConnection readiness state is CLOSED (3), abort these steps.

  2. Let channel be the DataChannel object which is about to be closed.

  3. If channel’s readyState is CLOSING (2) or CLOSED (3), then abort these steps.

  4. Set channel’s readyState attribute to CLOSING (2).

  5. Queue a task to run the following steps:

    1. Close channel’s underlying data transport.

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

    3. Fire a simple event named close at channel.

interface DataChannel {
    readonly attribute DOMString      label;
    readonly attribute boolean        reliable;
    const unsigned short CONNECTING = 0;
    const unsigned short OPEN = 1;
    const unsigned short CLOSING = 2;
    const unsigned short CLOSED = 3;
    readonly attribute unsigned short 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 (ArrayBuffer data);
    void send (Blob data);
};

9.1.1 Attributes

binaryType of type DOMString
Note

FIXME: align behavior with WebSocket API

bufferedAmount of type unsigned long, readonly
Note

FIXME: align behavior with WebSocket API

label of type DOMString, readonly

The DataChannel.label attribute represents a label that can be used to distinguish this DataChannel object from other DataChannel objects. The attribute must return the value to which it was set when the DataChannel object was created.

onclose of type EventHandler
This event handler, of type close , must be supported by all objects implementing the DataChannel interface.
onerror of type EventHandler
This event handler, of type error , must be supported by all objects implementing the DataChannel interface.
onmessage of type EventHandler
This event handler, of type message , must be supported by all objects implementing the DataChannel interface.
onopen of type EventHandler
This event handler, of type open , must be supported by all objects implementing the DataChannel interface.
readyState of type unsigned short, readonly

The DataChannel.readyState attribute represents the state of the DataChannel object. It must return the value to which the user agent last set it (as defined by the processing model algorithms). The attribute can have the following values: CONNECTING, OPEN, CLOSING or CLOSED.

reliable of type boolean, readonly

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

9.1.2 Methods

close

Closes the DataChannel . It may be called regardless if the DataChannel object was created by this peer or the remote peer.

When the close() method is called, the user agent must initiate the process of tearing down the DataChannel object’s underlying data transport.

No parameters.
Return type: void
send
Note

FIXME: align behavior with WebSocket API

ParameterTypeNullableOptionalDescription
dataDOMString✘✘
Return type: void
send
Note

FIXME: align behavior with WebSocket API

ParameterTypeNullableOptionalDescription
dataArrayBuffer✘✘
Return type: void
send
Note

FIXME: align behavior with WebSocket API

ParameterTypeNullableOptionalDescription
dataBlob✘✘
Return type: void

9.1.3 Constants

CLOSED of type unsigned short

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

CLOSING of type unsigned short

The process of closing down the underlying data transport has started.

CONNECTING of type unsigned short

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

OPEN of type unsigned short

TODO - theses constants need to be changed to an enum.

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

dictionary DataChannelInit {
    boolean reliable;
};

9.1.4 Dictionary DataChannelInit Members

reliable of type boolean
FIXME: write description

9.2 Examples

This simple example shows how to create a DataChannel, register an event listener to handle incoming data, and how to send a message.

Example 3
var chan = peerConn.createDataChannel("mylabel");
chan.onmessage = function (evt) {
    // use evt.data };
    chan.send("hello");

This simple example shows how to register an event listener to handle the case when a remote peer creates a new DataChannel.

Example 4
peerConn.ondatachannel = function (evt) {
   var chan = evt.channel;
   chan.onmessage = function (evt) {
       // use evt.data
   };
   chan.onclose = function () {
          // remote side closed the data channel
   };
};

10. Garbage collection

A Window object has a strong reference to any RTCPeerConnection objects created from the constructor whose global object is that Window object.

11. Event definitions

11.1 RTCPeerConnectionIceEvent

The onicecandidate event of the RTCPeerConnection uses the RTCPeerConnectionIceEvent interface.

Firing a 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 candiate must be created and dispatched at the given target.

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

11.1.1 Attributes

candidate of type RTCIceCandidate, readonly

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

11.1.2 Dictionary RTCPeerConnectionIceEventInit Members

candidate of type RTCIceCandidate

11.2 MediaStreamTrackEvent

The addtrack and removetrack events use the MediaStreamTrackEvent interface.

Firing a track event named e with a MediaStreamTrack track 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 MediaStreamTrackEvent interface with the track attribute set to track, must be created and dispatched at the given target.

[Constructor(DOMString type, MediaStreamTrackEventInit eventInitDict)]
interface MediaStreamTrackEvent : Event {
    readonly attribute MediaStreamTrack track;
};
dictionary MediaStreamTrackEventInit : EventInit {
    readonly MediaStreamTrack? track;
};

11.2.1 Attributes

track of type MediaStreamTrack, readonly

The track attribute represents the MediaStreamTrack object associated with the event.

11.2.2 Dictionary MediaStreamTrackEventInit Members

track of type readonly MediaStreamTrack, nullable

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

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

11.3.1 Attributes

stream of type MediaStream, readonly, nullable

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

11.3.2 Dictionary MediaStreamEventInit Members

stream of type MediaStream

11.4 DataChannelEvent

The datachannel event use the DataChannelEvent interface.

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

[Constructor(DOMString type, DataChannelEventInit eventInitDict)]
interface DataChannelEvent : Event {
    readonly attribute DataChannel channel;
};
dictionary DataChannelEventInit : EventInit {
    DataChannel channel;
};

11.4.1 Attributes

channel of type DataChannel, readonly

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

11.4.2 Dictionary DataChannelEventInit Members

channel of type DataChannel

12. Event summary

This section is non-normative.

The following event fires on DataChannel objects:

Event name Interface Fired when...
open Event The DataChannel 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 DataChannel object’s underlying data transport has was 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 remoteStreams array.
removestream MediaStreamEvent A stream has been removed from the remoteStreams array.
renegotiationneeded Event The browser wishes to inform the application that session negotiation needs to be redone at some point in the near future.
Issue 22

ISSUE: should this be moved to "Negotiation Needed" instead of "Re-Negotiation Needed"?
statechange Event TODO
icechange Event TODO
icecandidate RTCPeerConnectionIceEvent TODO

13. Change Log

This section will be removed before publication.

Changes since Jul 20, 2012

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

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, Harald Alvestrand and Stefan Håkansson, for their support.

B. References

B.1 Normative references

[GETUSERMEDIA]
D. Burnett, A. Narayanan. getusermedia: Getting access to local devices that can generate multimedia streams 22 December 2011. W3C Editors draft (Work in progress.) URL: http://dev.w3.org/2011/webrtc/editor/getusermedia.html
[HTML5]
Ian Hickson; David Hyatt. HTML5. 25 May 2011. W3C Working Draft. (Work in progress.) 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. Internet 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. Internet 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. Internet 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. Internet 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. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-WebIDL-20110927/

B.2 Informative references

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