RTCConfiguration Type

sequence<RTCIceServer> iceServers

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

RTCIceTransports iceTransports = "all"

Indicates which candidates the ICE engine is allowed to use.

DOMString peerIdentity

Sets the target peer identity for the RTCPeerConnection. The RTCPeerConnection will establish a connection to a remote peer unless it can be successfully authenticated with the provided name.

RTCIceServer Type

(DOMString or sequence<DOMString> urls

STUN or TURN URI(s) as defined in [[!RFC7064]] and [[!RFC7065]] or other URI types.

DOMString username

If this RTCIceServer object represents a TURN server, then this attribute specifies the username to use with that TURN server.

DOMString credential

If this RTCIceServer object represents a TURN server, then this attribute specifies the credential to use with that TURN server.

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

An example array of RTCIceServer objects is:

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

RTCIceTransports Enum

none

The ICE engine MUST not send or receive any packets at this point.

relay

The ICE engine MUST only use media relay candidates such as candidates passing through a TURN server. This can be used to reduce leakage of IP addresses in certain use cases.

all

The ICE engine may use any type of candidates when this value is specified.

Offer/Answer Options

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

long offerToReceiveVideo

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

long offerToReceiveAudio

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

boolean voiceActivityDetection = true

Many codecs and system are capable of detecting "silence" and changing their behavior in this case by doing things such as not transmitting any media. In many cases, such as when dealing with emergency calling or sounds other than spoken voice, it is desirable to be able to turn off this behavior. This option allows the application to provide information about whether it wishes this type of processing enabled or disabled.

boolean iceRestart = false

When the value of this dictionary member is true, the generated description will have ICE credentials that are different from the current credentials (as visible in the localDescription attribute's SDP). Applying the generated description will restart ICE.

When the value of this dictionary member is false, and the localDescription attribute has valid ICE credentials, the generated description will have the same ICE credentials as the current value from the localDescription attribute.

yes

An identity MUST be requested.

no

No identity is to be requested.

ifconfigured

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

Operation

Calling new RTCPeerConnection(configuration ) creates an RTCPeerConnection object.

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

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

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

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

1. Validate the RTCConfiguration argument by running the steps defined by the updateIce() method.

2. Let connection be a newly created RTCPeerConnection object.

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

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

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

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

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

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

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

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

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

1. Let connection be the RTCPeerConnection expecting this media.

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

3. Run the algorithm to represent an incoming component with a track for each incoming component.

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

4. Queue a task to run the following substeps:

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

   2. Add stream to connection's remote streams set.

   3. Fire a stream event named addstream with stream at the connection object.

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

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

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

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

3. By definition, stream is now ended.

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

4. Queue a task to run the following substeps:

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

   2. Remove stream from connection's remote streams set.

   3. Fire a stream event named removestream with stream at the connection object.

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

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

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

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

Interface Definition

Constructor (RTCConfiguration configuration)

See the RTCPeerConnection constructor algorithm.

void createOffer (RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback, optional RTCOfferOptions options)

The createOffer method generates a blob of SDP that contains an RFC 3264 offer with the supported configurations for the session, including descriptions of the local MediaStreams attached to this RTCPeerConnection, the codec/RTP/RTCP options supported by this implementation, and any candidates that have been gathered by the ICE Agent. The options parameter may be supplied to provide additional control over the offer generated.

As an offer, the generated SDP will contain the full set of capabilities supported by the session (as opposed to an answer, which will include only a specific negotiated subset to use); for each SDP line, the generation of the SDP must follow the appropriate process for generating an offer. In the event createOffer is called after the session is established, createOffer will generate an offer that is compatible with the current session, incorporating any changes that have been made to the session since the last complete offer-answer exchange, such as addition or removal of streams. If no changes have been made, the offer will include the capabilities of the current local description as well as any additional capabilities that could be negotiated in an updated offer.

Session descriptions generated by createOffer MUST be immediately usable by setLocalDescription without causing an error as long as setLocalDescription is called within the successCallback function. If a system has limited resources (e.g. a finite number of decoders), createOffer needs to return an offer that reflects the current state of the system, so that setLocalDescription will succeed when it attempts to acquire those resources. The session descriptions MUST remain usable by setLocalDescription without causing an error until at least end of the successCallback function. Calling this method is needed to get the ICE user name fragment and password.

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

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

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

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

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

void createAnswer (RTCSessionDescriptionCallback successCallback, RTCPeerConnectionErrorCallback failureCallback)

The createAnswer method generates an [[!SDP]] answer with the supported configuration for the session that is compatible with the parameters in the remote configuration. Like createOffer, the returned blob contains descriptions of the local MediaStreams attached to this RTCPeerConnection, the codec/RTP/RTCP options negotiated for this session, and any candidates that have been gathered by the ICE Agent. The options parameter may be supplied to provide additional control over the generated answer.

As an answer, the generated SDP will contain a specific configuration that, along with the corresponding offer, specifies how the media plane should be established. The generation of the SDP must follow the appropriate process for generating an answer.

Session descriptions generated by createAnswer must be immediately usable by setLocalDescription without generating an error if setLocalDescription is called from the successCallback function. Like createOffer, the returned description should reflect the current state of the system. The session descriptions MUST remain usable by setLocalDescription without causing an error until at least the end of the successCallback function. Calling this method is needed to get the ICE user name fragment and password.

An answer can be marked as provisional, as described in [[!RTCWEB-JSEP]], by setting the type to "pranswer".

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

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

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

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

void setLocalDescription (RTCSessionDescription description, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback)

The setLocalDescription() method instructs the RTCPeerConnection to apply the supplied RTCSessionDescription as the local description.

This API changes the local media state. In order to successfully handle scenarios where the application wants to offer to change from one media format to a different, incompatible format, the RTCPeerConnection must be able to simultaneously support use of both the old and new local descriptions (e.g. support codecs that exist in both descriptions) until a final answer is received, at which point the RTCPeerConnection can fully adopt the new local description, or rollback to the old description if the remote side denied the change.

ISSUE: how to indicate to rollback?

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

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

• If this RTCPeerConnection object's signaling state is closed, the user agent MUST throw an InvalidStateError exception and abort this operation.

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

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

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

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

  3. If the reason for the failure is:

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

       Let errorType be InvalidSessionDescriptionError.

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

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

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

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

  4. Invoke the failureCallback with an DOMError object, whose name attribute is errorType, as its argument.

• If the RTCSessionDescription argument is applied successfully, then user agent must queue a task runs the following steps:

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

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

  3. Set connection's description attribute (localDescription or remoteDescription depending on the setting operation) to the RTCSessionDescription argument.

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

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

  6. Set connection's signalingState accordingly.

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

  8. Queue a new task that, if connection's signalingState is not closed, invokes the successCallback.

readonly attribute RTCSessionDescription? localDescription

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.

void setRemoteDescription (RTCSessionDescription description, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback)

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

When the method is invoked, the user agent must follow the processing model of setLocalDescription(), with the following additional conditions:

• If an a=identity attribute is present in the session description, the browser validates the identity assertion.. Identity validation completes asynchronously and does not block the completion of setRemoteDescription, unless there is a target peer identity.

  The target peer identity cannot be changed once set. Once set, if a different value is provided, the user agent MUST throw an InvalidStateError exception and abort this operation.

• If the "peerIdentity" configuration is applied to the RTCPeerConnection, this establishes a target peer identity. Alternatively, if the RTCPeerConnection has previously authenticated the identity of the peer (that is, there is a current value for peerIdentity), then this also establishes a target peer identity.

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

readonly attribute RTCSessionDescription? remoteDescription

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.

readonly attribute RTCSignalingState signalingState

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

void updateIce (RTCConfiguration configuration)

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

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

When the updateIce() method is invoked, the user MUST run the following steps to process the RTCConfiguration dictionary:

1. If the iceTransports member is present, let its value be the ICE Agent's ICE transports setting.

2. If the iceTransports member was omitted and the ICE Agent's ICE transports setting is unset, set the ICE Agent's ICE transports setting to the iceTransports dictionary member default value.

3. If the iceServers dictionary member is present, but its value is an empty list, then throw an InvalidAccessError and abort these steps. If the list, on the other hand, has elements, each element must be validated by running the following sub-steps:

   1. Let server be the current list element.

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

   3. If server.urls is a string, let urls be a list consisting of just that string. Otherwise, let urls refer to the server.urls list.

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

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

   After passing the validation, let the iceServers dictionary member be the ICE Agent's ICE servers list.

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

   6. If the iceServers dictionary member was omitted, and the ICE Agent's ICE servers list is unset, throw an InvalidAccessError and abort these steps.

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

void addIceCandidate (RTCIceCandidate candidate, VoidFunction successCallback, RTCPeerConnectionErrorCallback failureCallback)

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

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

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

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

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

readonly attribute RTCIceGatheringState iceGatheringState

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

readonly attribute RTCIceConnectionState iceConnectionState

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

RTCConfiguration getConfiguration()

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

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

sequence<MediaStream> getLocalStreams()

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

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

sequence<MediaStream> getRemoteStreams()

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

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

MediaStream? getStreamById(DOMString streamId)

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

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

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

void addStream (MediaStream stream)

Adds a new stream to the RTCPeerConnection.

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

1. Let connection be the RTCPeerConnection object on which the MediaStream, stream, is to be added.

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

3. If stream is already in connection's local streams set, then abort these steps.

4. Add stream to connection's local streams set.

5. A stream could have contents that are inaccessible to the application. This can be due to being marked with a peerIdentity option or anything that would make a stream CORS cross-origin. These streams can be added to the local streams set but content MUST NOT be transmitted, though streams marked with peerIdentity can be transmitted if they meet the requirements for sending (see ) .

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

   Note that this property can change over time.

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

void removeStream (MediaStream stream)

Removes the given stream from the RTCPeerConnection.

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

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

1. Let connection be the RTCPeerConnection object on which the MediaStream, stream, is to be removed.

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

3. If stream is not in connection's local streams set, then abort these steps.

4. Remove stream from connection's local streams set.

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

void close ()

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

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

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

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

attribute EventHandler onnegotiationneeded

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

attribute EventHandler onicecandidate

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

attribute EventHandler onsignalingstatechange

This event handler, of event handler event type signalingstatechange, MUST be supported by all objects implementing the RTCPeerConnection interface. It is called any time the readyState changes, i.e., from a call to setLocalDescription, a call to setRemoteDescription, or code. It does not fire for the initial state change into new.

attribute EventHandler onaddstream

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

attribute EventHandler onremovestream

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

attribute EventHandler oniceconnectionstatechange

This event handler, of event handler event type iceconnectionstatechange, MUST be fired by all objects implementing the RTCPeerConnection interface. It is called any time the RTCPeerConnection ice connection state changes.

Garbage collection

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

RTCPeerState Enum

stable

There is no offer­answer exchange in progress. This is also the initial state in which case the local and remote descriptions are empty.

have-local-offer

A local description, of type "offer", has been successfully applied.

have-remote-offer

A remote description, of type "offer", has been successfully applied.

have-local-pranswer

A remote description of type "offer" has been successfully applied and a local description of type "pranswer" has been successfully applied.

have-remote-pranswer

A local description of type "offer" has been successfully applied and a remote description of type "pranswer" has been successfully applied.

closed

The connection is closed.

The non-normative peer state transitions are:

An example set of transitions might be:

Caller transition:

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

Callee transition:

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

RTCIceGatheringState Enum

new

The object was just created, and no networking has occurred yet.

gathering

The ICE engine is in the process of gathering candidates for this RTCPeerConnection.

complete

The ICE engine has completed gathering. Events such as adding a new interface or a new TURN server will cause the state to go back to gathering.

RTCIceConnectionState Enum

new

The ICE Agent is gathering addresses and/or waiting for remote candidates to be supplied.

checking

The ICE Agent has received remote candidates on at least one component, and is checking candidate pairs but has not yet found a connection. In addition to checking, it may also still be gathering.

connected

The ICE Agent has found a usable connection for all components but is still checking other candidate pairs to see if there is a better connection. It may also still be gathering.

completed

The ICE Agent has finished gathering and checking and found a connection for all components. Open issue: it is not clear how the non controlling ICE side knows it is in the state.

failed

The ICE Agent is finished checking all candidate pairs and failed to find a connection for at least one component. Connections may have been found for some components.

disconnected

Liveness checks have failed for one or more components. This is more aggressive than failed, and may trigger intermittently (and resolve itself without action) on a flaky network.

closed

The ICE Agent has shut down and is no longer responding to STUN requests.

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

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

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

Some example transitions might be:

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

The non-normative ICE state transitions are:

RTCPeerConnectionErrorCallback

DOMError error

An error object encapsulating information about what went wrong.

General Principles

Errors are indicated in two ways: exceptions and objects passed to error callbacks. Exceptions are thrown to indicate invalid state and other programming errors. For example when a method is called when the RTCPeerConnection is in an invalid state, or a state in which that particular method is not allowed to be executed. In all other cases, an error object MUST be provided to the error callback.

RTCSdpError

readonly attribute long sdpLineNumber

The line number of an RTCSessionDescription at which the error was encountered.

RTCSdpType

The RTCSdpType enum describes the type of an RTCSessionDescription instance.

offer

An RTCSdpType of "offer" indicates that a description should be treated as an [[!SDP]] offer.

pranswer

An RTCSdpType of "pranswer" indicates that a description should be treated as an [[!SDP]] answer, but not a final answer. A description used as an SDP "pranswer" may be applied as a response to a SDP offer, or an update to a previously sent SDP "pranswer".

answer

An RTCSdpType of "answer" indicates that a description should be treated as an [[!SDP]] final answer, and the offer-answer exchange should be considered complete. A description used as an SDP answer may be applied as a response to an SDP offer or as an update to a previously sent SDP "pranswer".

RTCSessionDescription Class

Constructor (optional RTCSessionDescriptionInit descriptionInitDict)

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

attribute RTCSdpType? type

The type of SDP this RTCSessionDescription represents.

attribute DOMString? sdp

The string representation of the SDP [[!SDP]]

serializer = { attribute }

RTCSdpType type

DOMString sdp

RTCSessionDescriptionCallback

RTCSessionDescription sdp

The object containing the SDP [[!SDP]].

RTCIceCandidate Type

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

Constructor (optional RTCIceCandidateInit candidateInitDict)

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

attribute DOMString? candidate

This carries the candidate-attribute as defined in section 15.1 of [[!ICE]].

attribute DOMString? sdpMid

If present, this contains the identifier of the "media stream identification" as defined in [[!RFC3388]] for the m-line this candidate is associated with.

attribute unsigned short? sdpMLineIndex

This indicates the index (starting at zero) of the m-line in the SDP this candidate is associated with.

serializer = { attribute}

DOMString candidate

DOMString sdpMid

unsigned short sdpMLineIndex

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.

Constructor(DOMString type, RTCPeerConnectionIceEventInit eventInitDict)

readonly attribute RTCIceCandidate candidate

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

RTCIceCandidate candidate

TODO

Identity Provider Selection

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

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

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

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

Instantiating an IdP Proxy

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

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

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

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

User Login Procedure

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

The "LOGINNEEDED" response includes a URL for a page where the authorization process can be completed. This URL is exposed to the application through the loginUrl attribute of the idpassertionerror event. This URL might be to a page where a user is able to enter their (IdP) username and password, or otherwise provide any information the IdP needs to authorize a assertion request.

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

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

id

The id attribute specified in MediaStream returns an id that is unique to this stream, so that streams can be recognized after they are sent through the RTCPeerConnection API.

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

The id of a MediaStream object is unique to the source of the stream, but that does not mean it is not possible to end up with duplicates. For example, a locally generated stream could be sent from one user agent to a remote peer using RTCPeerConnection and then sent back to the original user agent in the same manner, in which case the original user agent will have multiple streams with the same id (the locally-generated one and the one received from the remote peer).

Events on MediaStream

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

1. Let stream be the target MediaStream object.

2. Represent component with track: Run the following steps to create a track representing the incoming component:

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

   2. Initialize track’s kind attribute to "audio" or "video" depending on the media type of the incoming component.

   3. Initialize track’s id attribute to the component track id.

   4. Initialize track’s label attribute to "remote audio" or "remote video" depending on the media type of the incoming component.

   5. Initialize track’s readyState attribute to muted.

   6. Add track to stream’s track set.

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

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

1. Let stream be the target MediaStream object.

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

3. Remove track from stream’s track set.

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

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

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.

readonly attribute boolean isolated

A MediaStreamTrack is isolated (and the corresponding isolated attribute set to true) when content is inaccessible to the owning document. This occurs as a result of setting the peerIdentity option. A track is also isolated if it comes from a cross origin source.

attribute EventHandler onisolationchange

This event handler, of type isolationchange, is fired when the value of the isolated attribute changes.

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 [[!WEBRTC-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.

Tracks that are not bound to a particular peerIdentity do not cause other streams to be isolated, these tracks simply do not have their content transmitted.

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

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.