Terminology

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

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

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

The terms MediaStream, MediaStreamTrack, Constraints, and Consumer are defined in [[!GETUSERMEDIA]].

The terms single-session transmission (SST) and multi-session transmission (MST) are defined in [[!RFC6190]]. While this specification supports SST but not MST, multiple streams may be utilized within a single RTP session.

Overview

An RTCDtlsTransport instance is associated to an RTCRtpSender or an RTCRtpReceiver.

Operation

A RTCDtlsTransport instance is optionally constructed from an RTCIceTransport object or an RTCDtlsTransport is automatically constructed.

Interface Definition

attribute RTCIceTransport transport

The associated RTCIceTransport instance.

readonly attribute RTCDtlsTransportState state

The current state of the DTLS transport.

RTCDtlsParameters getLocalParameters()

Obtain the DTLS parameters of the local RTCDtlsTransport.

RTCDtlsParameters? getRemoteParameters()

Obtain the current DTLS parameters of the remote RTCDtlsTransport.

sequence<ArrayBuffer> getRemoteCertificates()

Obtain the certificates used by the remote peer.

void start(RTCDtlsParameters remoteParameters)

Start DTLS transport negotiation with the parameters of the remote DTLS transport.

void stop()

Stops and closes the DTLS transport object.

attribute EventHandler? onstatechange

Set this handler to receive events when the state of the DTLS transport changes.

attribute EventHandler? onerror

Set this handler to receive error events.

Interface Definition

readonly attribute DOMError e

The DOMError object whose name attribute has the value TODO.

Interface Definition

readonly attribute RTCDtlsTransportState state

The state attribute contains the new RTCDtlsTransportState that caused the event.

The RTCDtlsParameters Object

The RTCDtlsParameters object includes information relating to DTLS configuration.

RTCDtlsRole role="auto"

The DTLS role, with a default of auto.

sequence<RTCDtlsFingerprint> fingerprint

Sequence of fingerprints.

enum RTCDtlsRole

auto

The DTLS role is be determined based on the resolved ICE role: the 'Controlled' role acts as the DTLS client, the 'Controlling' role acts as the DTLS server.

client

The DTLS client role.

server

The DTLS server role.

Example

enum RTCDtlsTransportState

RTCDtlsTransportState provides information about the state of the DTLS transport.

new

new state

connecting

connecting state

connected

connected state. Implies that all DTLS processing needed by upper layers (including DTLS/SRTP) has finished.

closed

closed state

Overview

An RTCIceTransport instance is associated to a transport object (such as RTCDtlsTransport), and provides RTC related methods to it.

Operation

An RTCIceTransport instance is constructed from an RTCIceRole and either an RTCIceListener or an RTCIceOptions object.

Interface Definition

readonly attribute RTCIceListener iceListener

The RTCIceListener specified in the RTCIceTransport constructor. If none was specified, the system will create an RTCIceListener automatically using the RTCIceOptions specified.

readonly attribute RTCIceRole role

RTCIceRole contains the current role of the ICE transport.

readonly attribute RTCIceTransportState state

The current state of the ICE transport.

readonly attribute RTCIceGatheringState iceGatheringState

The current state of ICE candidate gathering.

sequence<RTCIceCandidate> getLocalCandidates()

Retrieve the sequence of valid candidates associated with the local RTCIceTransport. This retrieves all candidates currently known, even if an onlocalcandidate event hasn't been processed yet.

sequence<RTCIceCandidate> getRemoteCandidates()

Retrieve the sequence of candidates associated with the remote RTCIceTransport.

void gather(RTCIceGatherPolicy gatherPolicy)

Start gathering RTCIceCandidate objects, based on the gather policy (set on the local system, not negotiated).

void start(RTCIceParameters remoteParameters, optional RTCIceRole role)

Starts candidate connectivity checks and attempts to connect to the remote RTCIceTransport.

void stop()

Stops and closes the current object.

RTCIceParameters getLocalParameters()

Obtain the ICE parameters of the local RTCIceTransport.

RTCIceParameters? getRemoteParameters()

Obtain the current ICE parameters of the remote RTCIceTransport.

void addRemoteCandidate(RTCIceCandidate remoteCandidate)

Add remote candidate associated with remote RTCIceTransport.

void setRemoteCandidates(sequence<RTCIceCandidate> remoteCandidates)

Set the sequence of candidates associated with the remote RTCIceTransport.

attribute EventHandler? onlocalcandidate

Set this handler to receive events when a new local candidate is available.

attribute EventHandler? onstatechange

Set this handler to receive events when the state of the RTCIceTransport has changed.

attribute EventHandler? ongatheringstatechange

Set this handler to receive an event when ICE gather state changes.

attribute EventHandler? onerror

Set this handler to receive error events (such as failure of ICE candidate gathering).

enum RTCIceGatheringState

new

No networking has occurred yet.

gathering

The ICE engine is in the process of gathering candidates.

complete

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

Interface Definition

readonly attribute RTCIceCandidate? candidate

The candidate attribute is the RTCIceCandidate object with the new local ICE candidate that caused the event. If candidate is null, there are no additional candidates for now.

Interface Definition

readonly attribute RTCIceTransportState state

The state attribute contains the new RTCIceTransportState causing the event.

Interface Definition

readonly attribute RTCIceGatherState state

The state attribute contains the new RTCIceGatheringState that caused the event.

Interface Definition

readonly attribute DOMError e

The DOMError object whose name attribute has the value TODO.

The RTCIceParameters Object

The RTCIceParameters object includes the ICE username and password.

DOMString usernameFragment

ICE username.

DOMString password

ICE password.

Examples

// Assume we already have a way to signal. This is an example
// of  how to offer ICE and DTLS parameters and ICE candidates and
// get back ICE and DTLS parameters and ICE candidates, and start
// both ICE and DTLS.

function initiate(signaller) {
 var iceOptions = ...;
 var ice = new RTCIceTransport(RTCIceRole.controlling, iceOptions);
 var dtls = new RTCDtlsTransport(ice);
 // ... get tracks and RTP objects from other example

 signaller.sendInitiate({
   "ice": ice.
getLocalParameters(),
   "dtls": dtls.
getLocalParameters(),
   // ... include RTP info from other example
 }, function(remote) {
   ice.setRemoteParameters(remote.ice);
   dtls.start(remote.dtls);
   // ... start RTP senders and receivers from other example
 });

 ice.oncandidate = function(candidate) {
   signaller.sendLocalCandidate(candidate);
 }

 signaller.onRemoteCandidate = function(candidate) {
   ice.addRemoteCandidate(candidate);
 }

 ice.start();
}

    

// Assume we already have a way to signal and remote info is 
// signalled to us.  This is an example of how to answer with ICE and DTLS
// and DTLS parameters and ICE candidates and start both ICE and DTLS.
//
function accept(signaller, remote) {
 var iceOptions = ...;
 var ice = new RTCIceTransport(RTCIceRole.controlled,iceOptions);
 var dtls = new RTCDtlsTransport(ice);
 // ... get tracks and RTP objects from other example
 ice.onlocalcandidate = function(candidate) {
   signaller.sendLocalCandidate(candidate);
 }

 signaller.onRemoteCandidate = function(candidate) {
   ice.addRemoteCandidate(candidate);
 }

 signaller.sendAccept({
   "ice": ice.
getLocalParameters(),
   "dtls": ice.
getLocalParameters()
   // ... include RTP info from other example
 });

 ice.start(remote.ice);
 dtls.start(remote.dtls);

 // ... start RTP senders and receivers from other example
}

    

enum RTCIceRole

controlling

controlling state

controlled

controlled state

enum RTCIceGatherPolicy

all

Gather all ICE candidate types.

nohost

Gather all ICE candidate types except for host candidates.

relayonly

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

enum RTCIceTransportState

new

new state

checking

checking state

connected

connected state

completed

completed state

disconnected

disconnected state

closed

closed state

The non-normative ICE state transitions are:

The RTCIceOptions Object

The RTCIceOptions object includes information relating to ICE configuration.

sequence<RTCIceServer>? iceServers

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

The RTCIceServer Object

The RTCIceServer is used to provide STUN or TURN server configuration. 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.

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

(DOMString or sequence<DOMString>) urls

STUN or TURN URI(s) as defined in [[!STUN-URI]] and [[!TURN-URI]]

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 the uri element is a TURN URI, then this is the credential to use with that TURN server.

The RTCIceCandidate Object

The RTCIceCandidate object includes information relating to an ICE candidate.

{
  foundation: "abcd1234",
  priority: 1694498815,
  ip: "192.0.2.33",
  protocol: "udp",
  port: 10000,
  type: "host"
};
    

DOMString foundation

A unique identifier that allows ICE to correlate candidates that appear on multiple RTCIceTransports.

unsigned long priority

The assigned priority of the candidate. This is automatically populated by the browser.

DOMString ip

The IP address of the candidate.

RTCIceProtocol protocol

The protocol of the candidate (UDP/TCP).

unsigned short port

The port for the candidate.

RTCIceCandidateType type

The type of candidate.

RTCIceTcpCandidateType? tcpType=null

The type of TCP candidate.

DOMString? relatedAddress=""

For candidates that are derived from others, such as relay or reflexive candidates, the relatedAddress refers to the host candidate that these are derived from. For host candidates, the relatedAddress is set to the empty string.

unsigned short? relatedPort=null

For candidates that are derived from others, such as relay or reflexive candidates, the relatedPort refers to the host candidate that these are derived from. For host candidates, the relatedPort is null.

Overview

An RTCIceListener instance is associated to an RTCIceTransport.

Operation

An RTCIceListener instance is optionally constructed from an RTCIceOptions object, or an RTCIceListener is automatically constructed.

Interface Definition

attribute RTCIceOptions options

The RTCIceOptions instance.

Example

var iceOptions = ...;
var iceListener = new RTCIceListener(iceOptions);
var iceBase = new RTCIceTransport(RTCIceRole.controlling,iceOptions);
sendInitiate(iceBase.getLocalParameters(), function(response) {
  // We may get N responses
  var ice = new RTCIceTransport(RTCIceRole.controlling, iceListener);
  var ice.setRemoteParameters(response.iceParameters);
  ice.start();
  // ... setup DTLS, RTP, SCTP, etc.
});

iceBase.onlocalcandidate = sendLocalCandidate;
iceListener.start();

    

Overview

An RTCRtpSender instance is associated to a sending MediaStreamTrack and provides RTC related methods to it.

Operation

A RTCRtpSender instance is constructed from an MediaStreamTrack object and associated to an RTCDtlsTransport.

Interface Definition

attribute MediaStreamTrack track

The associated MediaStreamTrack instance.

attribute RTCDtlsTransport transport

The associated RTCDtlsTransport instance.

static RTCRtpCapabilities getCapabilities()

Obtain the capabilities of the RTCRtpSender.

static RTCRtpParameters createParameters(MediaStreamTrack track, optional RTCRtpCapabilities capabilities)

Create parameters based on the MediaStreamTrack and the capabilities specified in RTCRtpCapabilities.

static RTCRtpParameters filterParameters(RTCRtpParameters parameters, optional RTCRtpCapabilities capabilities)

Filter parameters based on the RTCRtpCapabilities.

void send(RTCRtpParameters parameters)

Media is controlled by the given "parameters". The sender starts sending when send() is called and stops sending when stop() is called.

void stop()

Stops sending the track on the wire. Stop is final like MediaStreamTrack

Example

Overview

An RTCRtpReceiver instance is associated to a receiving MediaStreamTrack and provides RTC related methods to it.

Operation

A RTCRtpReceiver instance is constructed from an RTCDtlsTransport object.

Interface Definition

readonly attribute MediaStreamTrack? track

The associated MediaStreamTrack instance.

attribute RTCDtlsTransport transport

The associated RTCDtlsTransport instance.

static RTCRtpCapabilities getCapabilities()

Obtain the capabilities of the RTCRtpReceiver.

static RTCRtpParameters createParameters (DOMString kind, optional RTCRtpCapabilities capabilities)

Create parameters based on the kind and the capabilities specified in RTCRtpCapabilities.

DOMString kind

Specifies kind, either "audio" or "video".

optional RTCRtpCapabilities capabilities

static RTCRtpParameters filterParameters(RTCRtpParameters parameters, optional RTCRtpCapabilities capabilities)

Filter parameters based on the RTCRtpCapabilities.

void receive(RTCRtpParameters parameters)

Media is controlled by the given "parameters". The receiver starts receiving when the receive() is called and stopped when the stop() is called.

void stop()

Stops receiving the track on the wire. Stop is final like MediaStreamTrack

Examples

// Assume we already have a way to signal, a transport 
// (RTCDtlsTransport), and audio and video tracks. This is an example 
// of  how to offer them  and get back an answer with audio and 
// video tracks, and begin sending and receiving them.
function initiate(signaller, transport, audioTrack, videoTrack) {
  var audioSender = new RTCRtpSender(audioTrack, transport);
  var videoSender = new RTCRtpSender(videoTrack, transport);
  var audioReceiver = new RTCRtpReceiver(transport);
  var videoReceiver = new RTCRtpReceiver(transport);

  var sendAudioParams = RTCRtpSender.createParameters(audioTrack);
  var sendVideoParams = RTCRtpSender.createParameters(videoTrack);
  signaller.offerTracks({
    // The initiator offers parameters it wants to send with, 
    // and the capabilities it has for receiving. 
    "rtpCaps": RTCRtpReceiver.getCapabilities(),
    "audio": sendAudioParams,
    "video": sendVideoParams
  }, function(answer) {
    // The responder answers with parameters it wants to send with
    // and the capabilities it has for receiving. 
    var audioSendParams = RTCRtpSender.filterParameters(
       sendAudioParams, answer.rtpCaps);
    var videoSendParams = RTCRtpSender.filterParameters(
       sendVideoParams, answer.rtpCaps);
    var audioRecvParams = RTCRtpReceiver.filterParameters(
       answer.audio);
    var videoRecvParams = RTCRtpReceiver.filterParameters(
       answer.video);
      
    audioSender.send(audioSendParams);
    videoSender.send(videoSendParams)
    audioReceiver.receive(audioRecvParams);
    videoReceiver.receive(videoRecvParams);

    // Now we can render/play 
    // audioReceiver.track and videoReceiver.track.
  });
}
    

// Assume we already have a way to signal, a transport 
// (RTCDtlsTransport), and audio and video tracks. This is an example 
// of how to answer an offer with audio and video tracks, and begin 
// sending and receiving them.
function accept(
  signaller, remote, transport, audioTrack, videoTrack) {
  var audioSender = new RTCRtpSender(audioTrack, transport);
  var videoSender = new RTCRtpSender(videoTrack, transport);
  var audioReceiver = new RTCRtpReceiver(transport);
  var videoReceiver = new RTCRtpReceiver(transport);

  var audioSendParams = RTCRtpSender.createParameters(
    audioTrack, remote.rtpCaps);
  var videoSendParams = RTCRtpSender.createParameters(
    videoTrack, remote.rtpCaps);
  var audioRecvParams = RTCRtpReceiver.filterParameters(
     remote.audio);
  var videoRecvParams = RTCRtpReceiver.filterParameters(
     remote.video);
  
  audioSender.send(audioSendParams);
  videoSender.send(videoSendParams)
  audioReceiver.receive(audioRecvParams);
  videoReceiver.receive(videoRecvParams);
 
  signaller.answerTracks({
    "rtpCaps": RTCRtpReceiver.getCapabilities(),
    "audio": audioSendParams,
    "video": videoSendParams
  });

  // Now we can render/play 
  // audioReceiver.track and videoReceiver.track.
}
    

Overview

An RTCRtpListener instance is associated to an RTCDtlsTransport.

Operation

An RTCRtpListener instance is constructed from an RTCDtlsTransport object.

To determine whether an RTP stream is configured to be processed by an existing RTCRtpReceiver object, the RTCRtpListener attempts to match the values of an incoming RTP packet's Payload Type and SSRC fields as well as the value of its receiverId RTP extension (if present) against the RTCRtpReceiver.RTCRtpParameters.RTCRtpCodecParameters.payLoadType, RTCRtpReceiver.RTCRtpParameters.RTCRtpEncodingParameters.ssrc, and RTCRtpReceiver.RTCRtpParameters.receiverId attributes of configured RTCRtpReceiver objects.

TODO: provide details of matching behavior, along with examples.

Interface Definition

readonly attribute RTCDtlsTransport transport

The RTCDtlsTransport instance.

attribute EventHandler? onunhandledrtp

The event handler which handles the RTCRtpUnhandledRtpEvent.

Interface Definition

readonly attribute unsigned int ssrc

The SSRC in the RTP packet triggering the event.

readonly attribute unsigned byte payloadType

The Payload Type value in the RTP packet triggering the event.

readonly attribute DOMString? receiverId

The value of the AppId header extension in the RTP packet triggering the event, if present.

Example

dictionary RTCRtpCapabilities

sequence<RTCRtpCodec> audioCodecs

Supported audio codecs.

sequence<RTCRtpCodec> videoCodecs

Supported video codecs.

sequence<DOMString> headerExtensions

URIs of supported RTP header extensions.

Capabilities features

Features supported by the RTP engine.

Capabilities rtcpFeedback

Supported RTCP capabilities, such as "nack" from [[!RFC4585]].

dictionary RTCRtpCodec

DOMString name=""

The MIME media type, if set, empty string otherwise.

unsigned int? clockRate=null

Codec clockrate, null if unset.

unsigned int? numChannels=1

The number of channels supported (e.g. stereo); one by default.

Capabilities formats

Codec-specific capabilities available for signaling.

dictionary RTCRtpParameters

DOMString? receiverId=""

The receiverId assigned to the RTP stream, if any, empty string otherwise. In an RTCRtpReceiver object, this corresponds to recv-appId defined in [[!APPID]]. In an RTCRtpSender object, it corresponds to the appId. This is a stable identifier that can be defined and assign to any RTP stream rather than relying on an SSRC. An SSRC is randomly generated and can change arbitrarily due to conflicts with other SSRCs, whereas the receiverId has a value whose meaning can be defined in advance between RTP sender and receiver, assisting in RTP demultiplexing.

sequence<RTCRtpCodecParameters> codecs

The codecs to send or receive (could include RTX and CN as well).

sequence<RTCRtpHeaderExtensionParameters> headerExtensions

The RTP header extensions to send or receive.

sequence<RTCRtpEncodingParameters> encodings

The "encodings" or "layers" to be used for things like simulcast, Scalable Video Coding, RTX, FEC, etc.

dictionary RTCRtpCodecParameters

unsigned byte payloadType=null

The value that goes in the RTP Payload Type Field [[!RFC3550]], null if unset.

RTCRtpCodec codec

The codec to be used for sending or receiving.

Settings formats

Codec settings that control what is sent or received. For example, with Opus [[!RFC6716]], stereo=1.

Settings rtcpFeedback

RTCP feedback settings, separated out because they are so different.

dictionary RTCRtpEncodingParameters

unsigned int? ssrc=null

The SSRC for this layering/encoding, null if unset.

DOMString? codecName=""

For per-encoding codec specifications, give the codec name here. If the empty string, the browser will choose.

RTCRtpFecParameters? fec

Specifies the FEC mechanism if used.

RTCRtpRtxParameters? rtx

Specifies the RTX mechanism if used.

double priority=1.0

The higher the value, the more the bits will be given to each as available bandwidth goes up. Default is 1.0.

double maxBitrate=null

Ramp up resolution/quality/framerate until this bitrate, null if unset. Summed when using dependent layers.

double minQuality=null

Never send less than this quality, null if unset. 1.0 = maximum attainable quality.

double frameratebias=0.5

What to give more bits to, if available, null if unset. 0.0 = strongly favor resolution or 1.0 = strongly favor framerate. 0.5 = neither (default).

double scale=null

Do this scale of the input resolution, or die trying. 1.0 = full resolution. Default is unconstrained (null).

boolean active=true

Whether the sender or receiver is active. If false, don't send any media right now. Disable is different than omitting the encoding; it can keep resources available to re-enable more quickly than re-adding. Plus, it still sends RTCP. Default is active.

DOMString? encodingId

An identifier for the encoding object. This identifier should be unique within the scope of the localized sequence of RTCRtpEncodingParameters for any given RTCRtpParameters object. If encodings contained within sequences of other RTCRtpParameters objects are dependent upon this encoding identifier, the identifier should be globally unique (unless two or more encodings are intentionally referencing the same dependency RTCRtpEncodingParameters such as described in [[!RFC5583]] Section 6.5a).

sequence<DOMString> dependencyEncodingIds

Just the IDs (resolve to encodingIds within the same sequence first, then search globally for matches).

Examples

//Send a thumbnail along with regular size
var encodings1 = [  ssrc: 1,  priority: 1.0 }] 

// Control the resolution and framerate with a different track and RtpSender. 
var encodings2 = [{ ssrc: 2,  
// Prioritize the thumbnail over the main video.  
priority: 10.0 }];

// Sign Language (need high framerate, but don't get too bad quality)
var encodings = [{ minQuality: 0.2,  framerateBias: 1.0 }]; 

// Screencast (High quality, framerate can be low)
var encodings = [{ framerateBias: 0.0 }]; 

//Remote Desktop (High framerate, must not dowscale) 
var encodings = [{ framerateBias: 1.0 }];

// Audio more important than video
var audioEncodings = [{ priority: 10.0 }]; 
var videoEncodings = [{ priority: 0.1 }]; 

//Video more important than audio
var audioEncodings = [{ priority: 0.1 }]; 
var videoEncodings = [{ priority: 10.0 }];

//Crank up the quality
var encodings = [{ maxBitrate: 10000000 }]; 

//Keep the bandwidth low
var encodings = [{ maxBitrate: 100000 }]; 

Example of 3-layer encoding with spatial scalability
var encodings =[{
  layerId: "0",
  scale: 0.25
}, {
  layerId: "1",
  layerDependencies: ["0"]
  scale: 0.5
}, {
  layerId: "2",
  layerDependencies: ["0", "1"]
  scale: 1.0
}]

Example of 3-layer encoding with spatial scalability and all but bottom layer disabled
var encodings1 =[{
  layerId: "0",
  scale: 0.25
}, {
  layerId: "1",
  layerDependencies: ["0"],
  scale: 0.5,
  active: false
}, {
  layerId: "2",
  layerDependencies: ["0", "1"],
  scale: 1.0,
  active: false
}];

Example of 3-layer spatial simulcast
var encodings =[{
  layerId: "0",
  scale: 0.25
}, {
  layerId: "1",
  scale: 0.5
}, {
  layerId: "2",
  scale: 1.0
}]

Example of 3-layer spatial simulcast with all but bottom layer disabled
var encodings1 =[{
  layerId: "0",
  scale: 0.25
}, {
  layerId: "1",
  scale: 0.5,
  active: false
}, {
  layerId: "2",
  scale: 1.0,
  active: false
}];

dictionary RTCRtpFecParameters

unsigned int ssrc=null

The SSRC to use for FEC, null if unset.

DOMString mechanism=""

The Forward Error Correction (FEC) mechanism to use, if any, empty string otherwise.

dictionary RTCRtpRtxParameters

unsigned int ssrc=null

The SSRC to use for RTX, null if unset.

dictionary RTCRtpHeaderExtensionParameters

DOMString uri=""

The URI of the RTP header extension, if any, as defined in [[!RFC5285]], empty string otherwise.

unsigned short id=null

The value that goes in the packet, null if unset.

boolean encrypt=false

If true, the value in the header is encrypted as per [[!RFC6904]]. Default is unencrypted.

Properties

Capabilities

Capabilities are a dictionary containing one or more key-value pairs, where each key must be a property defined in the registry, and each value must be a subset of the set of values defined for that property in the registry. The exact syntax of the value expression depends on the type of the property but is of type ConstraintValues. The Capabilities dictionary specifies the subset of the properties and values from the registry that the UA supports. Note that a UA may support only a subset of the properties that are defined in the registry, and may support a subset of the set values for those properties that it does support. Note that Capabilities are returned from the UA to the application, and cannot be specified by the application. However, the application can set the Parameters. An example of a Capabilities dictionary is shown below. This example is not very realistic in that a browser would actually be required to support more settings that just these.

Settings

A Settings is a dictionary containing one or more key-value pairs. It must contain each key returned in Capabilities. There must be a single value for each key and the value must a member of the set defined for that property by Capabilities. The exact syntax of the value expression depends on the type of the property. It will be a DOMString[] for properties of type MultiPropertyValueSet. It will be a DOMString[] for properties of type PropertyValueSet, it will be a long for properties of type PropertyValueLongRange , it will be a double for properties of type PropertyValueDoubleRange. Thus the Settings dictionary contains the actual values that the UA has chosen for the object's Capabilities. An example of a Settings dictionary is shown below. This example is not very realistic in that a browser would actually be required to support more settings that just these.

Overview

An RTCDtmfSender instance allows sending DTMF tones to/from the remote peer, as per [[!RFC4733]].

Operation

An RTCDtmfSender object is constructed from an RTCRtpSender object.

Interface Definition

readonly attribute boolean canInsertDTMF

Whether the RTCDtmfSender is capable of sending DTMF.

void insertDTMF(in DOMString tones, optional long duration, long interToneGap)

readonly attribute RTCRtpSender sender

The RTCRtpSender instance

attribute EventHandler ontonechange

The ontonechange event handler uses the RTCDTMFToneChangeEvent interface to return the character for each tone as it is played out.

readonly attribute DOMString toneBuffer

The toneBuffer attribute returns a list of the tones remaining to be played out.

readonly attribute long duration

The duration attribute returns the current tone duration value in milliseconds. 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 duration.

readonly attribute long interToneGap

The interToneGap attribute returns 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 an 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=""

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

Overview

An RTCDataChannel class instance allows sending data messages to/from the remote peer.

Operation

An RTCDataChannel object is constructed from an RTCDataTransport object and an RTCDataChannelParameters object.

Interface Definition

The RTCDataChannel interface represents a bi-directional data channel between two peers. There are two ways to establish a connection with RTCDataChannel. The first way is to construct an RTCDataChannel at one of the peers with the RTCDataChannelParameters.negotiated attribute unset or set to its default value false. This will announce the new channel in-band and trigger an ondatachannel event with the corresponding RTCDataChannel object at the other peer. The second way is to let the application negotiate the RTCDataChannel. To do this, create an RTCDataChannel object with the RTCDataChannelParameters.negotiated 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 RTCDataChannelParameters.negotiated 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.

readonly attribute RTCDataTransport transport

The readonly attribute referring to the related transport object.

readonly attribute RTCDataChannelParameters parameters

The parameters applying to this data channel.

readonly attribute RTCDataChannelState readyState

The 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 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 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 an RTCDataChannel object is constructed, 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 close()

Closes the RTCDataChannel. It may be called regardless of whether the RTCDataChannel object was created by this peer or the remote peer. When the close() method is called, the user agent must run the following steps:

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

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

3. Set channel's readyState attribute to closing.

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

attribute EventHandler onopen

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

attribute EventHandler onerror

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

attribute EventHandler onclose

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

attribute EventHandler onmessage

This event handler, of event handler event type message, must be fired to allow a developer's JavaScript to receive data from a remote peer.

Event Argument	Description
Object data	The received remote data.

Promise send (DOMString data)

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

Promise send (Blob data)

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

Promise send (ArrayBuffer data)

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

Promise send (ArrayBufferView data)

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

Interface Definition

enum RTCDataChannelState

connecting

The user agent is attempting to establish the underlying data transport. This is the initial state of an RTCDataChannel object.

open

The underlying data transport is established and communication is possible. This is the initial state of an RTCDataChannel object dispatched as a part of an 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.

dictionary RTCDataChannelParameters

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

DOMString? label=""

The label attribute represents a label that can be used to distinguish this RTCDataChannel object from other RTCDataChannel objects. The attribute must return the value to which it was set when the RTCDataChannel object was constructed. For an SCTP data channel, the label is carried in the DATA_CHANNEL_OPEN message defined in [[!DATA-PROT]] Section 5.1.

boolean ordered=true

The ordered attribute returns true if the RTCDataChannel is ordered, and false if out of order delivery is allowed. Default is true. The attribute must return the value to which it was set when the RTCDataChannel was constructed.

unsigned short? maxPacketLifetime=null

The maxPacketLifetime attribute represents the length of the time window (in milliseconds) during which retransmissions may occur in unreliable mode, or null if unset. The attribute must return the value to which it was set when the RTCDataChannel was constructed.

unsigned short? maxRetransmits=null

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

DOMString? protocol=""

The name of the sub-protocol used with this RTCDataChannel if any, or the empty string otherwise (in which case the protocol is unspecified). The attribute must return the value to which it was set when the RTCDataChannel was constucted. Sub-protocols are registered in the 'Websocket Subprotocol Name Registry' created in [[!RFC6455]] Section 11.5.

boolean negotiated=false

The 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 constructed. If set to true, the application developer must signal to the remote peer to construct an RTCDataChannel object with the same id for the data channel to be open. If set to false, the remote party will receive an ondatachannel event with a system constructed RTCDataChannel object.

unsigned short? id=null

The id attribute returns the id for this RTCDataChannel, or null if unset. The id was either assigned by the user agent at channel creation time or was selected by the script. For SCTP, the id represents a stream identifier, as discussed in [[!DATA]] Section 6.5. The attribute must return the value to which it was set when the RTCDataChannel was constructed.

Overview

An RTCSctpTransport inherits from an RTCDataTransport object, which is associated to an RTCDataChannel object.

Operation

An RTCSctpTransport is constructed from an RTCDtlsTransport object.

Interface Definition

attribute RTCDtlsTransport transport

The RTCDtlsTransport instance the RTCSctpTransport object is sending over.

static RTCSctpCapabilities getCapabilities()

Retrieves the RTCSctpCapabilities of the RTCSctpTransport instance.

void start(RTCSctpCapabilities remoteCaps)

void stop()

Stops the RTCSctpTransport instance.

attribute EventHandler ondatachannel

If the remote peers sets RTCDataChannelParameters.negotiated to false, then the ondatachannel event will fire indicating a new RTCDataChannel object has been constructed to connect with the RTCDataChannel constructed by the remote peer. This event handler, of type datachannel, must be supported by all objects implementing the RTCSctpTransport interface.

Example

function initiate(signaller) {
  var dtls = ...;  // See ICE/DTLS example.
  var sctp = new RTCSctpTransport(dtls);

  signaller.sendInitiate({
    // ... include ICE/DTLS info from other example.
  sctpCapabilities: RTCSctpTransport.getCapabilities()
  }, function(remote) {
    sctp.start(remote.sctpCapabilities);
  });

  var channel = sctp.createDataChannel({...});
  channel.send("foo");
}

function accept(signaller, remote) {
  var dtls = ...;  // See ICE/DTLS example.
  signaller.sendAccept({
    // ... include ICE/DTLS info from other example.
    "sctpCapabilities": RTCSctpTransport.getCapabilities()
  });

  var sctp = new RTCSctpTransport(dtls);
  sctp.start(remote.sctpCapabilties);

  // Assume in-band signalling.  We could also easily add
  // RTCDataChannelParameters into the out-of-band signalling
  // And call .createDataChannel here with negotiated: true.

  sctp.ondatachannel = function(channel) {
    channel.onmessage = function(message) {
    if (message == "foo") {
      channel.send("bar");
    }
  }
}

RTCStatsCallback

RTCStatsReport report

A RTCStatsReport representing the gathered stats.

RTCStatsReport Object

The getStats() method delivers a successful result in the form of a RTCStatsReport object. A RTCStatsReport object represents a map between strings, identifying the inspected objects (RTCStats.id), and their corresponding RTCStats objects.

An RTCStatsReport may be composed of several RTCStats objects, each reporting stats for one underlying object. One achieves the total for the object by summing over all stats of a certain type; for instance, if an RTCRtpSender object is sending RTP streams involving multiple SSRCs over the network, the RTCStatsReport may contain one RTCStats object per SSRC (which can be distinguished by the value of the "ssrc" stats attribute).

getter RTCStats (DOMString id)

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

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

RTCStats Dictionary

An RTCStats dictionary represents the stats gathered by inspecting a specific object. 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 a RTCStats object.

DOMHiResTimeStamp timestamp

The timestamp, of type DOMHiResTimeStamp [[!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.

inbound-rtp

Inbound RTP. Relevant to RTCRtpReceiver objects.

outbound-rtp

Outbund RTP. Relevant to RTCRtpSender objects.

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

Relevant to RTCRtpReceiver objects.

unsigned long bytesReceived

Relevant to RTCRtpReceiver objects.

unsigned long packetsSent

Relevant to RTCRtpSender objects.

unsigned long bytesSent

Relevant to RTCRtpSender objects.

Other interfaces

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:

Simple Peer-to-peer Example

This example code provides a basic audio and video session between two browsers.

Changes since 12 April 2014

1. Fixes for error handling, as described in Issue 26
2. Support for contributing sources removed (re-classified as a 1.2 feature), as described in Issue 27
3. Cleanup of DataChannel construction, as described in Issue 60
4. Separate proposal on simulcast/layering, as described in Issue 61
5. Separate proposal on quality, as described in Issue 62
6. Fix for TCP candidate type, as described in Issue 63
7. Fix to the fingerprint attribute, as described in Issue 64
8. Fix to RTCRtpFeatures, as described in Issue 65
9. Support for retrieval of remote certificates, as described in Issue 67
10. Support for ICE error handling, described in Issue 68
11. Support for Data Channel send rate control, as described in Issue 69
12. Support for capabilities and settings, as described in Issue 70
13. Removal of duplicate RTCRtpListener functionality, as described in Issue 71
14. ICE gathering state added, as described in Issue 72
15. Removed ICE role from the ICE transport constructor, as described in Issue 73

Changes since 13 February 2014

1. Support for contributing source information added, as described in Issue 27
2. Support for control of quality, resolution, framerate and layering added, as described in Issue 31
3. RTCRtpListener object added and figure in Section 1 updated, as described in Issue 32
4. More complete support for RTP and Codec Parameters added, as described in Issue 33
5. Data Channel transport problem fixed, as described in Issue 34
6. Various NITs fixed, as described in Issue 37
7. Section 2.2 and 2.3 issues fixed, as described in Issue 38
8. Default values of some dictionary attributes added, to partially address the issue described in Issue 39
9. Support for ICE TCP added, as described in Issue 41
10. Fixed issue with sequences as attributes, as described in Issue 43
11. Fix for issues with onlocalcandidate, as described in Issue 44
12. Initial stab at a Stats API, as requested in Issue 46
13. Added support for ICE gather policy, as described in Issue 47

Changes since 07 November 2013

1. RTCTrack split into RTCRtpSender and RTCRtpReceiver objects, as proposed on 06 January 2014.
2. RTCConnection split into RTCIceTransport and RTCDtlsTransport objects, as proposed on 09 January 2014.
3. RTCSctpTransport object added, as described in Issue 25
4. RTCRtpHeaderExtensionParameters added, as described in Issue 28
5. RTCIceListener added, in order to support parallel forking, as described in Issue 29
6. DTMF support added, as described in Issue 30