4.2.1 RTCConfiguration Type

dictionary RTCConfiguration {
             sequence<RTCIceServer>   iceServers;
             RTCIceTransportPolicy    iceTransportPolicy = "all";
             RTCBundlePolicy          bundlePolicy = "balanced";
             DOMString                peerIdentity;
             sequence<RTCCertificate> certificates;
};

4.2.2 RTCIceCredentialType Enum

enum RTCIceCredentialType {
    "password",
    "token"
};

4.2.3 RTCIceServer Type

dictionary RTCIceServer {
    required (DOMString or sequence<DOMString>) urls;
             DOMString                          username;
             DOMString                          credential;
             RTCIceCredentialType               credentialType = "password";
};

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

An example array of RTCIceServer objects is:

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

4.2.4 RTCIceTransportPolicy Enum

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

4.2.5 RTCBundlePolicy Enum

enum RTCBundlePolicy {
    "balanced",
    "max-compat",
    "max-bundle"
};

4.2.6 Offer/Answer Options

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

dictionary RTCOfferAnswerOptions {
             boolean voiceActivityDetection = true;
};

dictionary RTCOfferOptions : RTCOfferAnswerOptions {
             long    offerToReceiveVideo;
             long    offerToReceiveAudio;
             boolean iceRestart = false;
};

dictionary RTCAnswerOptions : RTCOfferAnswerOptions {
};

4.3.1 Operation

Calling new RTCPeerConnection(configuration ) creates an RTCPeerConnection object.

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

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

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

1. Let connection be a newly created RTCPeerConnection object.

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

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

4. Set connection's RTCPeerConnection signalingState to stable.

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

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

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

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

9. Return connection.

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

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

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

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

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

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

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

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

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

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

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

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

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

   • A new candidate is available.

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

   • The gathering process is done.

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

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

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

4.3.2 Interface Definition

[ Constructor (optional RTCConfiguration configuration)]
interface RTCPeerConnection : EventTarget  {
    Promise<RTCSessionDescription> createOffer (optional RTCOfferOptions options);
    Promise<RTCSessionDescription> createAnswer (optional RTCAnswerOptions options);
    Promise<void>                  setLocalDescription (RTCSessionDescription description);
    readonly    attribute RTCSessionDescription? localDescription;
    Promise<void>                  setRemoteDescription (RTCSessionDescription description);
    readonly    attribute RTCSessionDescription? remoteDescription;
    Promise<void>                  addIceCandidate (RTCIceCandidate candidate);
    readonly    attribute RTCSignalingState      signalingState;
    readonly    attribute RTCIceGatheringState   iceGatheringState;
    readonly    attribute RTCIceConnectionState  iceConnectionState;
    readonly    attribute boolean?               canTrickleIceCandidates;
    RTCConfiguration               getConfiguration ();
    void                           setConfiguration (RTCConfiguration configuration);
    void                           close ();
                attribute EventHandler           onnegotiationneeded;
                attribute EventHandler           onicecandidate;
                attribute EventHandler           onsignalingstatechange;
                attribute EventHandler           oniceconnectionstatechange;
                attribute EventHandler           onicegatheringstatechange;
};

4.3.3 Legacy Interface Extensions

partial interface RTCPeerConnection {
    void createOffer (RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback, optional RTCOfferOptions options);
    void setLocalDescription (RTCSessionDescription description, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback);
    void createAnswer (RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback);
    void setRemoteDescription (RTCSessionDescription description, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback);
    void addIceCandidate (RTCIceCandidate candidate, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback);
};

4.3.4 Garbage collection

An RTCPeerConnection object MUST not be garbage collected as long as any event can cause an event handler to be triggered on the object. When the object's RTCPeerConnection signalingState is closed, no such event handler can be triggered and it is therefore safe to garbage collect the object.

All RTCDataChannel and MediaStreamTrack objects that are connected to a RTCPeerConnection are considered to have a strong reference to the RTCPeerConnection object.

4.4.1 RTCSignalingState Enum

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

The non-normative peer state transitions are:

An example set of transitions might be:

Caller transition:

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

Callee transition:

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

4.4.2 RTCIceGatheringState Enum

enum RTCIceGatheringState {
    "new",
    "gathering",
    "complete"
};

4.4.3 RTCIceConnectionState Enum

enum RTCIceConnectionState {
    "new",
    "checking",
    "connected",
    "completed",
    "failed",
    "disconnected",
    "closed"
};

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

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

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

Some example transitions might be:

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

The non-normative ICE state transitions are:

4.5.1 RTCPeerConnectionErrorCallback

callback RTCPeerConnectionErrorCallback = void (DOMError error);

4.6.1 General Principles

All methods that return promises are governed by the standard error handling rules of promises. Methods that do not return promises may throw exceptions to indicate errors.

Legacy-methods may only throw exceptions to indicate invalid state and other programming errors. For example, when a legacy-method is called when the RTCPeerConnection is in an invalid state or a state in which that particular method is not allowed to be executed, it will throw an exception. In all other cases, legacy methods MUST provide an error object to the error callback.

4.6.2 RTCSdpError

interface RTCSdpError : DOMError {
    readonly    attribute long sdpLineNumber;
};

4.7.1 RTCSdpType

The RTCSdpType enum describes the type of an RTCSessionDescription instance.

enum RTCSdpType {
    "offer",
    "pranswer",
    "answer"
};

4.7.2 RTCSessionDescription Class

dictionary RTCSessionDescriptionInit {
             RTCSdpType type;
             DOMString  sdp;
};

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

4.7.3 RTCSessionDescriptionCallback

callback RTCSessionDescriptionCallback = void (RTCSessionDescription sdp);

4.8.1 Setting Negotiation-Needed

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

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

4.8.2 Clearing Negotiation-Needed

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

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

4.8.3 Firing An Event

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

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

4.9.1 RTCIceCandidate Type

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

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

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

4.9.2 RTCPeerConnectionIceEvent

The icecandidate event of the RTCPeerConnection uses the RTCPeerConnectionIceEvent interface.

Firing an RTCPeerConnectionIceEvent event named e with an RTCIceCandidate candidate means that an event with the name e, which does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated), and which uses the RTCPeerConnectionIceEvent interface with the candidate attribute set to the new ICE candidate, MUST be created and dispatched at the given target.

When firing an RTCPeerConnectionIceEvent event that contains a RTCIceCandidate object, it MUST include values for both sdpMid and sdpMLineIndex.

dictionary RTCPeerConnectionIceEventInit : EventInit {
             RTCIceCandidate candidate;
};

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

5.1.1 Attributes

ontrack of type EventHandler,

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

5.1.2 Methods

addTrack

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

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

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

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

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

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

5. A track could have contents that are inaccessible to the application. This can be due to being marked with a peerIdentity option or anything that would make a track CORS cross-origin. These tracks can be supplied to the addTrack method, and have an RTCRtpSender created for them, but content MUST NOT be transmitted, unless they are also marked with peerIdentity and they meet the requirements for sending (see isolated streams and RTCPeerConnection).

   All other tracks that are not accessible to the application MUST NOT be sent to the peer, with silence (audio), black frames (video) or equivalently absent content being sent in place of track content.

   Note that this property can change over time.

6. Mark connection as needing negotiation.

Parameter	Type	Nullable	Optional	Description
track	MediaStreamTrack	✘	✘
streams	MediaStream	✘	✘

Return type: RTCRtpSender

getReceivers

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

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

No parameters.

Return type: sequence<RTCRtpReceiver>

getSenders

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

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

No parameters.

Return type: sequence<RTCRtpSender>

removeTrack

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

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

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

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

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

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

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

5. Mark connection as needing negotiation.

Parameter	Type	Nullable	Optional	Description
sender	RTCRtpSender	✘	✘

Return type: void

5.1.3 Processing Remote MediaStreamTracks

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

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

1. Let connection be the RTCPeerConnection expecting this media.

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

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

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

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

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

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

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

   5. Initialize track's readyState attribute to live.

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

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

6. Add track to all MediaStream objects in streams.

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

8. Fire an event named track with receiver, track, and streams at the connection object.

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

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

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

3. By definition, track is now ended.

   Note

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

4. Queue a task to run the following substeps:

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

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

5.2.1 Attributes

mid of type DOMString, readonly

The RTCRtpSender.mid attribute is the value of the a=mid SDP attribute that is immutably associated, via setLocalDescription, with this RTCRtpSender object.

track of type MediaStreamTrack, readonly

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

5.3.1 Attributes

mid of type DOMString, readonly

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

track of type MediaStreamTrack, readonly

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

5.4.1 Constructors

RTCTrackEvent

readonly attribute RTCRtpReceiver receiver

Parameter	Type	Nullable	Optional	Description
type	DOMString	✘	✘
eventInitDict	RTCTrackEventInit	✘	✘

5.4.2 Attributes

receiver of type RTCRtpReceiver, readonly

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

streams of type array of MediaStream, readonly

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

track of type MediaStreamTrack, readonly

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

5.4.3 Dictionary RTCTrackEventInit Members

receiver of type RTCRtpReceiver,

Issue

TODO

streams of type array of MediaStream,

Issue

TODO

track of type MediaStreamTrack,

Issue

TODO

5.5.1 Methods

generateCertificate, static

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

The keygenAlgorithm argument is used to control how the private key associated with the certificate is generated. The keygenAlgorithm argument uses the WebCrypto [WebCryptoAPI] AlgorithmIdentifier type. The keygenAlgorithm value MUST be a valid argument to Crypto.subtle.generateKey; that is, the value MUST produce a non-error result when normalized according to the WebCrypto algorithm normalization process [WebCryptoAPI] with an operation name of generateKey and a [[supportedAlgorithms]] value specific to production of certificates for RTCPeerConnection.

Signatures produced by the generated key are used to authenticate the DTLS connection. The identified algorithm (as identified by the name of the normalized AlgorithmIdentifier) MUST be an asymmetric algorithm that can be used to produce a signature.

The certificate produced by this process also contains a signature. The validity of this signature is only relevant for compatibility reasons. Only the public key and the resulting certificate fingerprint are used by RTCPeerConnection, but it is more likely that a certificate will be accepted if the certificate is well formed. The browser selects the algorithm used to sign the certificate; a browser SHOULD select SHA-256 [FIPS-180-3] if a hash algorithm is needed.

The resulting certificate MUST NOT include information that can be linked to a user or user agent. Randomized values for distinguished name and serial number SHOULD be used.

A user agent MUST reject a call to generateCertificate() with a DOMError of type "InvalidAccessError" if the keygenAlgorithm parameter identifies an algorithm that the user agent cannot or will not use to generate a certificate for RTCPeerConnection.

The following values MUST be supported by a user agent: { name: "RSASSA-PKCS1-v1_5", modulusLength: 2048, publicExponent: 65537 }, and { name: "ECDSA", namedCurve: "P-256" }.

Note

It is expected that a user agent will have a small or even fixed set of values that it will accept.

Parameter	Type	Nullable	Optional	Description
keygenAlgorithm	AlgorithmIdentifier	✘	✘

Return type: Promise<RTCCertificate>

5.5.2 RTCCertificate Interface

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

interface RTCCertificate {
    readonly    attribute Date expires;
};

For the purposes of this API, the [[certificate]] slot contains unstructured binary data.

Note that a RTCCertificate might not directly hold private keying material, this might be stored in a secure module.

The RTCCertificate object can be stored and retrieved from persistent storage by an application. When a user agent is required to obtain a structured clone [HTML] of a RTCCertificate object, it performs the following steps:

1. Let input and memory be the corresponding inputs defined by the internal structured cloning algorithm, where input represents a RTCCertificate object to be cloned.
2. Let output be a newly constructed RTCCertificate object.
3. Copy the value of the expires attribute from input to output.
4. Let the [[certificate]] internal slot of output be set to the result of invoking the internal structured clone algorithm recursively on the corresponding internal slots of input, with the slot contents as the new "input" argument and memory as the new "memory" argument.
5. Let the [[handle]] internal slot of output refer to the same private keying material represented by the [[handle]] internal slot of input.

6.1.1 Attributes

ondatachannel of type EventHandler,

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

6.1.2 Methods

createDataChannel

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

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

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

2. Let channel be a newly created RTCDataChannel object.

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

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

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

6. If an attribute, either maxPacketLifeTime or maxRetransmits, has been set to indicate unreliable mode, and that value exceeds the maximum value supported by the user agent, the value must be set to the user agents maximum value.

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

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

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

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

Parameter	Type	Nullable	Optional	Description
label	DOMString	✘	✘
dataChannelDict	RTCDataChannelInit	✘	✔

Return type: RTCDataChannel

6.2.1 Attributes

binaryType of type DOMString,

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

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

bufferedAmount of type unsigned long, readonly

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

bufferedAmountLowThreshold of type unsigned long,

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

id of type unsigned short, readonly

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

label of type DOMString, readonly

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

maxPacketLifeTime of type unsigned short, readonly , nullable

The RTCDataChannel.maxPacketLifeTime attribute returns the length of the time window (in milliseconds) during which transmissions and retransmissions may occur in unreliable mode, or null if unset. The attribute MUST be initialized to null by default and MUST return the value to which it was set when the RTCDataChannel was created.

maxRetransmits of type unsigned short, readonly , nullable

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

negotiated of type boolean, readonly

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

onbufferedamountlow of type EventHandler,

This event handler, of type bufferedamountlow, MUST be supported by all objects implementing the RTCDataChannel interface.

onclose of type EventHandler,

This event handler, of type close, MUST be supported by all objects implementing the RTCDataChannel interface.

onerror of type EventHandler,

This event handler, of type error, MUST be supported by all objects implementing the RTCDataChannel interface.

onmessage of type EventHandler,

This event handler, of type message, MUST be supported by all objects implementing the RTCDataChannel interface.

onopen of type EventHandler,

This event handler, of type open, MUST be supported by all objects implementing the RTCDataChannel interface.

ordered of type boolean, readonly

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

protocol of type DOMString, readonly

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

readyState of type RTCDataChannelState, readonly

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

6.2.2 Methods

close

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

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

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

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

3. Set channel's readyState attribute to closing.

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

No parameters.

Return type: void

send

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

Parameter	Type	Nullable	Optional	Description
data	DOMString	✘	✘

Return type: void

send

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

Parameter	Type	Nullable	Optional	Description
data	Blob	✘	✘

Return type: void

send

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

Parameter	Type	Nullable	Optional	Description
data	ArrayBuffer	✘	✘

Return type: void

send

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

Parameter	Type	Nullable	Optional	Description
data	ArrayBufferView	✘	✘

Return type: void

6.2.3 Dictionary RTCDataChannelInit Members

id of type unsigned short,

Overrides the default selection of id for this channel.

maxPacketLifeTime of type unsigned short,

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

maxRetransmits of type unsigned short,

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

negotiated of type boolean, , defaulting to false

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

ordered of type boolean, , defaulting to true

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

protocol of type DOMString, , defaulting to ""

Subprotocol name used for this channel.

6.3.1 Constructors

RTCDataChannelEvent

readonly attribute RTCDataChannel channel

Parameter	Type	Nullable	Optional	Description
type	DOMString	✘	✘
eventInitDict	RTCDataChannelEventInit	✘	✘

6.3.2 Attributes

channel of type RTCDataChannel, readonly

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

6.3.3 Dictionary RTCDataChannelEventInit Members

channel of type RTCDataChannel,

Issue

TODO

7.1.1 Attributes

dtmf of type RTCDTMFSender, readonly , nullable

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

7.2.1 Attributes

duration of type long, readonly

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

interToneGap of type long, readonly

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

ontonechange of type EventHandler,

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

toneBuffer of type DOMString, readonly

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

7.2.2 Methods

insertDTMF

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

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

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

The interToneGap parameter indicates the gap between tones. It MUST be at least 30 ms. The default value is 70 ms.

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

Issue

How are invalid values handled?

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

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

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

Parameter	Type	Nullable	Optional	Description
tones	DOMString	✘	✘
duration	long = 100	✘	✔
interToneGap	long = 70	✘	✔

Return type: void

7.3.1 Constructors

RTCDTMFToneChangeEvent

readonly attribute DOMString tone

Parameter	Type	Nullable	Optional	Description
type	DOMString	✘	✘
eventInitDict	RTCDTMFToneChangeEventInit	✘	✘

7.3.2 Attributes

tone of type DOMString, readonly

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

7.3.3 Dictionary RTCDTMFToneChangeEventInit Members

tone of type DOMString,

Issue

TODO

8.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 InvalidStateError exception.

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

3. Let selectorArg be the methods first argument.

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, representing the gathered stats, as its argument.

Parameter	Type	Nullable	Optional	Description
selector	MediaStreamTrack	✔	✘
successCallback	RTCStatsCallback	✘	✘
failureCallback	RTCPeerConnectionErrorCallback	✘	✘

Return type: void

8.3.1 Callback RTCStatsCallback Parameters

report of type RTCStatsReport

A RTCStatsReport representing the gathered stats.

8.4.1 Methods

RTCStats

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

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

Parameter	Type	Nullable	Optional	Description
id	DOMString	✘	✘

Return type: getter

8.5.1 Dictionary RTCStats Members

id of type DOMString,

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

Issue

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

timestamp of type DOMHiResTimeStamp,

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

type of type RTCStatsType,

The type of this object.

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

8.6.1 Dictionary RTCRTPStreamStats Members

remoteId of type DOMString,

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

ssrc of type DOMString,

...

8.6.2 Dictionary RTCInboundRTPStreamStats Members

bytesReceived of type unsigned long,

...

packetsReceived of type unsigned long,

...

8.6.3 Dictionary RTCOutboundRTPStreamStats Members

bytesSent of type unsigned long,

...

packetsSent of type unsigned long,

...

9.1.1 Identity Provider Selection

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

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

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

9.1.2 Instantiating an IdP Proxy

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

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

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

The realm is populated with a global that implements WorkerGlobalScope [WEBWORKERS].

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

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

interface RTCIdentityProviderGlobalScope : WorkerGlobalScope {
    readonly    attribute RTCIdentityProviderRegistrar rtcIdentityProvider;
};

9.2.1 Methods

register

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

Parameter	Type	Nullable	Optional	Description
idp	RTCIdentityProvider	✘	✘

Return type: void

9.2.2 Interface Exposed by Identity Providers

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

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

9.2.3 Identity Assertion and Validation Results

dictionary RTCIdentityAssertionResult {
    required RTCIdentityProviderDetails idp;
    required DOMString                  assertion;
};

dictionary RTCIdentityProviderDetails {
    required DOMString domain;
             DOMString protocol = "default";
};

dictionary RTCIdentityValidationResult {
    required DOMString identity;
    required DOMString contents;
};

9.3.1 User Login Procedure

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

Rejecting the promise returned by generateAssertion will cause the error to propagate to the application. Login errors are indicated by rejecting the promise with an object that has a name attribute set to "IdpLoginError".

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

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

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

9.5.1 Attributes

idpLoginUrl of type DOMString, readonly , nullable

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

peerIdentity of type Promise<RTCIdentityAssertion>, readonly

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

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

9.5.2 Methods

getIdentityAssertion

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

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

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

2. Request an identity assertion from the IdP.

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

No parameters.

Return type: Promise<DOMString>

setIdentityProvider

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

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

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

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

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

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

Parameter	Type	Nullable	Optional	Description
provider	DOMString	✘	✘
protocol	DOMString	✘	✔
usernameHint	DOMString	✘	✔

Return type: void

9.5.3 Attributes

idp of type DOMString,

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

name of type DOMString,

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

10.2.1 id

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

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

10.2.2 Events on MediaStream

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

1. Let stream be the target MediaStream object.

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

3. Add track to stream's track set.

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

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

1. Let stream be the target MediaStream object.

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

3. Remove track from stream's track set.

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

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

10.4.1 Dictionary MediaStreamConstraints Members

peerIdentity of type DOMString,

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

10.4.2 Extended MediaStreamTrack Properties

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

partial interface MediaStreamTrack {
    readonly    attribute boolean      isolated;
                attribute EventHandler onisolationchange;
};

10.4.3 Isolated Streams and RTCPeerConnection

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

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

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

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

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

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

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

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

10.4.4 Protection Afforded by Media Isolation

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

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

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

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