Introduction

An RTCPeerConnection instance allows to establish peer to peer communications. Communications are coordinated via a signaling channel which is provided by unspecified means, but generally by a script in the page via the server, e.g. using XMLHttpRequest [[XMLHttpRequest]] or Web Sockets [[WEBSOCKETS-API]].

Configuration

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

RTCPeerConnection Interface

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

State Definitions

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

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

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. Details on how the completed state in ICE is reached are covered in [[!ICE]].

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

Callback Definitions

Error Handling

Session Description Model

Session Negotiation Model

Many changes to state of an RTCPeerConnection will require communication with the remote side via the signaling channel, in order to have the desired effect. The app can be kept informed as to when it needs to do signaling, by listening to the negotiationneeded event.

Interfaces for Connectivity Establishment

Priority and QoS Model

Many applications have multiple media flows of the same data type and often some of the flows are more important than others. WebRTC uses the priority and Quality of Service (QoS) framework described in [[!RTCWEB-TRANSPORT]] and [[!TSVWG-RTCWEB-QOS]] to provide priority and DSCP marking for packets that will help provide QoS in some networking environments. The priority setting can be used to indicate the relative priority of various flows. The priority API allows the JavaScript applications to tell the browser whether a particular media flow is high, medium, low or of very low importance to the application by setting the priority property of RTCRtpEncodingParameters objects to one of the following values.

Applications that use this API should be aware that often better overall user experience is obtained by lowering the priority of things that are not as important rather than raising the the priority of the things that are.

Certificate Management

The certificates that RTCPeerConnection instances use to authenticate with peers use the RTCCertificate interface. These objects can be explicitly generated by applications using RTCPeerConnection.generateCertificate and provided in the RTCConfiguration when constructing a new RTCPeerConnection instance.

The explicit certificate management functions provided here are optional. If an application does not provide the certificates configuration option when constructing an RTCPeerConnection a new set of certificates MUST be generated by the user agent. That set MUST include an ECDSA certificate with a private key on the P-256 curve and a signature with a SHA-256 hash.

static Promise<RTCCertificate> generateCertificate (AlgorithmIdentifier keygenAlgorithm)

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 window.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. If the algorithm normalization process produces an error, the call to generateCertificate MUST be rejected with that error.

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-4]] 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 NotSupportedError 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: new Uint8Array([1, 0, 1]), hash: "SHA-256" }, and { name: "ECDSA", namedCurve: "P-256" }.

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

RTCPeerConnection Interface Extensions

The RTP media API extends the RTCPeerConnection interface as described below.

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

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

sequence<RTCRtpTransceivers> getTransceivers()

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

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

RTCRtpSender addTrack (MediaStreamTrack track, MediaStream... streams)

Adds a new track to the RTCPeerConnection, and indicates 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.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. If an RTCRtpSender exists in connection's set of senders that has never been used to send (the corresponding media description has always had a direction of recvonly or inactive), then set that sender's .track to track and return the sender.

   Doing so will cause future calls to createOffer and createAnswer to mark the corresponding media description as sendrecv or sendonly, as defined in [[!JSEP]].

   .

5. If no such sender exists, create a new RTCRtpTransceiver with .sender.track set to track, add it to connection's set of transceivers, and return .sender to the caller.

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

7. Mark connection as needing negotiation.

void removeTrack (RTCRtpSender sender)

Stops sending media from sender. The RTCRtpSender will still appear in getSenders. Doing so will cause future calls to createOffer to mark the media description for the corresponding transceiver as recvonly or inactive, as defined in [[!JSEP]].

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

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

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

4. Stop sending media from sender.

5. Mark connection as needing negotiation.

RTCRtpTransceiver addTransceiver((MediaStreamTrack or DOMString) trackOrKind, RTCRtpTransceiverInit init)

Create a new RTCRtpTransceiver and add it to the collection of transceivers that will be returned by getReceivers().

Adding a transceiver will cause future calls to createOffer to add a media description for the corresponding transceiver, as defined in [[!JSEP]].

.

If a track is passed in, the value of the .sender.track will be set to that track and the MSID and media type generated by createOffer will be that of the track.

If a kind is passed in, the value of the .sender.track will be null and and media type generated by createOffer will be that of the kind. The MSID generated by createOffer (if necessary, such as when init.send == true) will be selected by the user agent and will not be related to any track. Future calls to .sender.replaceTrack with a track of a different kind will fail. Future calls will not change the MSID associated with the transceiver.

If init.sendEncodings is set, then subsequent calls to createOffer will be configured to send with multiple RTP encodings as defined in [[!JSEP]]. When setRemoteDescription is called with a corresponding remote description that is able to receive multiple RTP encodings as defined in [[!JSEP]], the RTCRtpSender may send multiple RTP encodings and the parameters in RTCRtpTransceiver.sender.getParameters() will reflect the encodings negotiated.

RID values passed into init.sendEncodings must be composed only of case-sensitive alphanumeric characters (a-z, A-Z, 0-9) up to a maximum of 16 characters.

attribute EventHandler ontrack

The event type of this event handler is track.

boolean send = true

If true, indicates that the RTCRtpTransceiver's RTCRtpSender will offer to send RTP and send RTP if the remote peer accepts. If false, indicates that the RTCRtpSender will not offer to send RTP and will not send RTP (the direction of the media description generated by createOffer will be recvonly or inactive).

boolean receive = true

If true, indicates that the RTCRtpTransceiver's RTCRtpReceiver will offer to receive RTP and receive RTP if the remote peer accepts. If false, indicates that the RTCRtpReceiver will not offer to receive RTP and will not receive RTP (the direction of the media description generated by createOffer will be sendonly or inactive).

sequence<MediaStream> streams

When the remote PeerConnection's ontrack event fires corresponding to the RTCRtpReceiver being added, these are the streams that will be put in the event.

RTCRtpSender Interface

The RTCRtpSender interface allows an application to control how a given MediaStreamTrack is encoded and transmitted to a remote peer. When setParameters is called is on an RTCRtpSender object, the encoding is changed appropriately.

readonly attribute MediaStreamTrack track

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

readonly attribute RTCDtlsTransport transport

The transport attribute is the transport over which media from track is sent in the form of RTP packets. When BUNDLE is used, many RTCRtpSender objects will share one transport and will all send RTP over the same transport. When RTCP mux is used, rtcpTransport will be null, and both RTP and RTCP traffic will flow over the transport described by transport.

readonly attribute RTCDtlsTransport? rtcpTransport

The rtcpTransport attribute is the transport over which RTCP is sent and received. When BUNDLE is used, many RTCRtpSender objects will share one rtcpTransport and will all send and receive RTCP over the same transport. When RTCP mux is used, rtcpTransport will be null, and both RTP and RTCP traffic will flow over the transport described by transport.

static RTCRtpCapabilities getCapabilities(DOMString kind)

The RTCRtpSender.getCapabilities method returns the most optimist view on the capabilities of the system for sending media of the given kind. It does not reserve any resources, ports, or other state but is meant to provide a way to discover the types of capabilities of the browser including which codecs may be supported.

void setParameters (RTCRtpParameters parameters)

The setParameters method updates how track is encoded and transmitted to a remote peer.

If any parameter in the parameters argument, marked as a Read-only parameter, has a value that is different from the corresponding parameter value returned from getParameters(), the user agent MUST throw a ReadOnlyError exception and abort this operation without updating the current parameters.

If codecs are reordered, the new order indicates the preference for sending, with the first codec being the codec with highest preference. If a codec is removed, that codec will not be used to send. The effect of reordering or removing codecs lasts until the codecs are renegotiated. After the codecs are renegotiated, they are set to the value negotiated, and setParameters needs to be called again to re-apply codec preferences.

RTCRtpParameters getParameters()

The getParameters method returns the RTCRtpSender object's current parameters for how track is encoded and transmitted to a remote RTCRtpReceiver. It may used with setParameters to change the parameters in the follwing way:

var params = sender.getParameters();
// ... make changes to RTCRtpParameters
params.encodings[0].active = false;
sender.setParameters(params)
            

Promise<void> replaceTrack (MediaStreamTrack withTrack)

Attempts to replace the track being sent with another track provided, without renegotiation.

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

1. Let sender be the RTCRtpSender object on which replaceTrack is invoked.

2. Let p be a new promise.

3. Let withTrack be the argument to this method.

4. If withTrack.kind differs from the sender.track.kind, then reject p with TypeError, return p and abort these steps.

5. Run the following steps in parallel:

   1. Determine if negotiation is needed to transmit withTrack in place of the sender's existing track. Ignore which MediaStream the track resides in and the id attribute of the track in this determination. If negotiation is needed, then reject p with InvalidModificationError, return p and abort these steps.

   2. Have the sender switch seamlessly to transmitting withTrack in place of what it is sending, without negotiating. To avoid track identifiers changing on the remote receiving end, the sender MUST retain the original track identifier and stream associations and use these in subsequent negotiations.

   3. Set sender.track attribute to withTrack, and resolve p with undefined.

6. Return p.

Changing dimensions and/or frame rates might not require negotiation. Cases that may require negotiation include:

1. Changing a frame rate to a value outside of the negotiated imageattr bounds, as described in [[!RFC6236]].
2. Changing a frame rate to a value that causes the block rate for the codec to be exceeded.
3. A video track differing in raw vs. pre-encoded format.
4. An audio track having a different number of channels.
5. Sources that also encode (typically hardware encoders) might be unable to produce the negotiated codec; similarly, software sources might not implement the codec that was negotiated for an encoding source.

sequence<RTCRtpEncodingParameters> encodings

A sequence containing parameters for RTP encodings of media.

sequence<RTCRtpHeaderExtensionParameters> headerExtensions

A sequence containing parameters for RTP header extensions.

RTCRtcpParameters rtcp

Parameters used for RTCP.

sequence<RTCRtpCodecParameters> codecs

A sequence containing the codecs that an RTCRtpSender will choose from in order to send media.

unsigned long ssrc

The SSRC of the RTP source stream of this encoding (non-RTX, non-FEC RTP stream). Read-only parameter.

RTCRtxParameters rtx

The parameters used for RTX, or unset if RTX is not being used.

RTCFecParameters fec

The parameters used for FEC, or unset if FEC is not being used.

boolean active

Indicates that this encoding is actively being sent. Setting it to false causes this encoding to no longer be sent. Setting it to true causes this encoding to be sent.

RTCPriorityType priority

Indicates the priority of this encoding. It is specified in [[!RTCWEB-TRANSPORT]], Section 4.

unsigned long maxBitrate

Indicates the maximum bitrate that can be used to send this encoding. The encoding may also be further constrained by other bandwidth limits (such as per-transport or per-session limits) below the maximum specified here. maxBitrate is the Transport Independent Application Specific Maximum (TIAS) bandwidth defined in [[RFC3890]] Section 6.2.2, which is the maximum bandwidth needed without counting IP or other transport layers like TCP or UDP.

RTCDegradationPreference degradationPreference = "balanced"

When bandwidth is constrained and the RtpSender needs to choose between degrading resolution or degrading framerate, degradationPreference indicates which is prefered.

DOMString rid

If set, this RTP encoding will be sent with the RID header extension as defined by [[!JSEP]].

float scaleResolutionDownBy = 1.0

If the sender's kind is "video", the video's resolution will be scaled down in each dimension by the given value before sending. For example, if the value is 2.0, the video will be scaled down by a factor of 2 in each dimension, resulting in sending a video of one quarter the size. If the value is 1.0, the video will not be affected. The value must be greater than 0.

maintain-framerate

Degrade resolution in order to maintain framerate.

maintain-resolution

Degrade framerate in order to maintain resolution.

balanced

Degrade a balance of framerate and resolution.

unsigned long ssrc

The SSRC of the RTP stream for RTX. Read-only parameter.

unsigned long ssrc

The SSRC of the RTP stream for FEC. Read-only parameter.

DOMString cname

The Canonical Name (CNAME) used by RTCP (e.g. in SDES messages). Read-only parameter.

boolean reducedSize

Whether reduced size RTCP [[RFC5506]] is configured (if true) or compound RTCP as specified in [[RFC3550]] (if false). Read-only parameter.

DOMString uri

The URI of the RTP header extension, as defined in [[RFC5285]]. Read-only parameter.

unsigned short id

The value put in the RTP packet to identify the header extension. Read-only parameter.

boolean encrypted

Whether the header extension is encryted or not. Read-only parameter.

unsigned short payloadType

The RTP payload type. This value can be set in the RTCRtpParameters.encodings[0].payloadType to control which codec should be used to send a given encoding.

DOMString mimeType

The codec MIME type. Valid types are listed in [[IANA-RTP-2]].

unsigned long clockRate

The codec clock rate expressed in Hertz.

unsigned short channels = 1

The number of channels (mono=1, stereo=2).

DOMString sdpFmtpLine

The a=fmtp line in the SDP corresponding to the codec, as defined by [[!JSEP]].

sequence<RTCRtpCodecCapability> codecs

Supported codecs.

sequence<RTCRtpHeaderExtensionCapability> headerExtensions

Supported RTP header extensions.

DOMString mimeType

The codec MIME type. Valid types are listed in [[IANA-RTP-2]].

DOMString uri

The URI of the RTP header extension, as defined in [[RFC5285]].

RTCRtpReceiver Interface

The RTCRtpReceiver interface allows an application to control the receipt of a MediaStreamTrack. When attributes on an RTCRtpReceiver are modified, a negotiation is triggered to signal the changes regarding what the application wants to receive to the other side.

readonly attribute MediaStreamTrack track

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

readonly attribute RTCDtlsTransport transport

The RTCRtpReceiver.transport attribute is the transport over which media for RTCRtpReceiver.track is received in the form of RTP packets. When BUNDLE is used, many RTCRtpReceiver objects will share one RTCRtpReceiver.transport and will all receive RTP over the same transport. When RTCP mux is used, RTCRtpReceiver.rtcpTransport will be null, and both RTP and RTCP traffic will flow over RTCRtpReceiver.transport.

readonly attribute RTCDtlsTransport? rtcpTransport

The RTCRtpReceiver.rtcpTransport attribute is the transport over which RTCP is sent and received. When BUNDLE is used, many RTCRtpReceiver objects will share one RTCRtpReceiver.rtcpTransport and will all send and receive RTCP over the same transport. When RTCP mux is used, RTCRtpReceiver.rtcpTransport will be null, and both RTP and RTCP traffic will flow over RTCRtpReceiver.transport.

static RTCRtpCapabilities getCapabilities(DOMString kind)

The RTCRtpReceiver.getCapabilities method returns the most optimistic view of the capabilities of the system for receiving media of the given kind. It does not reserve any resources, ports, or other state but is meant to provide a way to discover the types of capabilities of the browser including which codecs may be supported.

sequence<RTCRtpContributingSource> getContributingSources ()

Returns an RTCRtpContributingSource for each unique CSRC or SSRC received by this RTCRtpReceiver in the last 10 seconds.

The RTCRtpContributingSource objects contain information about a given contributing source, including the time the most recent time a packet was received from the source. The browser MUST keep information from RTP packets received in the previous 10 seconds. Each time an RTP packet is received, the RTCRtpContributingSource objects are updated. If the RTP packet contains CSRCs, then the RTCRtpContributingSource objects corresponding to those CSRCs are updated. If the RTP packet contains no CSRCs, then the RTCRtpContributingSource object corresponding to the SSRC is updated.

readonly attribute DOMHighResTimeStamp timestamp

The timestamp of type DOMHighResTimeStamp [[!HIGHRES-TIME]], indicating the time of reception of the most recent RTP packet containing the source. The timestamp is defined in [[!HIGHRES-TIME]] and corresponds to a local clock.

readonly attribute unsigned long source

The CSRC or SSRC value of the contributing source.

readonly attribute byte? audioLevel

The audio level contained in the last RTP packet received from this source. If the source was set from an SSRC, this will be the level value defined in [[!RFC6464]]. If an RFC 6464 extension header is not present, the browser will compute the value as if it had come from RFC 6464 and use that. If the source was set from a CSRC, this will be the level value defined in [[!RFC6465]]. RFC 6464 and 6465 define the level as a integral value from 0 to 127 representing the audio level in negative decibels relative to the loudest signal that they system could possibly encode. Thus, 0 represents the loudest signal the system could possibly encode, and 127 represents silence.

RTCRtpTransceiver Interface

The RTCRtpTransceiver interface represents a combination of an RTCRtpSender and an RTCRtpReceiver that share a common mid.

readonly attribute DOMString? mid

The mid attribute is the mid negotatiated and present in the local and remote descriptions as defined in [[!JSEP]]. Before negotiation is complete, the mid value may be null. After rollbacks, the value may change from a non-null value to null.

[SameObject] readonly attribute RTCRtpSender sender

The sender attribute is the RTCRtpSender corresponding to the RTP media that may be sent with mid = mid.

[SameObject] readonly attribute RTCRtpReceiver receiver

The receiver attribute is the RTCRtpReceiver corresponding to the RTP media that may be received with mid = mid.

readonly attribute boolean stopped

The stopped attribute indicates that the sender of this transceiver will no longer send, and that the receiver will no longer receive. It is true if either stop has been called or if setting the local or remote description has caused the RTCRtpReceiver to be stopped.

void stop()

The stop method stops the RTCRtpTransceiver. The sender of this transceiver will no longer send, and the receiver will no longer receive.

void setCodecPreferences(sequence<RTCRtpCodecCapability> codecs)

The setCodecPreferences method overrides the default codec preferences used by the user agent. When generating a session description using either createOffer or createAnswer, the user agent MUST use the indicated codecs, in the order specified in the codecs argument, for the media section corresponding to this RTCRtpTransceiver. Note that calls to createAnswer will use only the common subset of these codecs and the codecs that appear in the offer.

This method allows applications to disable the negotiation of specific codecs. It also allows an application to cause a remote peer to prefer the codec that appears first in the list for sending.

Codec preferences remain in effect for all calls to createOffer and createAnswer that include this RTCRtpTransceiver until this method is called again. Setting codecs to an empty sequence resets codec preferences to any default value.

RTCDtlsTransport Interface

The RTCDtlsTransport interface allows an application access to information about the Datagram Transport Layer Security (DTLS) transport over which RTP and RTCP packets are sent and received by RTCRtpSender and RTCRtpReceiver objects, as well other data such as SCTP packets sent and received by data channels. In particular, DTLS adds security to an underlying transport, and the RTCDtlsTransport interface allows access to information about the underlying transport and the security added.

readonly attribute RTCIceTransport transport

The transport attribute is the underlying transport that is used to send and receive packets. The underlying transport may not be shared between multiple active RTCDtlsTransport objects.

readonly attribute RTCDtlsTransportState state

The state attribute MUST return the state of the transport.

sequence<ArrayBuffer> getRemoteCertificates()

Returns a sequence of ArrayBuffer containing the remote certificates in use by the remote side.

attribute EventHandler onstatechange

This event handler, of event handler event type statechange, MUST be fired any time the RTCDtlsTransport state changes.

RTCDtlsTransportState Enum

new

DTLS has not started negotiating yet.

connecting

DTLS is in the process of negotiating a secure connection.

connected

DTLS has completed negotiation of a secure connection.

closed

The transport has been closed.

failed

The transport has failed as the result of an error (such as a failure to validate the remote fingerprint).

RTCIceTransport Interface

The RTCIceTransport interface allows an application access to information about the ICE transport over which packets are sent and received. In particular, ICE manages peer-to-peer connections which involve state which the application may want to access.

readonly attribute RTCIceRole role

The role attribute MUST return the ICE role of the transport.

readonly attribute RTCIceComponent component

The component attribute MUST return the ICE component of the transport.

readonly attribute RTCIceConnectionState state

The state attribute MUST return the state of the transport.

readonly attribute RTCIceGatheringState gatheringState

The gathering state attribute MUST return the gathering state of the transport.

sequence<RTCIceCandidate> getLocalCandidates()

Returns a sequence describing the local ICE candidates gathered for this RTCIceTransport and sent in onicecandidate

sequence<RTCIceCandidate> getRemoteCandidates()

Returns a sequence describing the remote ICE candidates received by this RTCIceTransport via addIceCandidate()

RTCIceCandidatePair? getSelectedCandidatePair()

Returns the selected candidate pair on which packets are sent, or null if there is no such pair.

RTCIceParameters? getLocalParameters()

Returns the local ICE parameters received by this RTCIceTransport via setLocalDescription(), or null if the parameters have not yet been received.

RTCIceParameters? getRemoteParameters()

Returns the remote ICE parameters received by this RTCIceTransport via setRemoteDescription() or null if the parameters have not yet been received.

attribute EventHandler onstatechange

This event handler, of event handler event type statechange, MUST be fired any time the RTCIceTransport state changes.

attribute EventHandler ongatheringstatechange

This event handler, of event handler event type gatheringstatechange, MUST be fired any time the RTCIceTransportgathering state changes.

attribute EventHandler onselectedcandidatepairchange

This event handler, of event handler event type selectedcandidatepairchange, MUST be fired any time the RTCIceTransport's selected candidate pair changes.

DOMString usernameFragment

The ICE username fragment as defined in [[!ICE]], Section 7.1.2.3.

DOMString password

The ICE password as defined in [[!ICE]], Section 7.1.2.3.

RTCIceCandidate local

The local ICE candidate.

RTCIceCandidate remote

The remote ICE candidate.

RTCIceRole Enum

controlling

A controlling agent as defined by [[!ICE]], Section 3.

controlled

A controlled agent as defined by [[!ICE]], Section 3.

RTCIceComponent Enum

RTP

The ICE Transport is used for RTP (or RTP/RTCP-multiplexing), as defined in [[!ICE]], Section 4.1.1.1. Protocols multiplexed with RTP (e.g. data channel) share its component ID.

RTCP

The ICE Transport is used for RTCP as defined by [[!ICE]], Section 4.1.1.1.

RTCTrackEvent

The track event uses the RTCTrackEvent interface.

Firing an RTCTrackEvent event named e with an RTCRtpReceiver receiver, a MediaStreamTrack track and a MediaStream[] streams, 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 RTCTrackEvent interface with the receiver attribute set to receiver, track attribute set to track, streams attribute set to streams, MUST be created and dispatched at the given target.

Constructor(DOMString type, RTCTrackEventInit eventInitDict)

readonly attribute RTCRtpReceiver receiver

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

readonly attribute MediaStreamTrack track

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

readonly attribute FrozenArray<MediaStream> streams

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

RTCRtpReceiver receiver

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

MediaStreamTrack track

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

sequence<MediaStream> streams

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

RTCPeerConnection Interface Extensions

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

readonly attribute RTCSctpTransport? sctp

The SCTP transport over which SCTP data is sent and received. If SCTP has not been negotiated, the value is null.

RTCDataChannel createDataChannel([TreatNullAs=EmptyString] DOMString label, optional RTCDataChannelInit dataChannelDict)

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 negotiated is false and label is longer than 65535 bytes long, throw a TypeError.
6. If negotiated is false and protocol is longer than 65535 bytes long, throw a TypeError.

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

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

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

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

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

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

attribute EventHandler ondatachannel

The event type of this event handler is datachannel.

RTCDataChannel

The RTCDataChannel interface represents a bi-directional data channel between two peers. A RTCDataChannel is created via a factory method on an RTCPeerConnection object. The messages sent between the browsers are described in [[!RTCWEB-DATA]] and [[!RTCWEB-DATA-PROTOCOL]].

There are two ways to establish a connection with RTCDataChannel. The first way is to simply create a RTCDataChannel at one of the peers with the negotiated RTCDataChannelInit dictionary member unset or set to its default value false. This will announce the new channel in-band and trigger a RTCDataChannelEvent with the corresponding RTCDataChannel object at the other peer. The second way is to let the application negotiate the RTCDataChannel. To do this, create a RTCDataChannel object with the negotiated RTCDataChannelInit dictionary member set to true, and signal out-of-band (e.g. via a web server) to the other side that it SHOULD create a corresponding RTCDataChannel with the negotiated RTCDataChannelInit dictionary member set to true and the same id. This will connect the two separately created RTCDataChannel objects. The second way makes it possible to create channels with asymmetric properties and to create channels in a declarative way by specifying matching ids.

Each RTCDataChannel has an associated underlying data transport that is used to transport actual data to the other peer. The transport properties of the underlying data transport, such as in order delivery settings and reliability mode, are configured by the peer as the channel is created. The properties of a channel cannot change after the channel has been created. The actual wire protocol between the peers is specified by the WebRTC DataChannel Protocol specification [[RTCWEB-DATA]].

A RTCDataChannel can be configured to operate in different reliability modes. A reliable channel ensures that the data is delivered at the other peer through retransmissions. An unreliable channel is configured to either limit the number of retransmissions ( maxRetransmits ) or set a time during which transmissions (including retransmissions) are allowed ( maxPacketLifeTime ). These properties can not be used simultaneously and an attempt to do so will result in an error. Not setting any of these properties results in a reliable channel.

A RTCDataChannel, created with createDataChannel() or dispatched via a RTCDataChannelEvent, MUST initially be in the connecting state. When the RTCDataChannel object's underlying data transport is ready, the user agent MUST announce the RTCDataChannel as open.

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

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

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

3. Set channel's readyState attribute to open.

4. Fire a simple event named open at channel.

When an underlying data transport is to be announced (the other peer created a channel with negotiated unset or set to false), the user agent of the peer that did not initiate the creation process MUST queue a task to run the following steps:

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

2. Let channel be a newly created RTCDataChannel object.

3. Let configuration be an information bundle received from the other peer as a part of the process to establish the underlying data transport described by the WebRTC DataChannel Protocol specification [[!RTCWEB-DATA-PROTOCOL]].

4. Initialize channel's label, ordered, maxPacketLifeTime, maxRetransmits, protocol, negotiated and id attributes to their corresponding values in configuration.

5. Set channel's readyState attribute to connecting.

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

An RTCDataChannel object's underlying data transport may be torn down in a non-abrupt manner by running the closing procedure. When that happens the user agent MUST, unless the procedure was initiated by the close() method, queue a task that sets the object's readyState attribute to closing. This will eventually render the data transport closed.

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

1. Let channel be the RTCDataChannel object whose transport was closed.

   The data transport protocol will specify what happens to, e.g. buffered data, when the data transport is closed.

2. Set channel's readyState attribute to closed.

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

4. Fire a simple event named close at channel.

readonly attribute DOMString label

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.

readonly attribute boolean ordered

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.

readonly attribute unsigned short? maxPacketLifeTime

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.

readonly attribute unsigned short? maxRetransmits

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.

readonly attribute DOMString protocol

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.

readonly attribute boolean negotiated

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.

readonly attribute unsigned short id

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.

readonly attribute RTCDataChannelState readyState

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

readonly attribute unsigned long bufferedAmount

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

attribute unsigned long bufferedAmountLowThreshold

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.

attribute EventHandler onopen

The event type of this event handler is open.

attribute EventHandler onbufferedamountlow

The event type of this event handler is bufferedamountlow.

attribute EventHandler onerror

The event type of this event handler is error.

attribute EventHandler onclose

The event type of this event handler is close.

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

attribute EventHandler onmessage

The event type of this event handler is message.

attribute DOMString binaryType

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.

void send(USVString data)

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

void send(Blob data)

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

void send(ArrayBuffer data)

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

void send(ArrayBufferView data)

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

boolean ordered = 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.

unsigned short maxPacketLifeTime

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.

unsigned short maxRetransmits

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

DOMString protocol = ""

Subprotocol name used for this channel.

boolean negotiated = 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.

unsigned short id

Overrides the default selection of id for this channel.

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

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

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

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

   • string object:

     Let data be the object and increase the bufferedAmount attribute by the number of bytes needed to express data as UTF-8.

   • Blob object:

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

   • ArrayBuffer object:

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

   • ArrayBufferView object:

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

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

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

connecting

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

open

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

closing

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

closed

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

RTCDataChannelEvent

The datachannel event uses the RTCDataChannelEvent interface.

Firing a datachannel event named e with a RTCDataChannel channel means that an event with the name e, which does not bubble (except where otherwise stated) and is not cancelable (except where otherwise stated), and which uses the RTCDataChannelEvent interface with the channel attribute set to channel, MUST be created and dispatched at the given target.

Constructor(DOMString type, RTCDataChannelEventInit eventInitDict)

readonly attribute RTCDataChannel channel

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

RTCDataChannel channel

TODO

Garbage Collection

A RTCDataChannel object MUST not be garbage collected if its

• readyState is connecting and at least one event listener is registered for open events, message events, error events, or close events.

• readyState is open and at least one event listener is registered for message events, error events, or close events.

• readyState is closing and at least one event listener is registered for error events, or close events.

• underlying data transport is established and data is queued to be transmitted.

RTCRtpSender Interface Extensions

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

readonly attribute RTCDTMFSender? dtmf

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

RTCDTMFSender

void insertDTMF(in DOMString tones, optional unsigned long duration = 100, optional unsigned long interToneGap = 70)

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. As noted in [[RTCWEB-AUDIO]] Section 3, support for the characters 0 through 9, #, and * are required.

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.

How are invalid values handled? (see also Issue 319)

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.

attribute EventHandler ontonechange

The event type of this event handler is tonechange. It returns the character for each tone as it is played out. See RTCDTMFToneChangeEvent for details.

readonly attribute DOMString toneBuffer

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.

readonly attribute long duration

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.

readonly attribute long interToneGap

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.

RTCDTMFToneChangeEvent

The tonechange event uses the RTCDTMFToneChangeEvent interface.

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

Constructor(DOMString type, RTCDTMFToneChangeEventInit eventInitDict)

readonly attribute DOMString tone

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.

DOMString tone

TODO

Introduction

The basic statistics model is that the browser maintains a set of statistics referenced by a selector. The selector may, for example, be a MediaStreamTrack. For a track to be a valid selector, it MUST be a MediaStreamTrack that is sent or received by the RTCPeerConnection object on which the stats request was issued. The calling Web application provides the selector to the getStats() method and the browser emits (in the JavaScript) a set of statistics that it believes is relevant to the selector.

The statistics returned are designed in such a way that repeated queries can be linked by the RTCStats id dictionary member. Thus, a Web application can make measurements over a given time period by requesting measurements at the beginning and end of that period.

RTCPeerConnection Interface Extensions

The Statistics API extends the RTCPeerConnection interface as described below.

Promise<RTCStatsReport> getStats( optional MediaStreamTrack? selector = null)

Gathers stats for the given selector and reports the result asynchronously.

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

1. Let selectorArg be the methods first argument.

2. If selectorArg is neither null nor a valid selector, return a promise rejected with a TypeError.

3. Let p be a new promise.

4. Run the following steps in parallel:

   1. Start gathering the stats indicated by selectorArg. If selectorArg is null, stats MUST be gathered for the whole RTCPeerConnection object.

   2. When the relevant stats have been gathered, resolve p with a new RTCStatsReport object, representing the gathered stats.

5. Return p.

RTCStatsCallback

RTCStatsReport report

A RTCStatsReport representing the gathered stats.

RTCStatsReport Object

The getStats() method delivers a successful result in the form of an RTCStatsReport object. An RTCStatsReport object is a map between strings that identify the inspected objects (RTCStats.id), and their corresponding RTCStats-derived dictionaries.

An RTCStatsReport may be composed of several RTCStats-derived dictionaries, each reporting stats for one underlying object that the implementation thinks is relevant for the selector. One achieves the total for the selector by summing over all the stats of a certain type; for instance, if a MediaStreamTrack is carried by multiple SSRCs over the network, the RTCStatsReport may contain one RTCStats-derived dictionary per SSRC (which can be distinguished by the value of the "ssrc" stats attribute).

readonly maplike<DOMString, object>

Use these to retrieve the various dictionaries descended from RTCStats that this stats report is composed of. The set of supported property names [[!WEBIDL]] is defined as the ids of all the RTCStats-derived dictionaries that have been generated for this stats report.

RTCStats Dictionary

An RTCStats dictionary represents the stats gathered by inspecting a specific object relevant to a selector. The RTCStats dictionary is a base type that specifies as set of default attributes, such as timestamp and type. Specific stats are added by extending the RTCStats dictionary.

Note that while stats names are standardized, any given implementation may be using experimental values or values not yet known to the Web application. Thus, applications MUST be prepared to deal with unknown stats.

Statistics need to be synchronized with each other in order to yield reasonable values in computation; for instance, if "bytesSent" and "packetsSent" are both reported, they both need to be reported over the same interval, so that "average packet size" can be computed as "bytes / packets" - if the intervals are different, this will yield errors. Thus implementations MUST return synchronized values for all stats in an RTCStats-derived dictionary.

DOMHighResTimeStamp timestamp

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

RTCStatsType type

The type of this object.

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

DOMString id

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.

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.

inboundrtp

Inbound RTP.

outboundrtp

Outbound RTP.

Derived Stats Dictionaries

DOMString ssrc

...

DOMString remoteId

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

unsigned long packetsReceived

...

unsigned long bytesReceived

...

unsigned long packetsSent

...

unsigned long bytesSent

...

Example

Consider the case where the user is experiencing bad sound and the application wants to determine if the cause of it is packet loss. The following example code might be used:

var baselineReport, currentReport;
var selector = pc.getSenders()[0].track;

pc.getStats(selector).then(function (report) {
    baselineReport = report;
})
.then(function() {
    return new Promise(function(resolve) {
        setTimeout(resolve, aBit); // ... wait a bit
    });
})
.then(function() {
    return pc.getStats(selector);
})
.then(function (report) {
    currentReport = report;
    processStats();
})
.catch(function (error) {
  log(error.toString());
});

function processStats() {
    // compare the elements from the current report with the baseline
    currentReport.forEach (now => {
        if (now.type != "outboundrtp")
            return;

        // get the corresponding stats from the baseline report
        base = baselineReport.get(now.id);

        if (base) {
            remoteNow = currentReport.get(now.remoteId);
            remoteBase = baselineReport.get(base.remoteId);

            var packetsSent = now.packetsSent - base.packetsSent;
            var packetsReceived = remoteNow.packetsReceived - remoteBase.packetsReceived;

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

Identity Provider Interaction

WebRTC offers and answers (and hence the channels established by RTCPeerConnection objects) can be authenticated by using a web-based Identity Provider (IdP). The idea is that the entity sending an offer or answer acts as the Authenticating Party (AP) and obtains an identity assertion from the IdP which it attaches to the session description. The consumer of the session description (i.e., the RTCPeerConnection on which setRemoteDescription() is called) acts as the Relying Party (RP) and verifies the assertion.

The interaction with the IdP is designed to decouple the browser from any particular identity provider; the browser need only know how to load the IdP's JavaScript, the location of which is determined by the IdP's identity, and the generic interface to generating and validating assertions. The IdP provides whatever logic is necessary to bridge the generic protocol to the IdP's specific requirements. Thus, a single browser can support any number of identity protocols, including being forward compatible with IdPs which did not exist at the time the browser was written.

Registering an IdP Proxy

An IdP proxy implements the RTCIdentityProvider callback interface, which is the means by which the user agent is able to request that an identity assertion be generated or validated.

Once instantiated, the IdP script is executed. The IdP MUST call the register() function on the RTCIdentityProviderRegistrar instance during script execution. If an IdP is not registered during this script execution, the user agent cannot use the IdP proxy and MUST fail any future attempt to interact with the IdP.

void register(RTCIdentityProvider idp)

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

Requesting Identity Assertions

The identity assertion request process is triggered by a call to createOffer, createAnswer, or getIdentityAssertion. When these calls are invoked and an identity provider has been set, the following steps are executed:

1. The RTCPeerConnection instantiates an IdP as described in Identity Provider Selection and Registering an IdP Proxy. If the IdP cannot be loaded, instantiated, or the IdP proxy is not registered, this process fails.

2. The RTCPeerConnection invokes the generateAssertion method on the RTCIdentityProvider instance registered by the IdP.

   The RTCPeerConnection generates the contents parameter to this method as described in [[!RTCWEB-SECURITY-ARCH]]. The value of contents includes the fingerprint of the certificate that was selected or generated during the construction of the RTCPeerConnection. The origin parameter contains the origin of the script that calls the RTCPeerConnection method that triggers this behavior. The usernameHint value is the same value that is provided to setIdentityProvider, if any such value was provided.

3. The IdP returns a Promise to the RTCPeerConnection. If the user has been authenticated by the IdP, and the IdP is willing to generate an identity assertion, the IdP resolves the promise with an identity assertion in the form of an RTCIdentityAssertionResult.

   This step depends entirely on the IdP. The methods by which an IdP authenticates users or generates assertions is not specified, though they could involve interacting with the IdP server or other servers.

4. The RTCPeerConnection MAY store the identity assertion for use with future offers or answers. If a fresh identity assertion is needed for any reason, applications can create a new RTCPeerConnection.

5. If the identity request was triggered by a createOffer() or createAnswer(), then the assertion is converted to a JSON string, base64-encoded and inserted into an a=identity attribute in the session description.

This process can fail. The IdP proxy MAY reject the promise, or the process of loading and registering the IdP could fail. If assertion generation fails, then the promise for the corresponding function call is rejected.

The browser SHOULD limit the time that it will allow for this process. This includes both the loading of the IdP proxy and the identity assertion generation. Failure to do so potentially causes the corresponding operation to take an indefinite amount of time. This timer can be cancelled when the IdP produces a response. The timer running to completion can be treated as equivalent to an error from the IdP.

Verifying Identity Assertions

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

The identity assertion request process involves the following asynchronous steps:

1. The RTCPeerConnection awaits any prior identity validation. Only one identity validation can run at a time for an RTCPeerConnection. This can happen because the resolution of setRemoteDescription is not blocked by identity validation unless there is a target peer identity.

2. The RTCPeerConnection loads the identity assertion from the session description and decodes the base64 value, then parses the resulting JSON. The idp parameter of the resulting dictionary contains a domain and an optional protocol value that identifies the IdP, as described in [[!RTCWEB-SECURITY-ARCH]].

3. The RTCPeerConnection instantiates the identified IdP as described in and . If the IdP cannot be loaded, instantiated or the IdP proxy is not registered, this process fails.

4. The RTCPeerConnection invokes the validateAssertion method on the RTCIdentityProvider instance registered by the IdP.

   The assertion parameter is taken from the decoded identity assertion. The origin parameter contains the origin of the script that calls the RTCPeerConnection method that triggers this behavior.

5. The IdP proxy returns a promise and performs the validation process asynchronously.

   The IdP proxy verifies the identity assertion using whatever means necessary. Depending on the authentication protocol this could involve interacting with the IDP server.

6. Once the assertion is successfully verified, the IdP proxy resolves the promise with an RTCIdentityValidationResult containing the validated identity and the original contents that are the payload of the assertion.

7. The RTCPeerConnection decodes the contents and validates that it contains a fingerprint value for every a=fingerprint attribute in the session description. This ensures that the certificate used by the remote peer for communications is covered by the identity assertion.

   If a peer offers a certificate that doesn't match an a=fingerprint line in the negotiated session description, the user agent MUST NOT permit communication with that peer.

8. The RTCPeerConnection validates that the domain portion of the identity matches the domain of the IdP as described in [[!RTCWEB-SECURITY-ARCH]].

9. The RTCPeerConnection resolves the peerIdentity attribute with a new instance of RTCIdentityAssertion that includes the IdP domain and peer identity.

10. The browser MAY display identity information to a user in browser UI. Any user identity information that is displayed in this fashion MUST use a mechanism that cannot be spoofed by content.

This process can fail at any step above. If identity validation fails, the peerIdentity promise is rejected with a DOMError that has a name of IdpError.

If identity validation fails and there is a target peer identity for the RTCPeerConnection, the promise returned by setRemoteDescription MUST be rejected.

If identity validation fails and there is no a target peer identity, the value of the peerIdentity MUST be set to a new, unresolved promise instance. This permits the use of renegotiation (or a subsequent answer, if the session description was a provisional answer) to resolve or reject the identity.

The browser SHOULD limit the time that it will allow for identity validation. This includes both the loading of the IdP proxy and the identity assertion validation. Failure to do so potentially causes the operation to take an indefinite amount of time. This timer can be cancelled when the IdP produces a response. The timer running to completion is treated as equivalent to an error from the IdP.

RTCPeerConnection Interface Extensions

The Identity API extends the RTCPeerConnection interface as described below.

void setIdentityProvider(DOMString provider, optional DOMString protocol, optional DOMString usernameHint)

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.

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

readonly attribute Promise<RTCIdentityAssertion> peerIdentity

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.

readonly attribute DOMString? idpLoginUrl

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

attribute DOMString idp

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

attribute DOMString name

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

Examples

The identity system is designed so that applications need not take any special action in order for users to generate and verify identity assertions; if a user has configured an IdP into their browser, then the browser will automatically request/generate assertions and the other side will automatically verify them and display the results. However, applications may wish to exercise tighter control over the identity system as shown by the following examples.

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

  pc.peerIdentity.then(identity =>
    console.log("IdP= " + identity.idp + " identity=" + identity.name));

Introduction

The MediaStreamTrack interface, as defined in the [[!GETUSERMEDIA]] specification, typically represents a stream of data of audio or video. One or more MediaStreamTracks can be collected in a MediaStream (strictly speaking, a MediaStream as defined in [[!GETUSERMEDIA]] may contain zero or more MediaStreamTrack objects).

A MediaStreamTrack may be extended to represent a media flow that either comes from or is sent to a remote peer (and not just the local camera, for instance). The extensions required to enable this capability on the MediaStreamTrack object will be described in this section. How the media is transmitted to the peer is described in [[!RTCWEB-RTP]], [[!RTCWEB-AUDIO]], and [[!RTCWEB-TRANSPORT]].

A MediaStreamTrack sent to another peer will appear as one and only one MediaStreamTrack to the recipient. A peer is defined as a user agent that supports this specification. In addition, the sending side application can indicate what MediaStream object(s) the MediaStreamTrack is member of. The corresponding MediaStream object(s) on the receiver side will be created (if not already present) and populated accordingly.

As also described earlier in this document, the objects RTCRtpSender and RTCRtpReceiver can be used by the application to get more fine grained control over the transmission and reception of MediaStreamTracks.

Channels are the smallest unit considered in the MediaStream specification. Channels are intended to be encoded together for transmission as, for instance, an RTP payload type. All of the channels that a codec needs to encode jointly MUST be in the same MediaStreamTrack and the codecs SHOULD be able to encode, or discard, all the channels in the track.

The concepts of an input and output to a given MediaStreamTrack apply in the case of MediaStreamTrack objects transmitted over the network as well. A MediaStreamTrack created by an RTCPeerConnection object (as described previously in this document) will take as input the data received from a remote peer. Similarly, a MediaStreamTrack from a local source, for instance a camera via [[!GETUSERMEDIA]], will have an output that represents what is transmitted to a remote peer if the object is used with an RTCPeerConnection object.

The concept of duplicating MediaStream and MediaStreamTrack objects as described in [[!GETUSERMEDIA]] is also applicable here. This feature can be used, for instance, in a video-conferencing scenario to display the local video from the user's camera and microphone in a local monitor, while only transmitting the audio to the remote peer (e.g. in response to the user using a "video mute" feature). Combining different MediaStreamTrack objects into new MediaStream objects is useful in certain situations.

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

MediaStream

MediaStreamTrack

A MediaStreamTrack object's reference to its MediaStream in the non-local media source case (an RTP source, as is the case for MediaStreamTracks received over an RTCPeerConnection ) is always strong.

When an RTCPeerConnection receives data on an RTP source for the first time, it MUST update the muted state of the corresponding MediaStreamTrack with the value false.

When an RTCPeerConnection's RTP source is temporarily unable to receive media due to a loss of connection or if a mute signal has been received, it MUST update the muted state of the corresponding MediaStreamTrack with the value true. When media data is available again, the muted state MUST be updated with the value false.

The mute signal mentioned in the previous paragraph is yet to be defined.

The procedure update a track's muted state is specified in [[!GETUSERMEDIA]].

When a track comes from a remote peer and the remote peer has permanently stopped sending data the ended event MUST be fired on the track, as specified in [[!GETUSERMEDIA]].

How do you know when it has stopped? This seems like an SDP question, not a media-level question. (Suggestion: when the track is ended, either through port 0, or removing the a=msid attrib)

Isolated Media Streams

A MediaStream acquired using getUserMedia() is, by default, accessible to an application. This means that the application is able to access the contents of tracks, modify their content, and send that media to any peer it chooses.

WebRTC supports calling scenarios where media is sent to a specifically identified peer, without the contents of media streams being accessible to applications. This is enabled by use of the peerIdentity parameter to getUserMedia().

An application willingly relinquishes access to media by including a peerIdentity parameter in the MediaStreamConstraints. This attribute is set to a DOMString containing the identity of a specific peer.

The MediaStreamConstraints dictionary is expanded to include the peerIdentity parameter.

DOMString peerIdentity

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

A user that is prompted to provide consent for access to a camera or microphone can be shown the value of the peerIdentity parameter, so that they can be informed that the consent is more narrowly restricted.

When the peerIdentity option is supplied to getUserMedia(), all of the MediaStreamTracks in the resulting MediaStream are isolated so that content is not accessible to any application. Isolated MediaStreamTracks can be used for two purposes:

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

• Used as the argument to addTrack() on an RTCPeerConnection instance, subject to the restrictions in isolated streams and RTCPeerConnection.

A MediaStreamTrack that is added to another MediaStream remains isolated. When an isolated MediaStreamTrack is added to a MediaStream with a different peerIdentity, the MediaStream gets a combination of isolation restrictions. A MediaStream containing MediaStreamTrack instances with mixed isolation properties can be displayed, but cannot be sent using RTCPeerConnection.

Any peerIdentity property MUST be retained on cloned copies of MediaStreamTracks.