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 and MediaStreamTrack are defined in [[!GETUSERMEDIA]].

For Scalable Video Coding (SVC), the terms single-session transmission (SST) and multi-session transmission (MST) are defined in [[RFC6190]]. This specification only supports SST but not MST. The term Single Real-time transport protocol stream Single Transport (SRST), defined in [[RFC7656]] Section 3.7, refers to an SVC implementation that transmits all layers within a single transport, using a single Real-time Transport Protocol (RTP) stream and synchronization source (SSRC). The term Multiple RTP stream Single Transport (MRST), also defined in [[RFC7656]] Section 3.7, refers to an implementation that transmits all layers within a single transport, using multiple RTP streams with a distinct SSRC for each layer.

Overview

The Microsoft Edge implementation of the RTCIceGatherer does not support the component or state attributes, nor does it support the close() method or the ongatherstatechange event handler.

As noted in [[!RFC5245]] Section 7.1.2.2, an incoming connectivity check contains an ICE-CONTROLLING or ICE-CONTROLLED attribute, depending on the role of the ICE agent initiating the check. Since an RTCIceGatherer object does not have a role, it cannot determine whether to respond to an incoming connectivity check with a 487 (Role Conflict) error; however, it can validate that an incoming connectivity check utilizes the correct local username fragment and password, and if not, can respond with an 401 (Unauthorized) error, as described in [[!RFC5389]] Section 10.1.2.

For incoming connectivity checks that pass validation, the RTCIceGatherer MUST buffer incoming connectivity checks so as to be able to provide them to associated RTCIceTransport objects so that they can respond.

Operation

An RTCIceGatherer instance is constructed from an RTCIceGatherOptions object and an optional MSRTCConfConfig object. . If RTCIceGatherOptions.portRange is invalid (e.g. portRange.max < portRange.min), throw an InvalidParameters exception.

Interface Definition

readonly attribute RTCIceComponent component

The component-id of the RTCIceGatherer.

RTCIceParameters getLocalParameters()

Obtain the ICE parameters of the RTCIceGatherer.

sequence<RTCIceCandidate> getLocalCandidates()

Retrieve the sequence of valid local candidates associated with the RTCIceGatherer. This retrieves all unpruned local candidates currently known (except for peer reflexive candidates), even if an onlocalcandidate event hasn't been processed yet. In Microsoft Edge, if getLocalCandidates() is called prior to emitting of the first candidate, an exception is thrown.

RTCIceGatherer createAssociatedGatherer()

Create an associated RTCIceGatherer for RTCP, with the same RTCIceParameters and RTCIceGatherOptions. If an RTCIceGatherer calls the method more than once, or if component is "RTCP", throw an InvalidStateError exception.

attribute EventHandler? onerror

This event handler, of event handler type error, MUST be supported by all objects implementing the RTCIceGatherer interface. If TURN credentials are invalid, or a port cannot be allocated for a local ICE candidate, then this event MUST be fired.

attribute EventHandler? onlocalcandidate

This event handler, of event handler event type icecandidate, uses the RTCIceGathererEvent interface. It MUST be supported by all objects implementing the RTCIceGatherer interface. It receives events when a new local ICE candidate is available. Since ICE candidate gathering begins once an RTCIceGatherer object is created, candidate events are queued until an onlocalcandidate event handler is assigned. When the final candidate is gathered, a candidate event occurs with an RTCIceCandidateComplete emitted.

RTCIceParameters Dictionary

The RTCIceParameters dictionary includes the ICE username fragment and password, as well as an indication of whether ICE lite is supported.

DOMString usernameFragment

ICE username.

DOMString password

ICE password.

boolean? iceLite

Whether ICE lite is supported (true) or not (false). If unset, ICE lite is not supported. Since browsers support full ICE, getLocalParameters().iceLite MUST NOT be set. This attribute is only set in remote parameters signaled by a remote peer (such as a gateway) that only supports ICE lite.

RTCIceCandidate Dictionary

The RTCIceCandidate dictiontary 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.

DOMString interfaceType

The interface type for the candidate. Types include "lan", "wlan", "wwan" and "vpn". Not supported in Microsoft Edge.

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

DOMString msMTurnSessionId

The assigned MTURN session identifier of the candidate. This is only set when an MSTURN URI is provided in the RTCIceServer object.

RTCIceCandidateComplete Dictionary

The RTCIceCandidateComplete dictionary signifies that all RTCIceCandidates are gathered.

RTCIceGathererEvent

The icecandidate event of the RTCIceGatherer object uses the RTCIceGathererEvent interface.

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

readonly attribute RTCIceGatherCandidate candidate

The candidate attribute is the RTCIceGatherCandidate object with the new ICE candidate that caused the event. If candidate is of type RTCIceCandidateComplete, there are no additional candidates.

RTCIceGatherCandidate candidate

The ICE candidate that caused the event.

RTCIceGatherOptions Dictionary

RTCIceGatherOptions provides options relating to the gathering of ICE candidates.

RTCIceGatherPolicy gatherPolicy

The ICE gather policy.

sequence<RTCIceServer> iceservers

The ICE servers to be configured.

MSPortRange portRange

The port range to use for local candidates

MSPortRange Dictionary

unsigned short min

Beginning of the port range.

unsigned short max

End of the port range.

RTCIceGatherPolicy Enum

The RTCIceGatherPolicy dictoinary provides the policy relating to the gathering of ICE candidates.

all

The ICE gatherer gathers all types of candidates when this value is specified.

nohost

The ICE gatherer gathers all ICE candidate types except for host candidates.

relay

The ICE gatherer MUST 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.

RTCIceServer Dictionary

The RTCIceServer dictionary provides 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"} 
      ]
   

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

Example

// Include some helper functions
import "helper.js";
// Create ICE gather options
var gatherOptions = new RTCIceGatherOptions();
gatherOptions.gatherPolicy = RTCIceGatherPolicy.relay;
gatherOptions.iceservers = [ { urls: "stun:stun1.example.net" } , 
  { urls:"turn:turn.example.org", username: "user", credential:"myPassword"} ];
// Create ICE gatherer objects
var iceGatherer = new RTCIceGatherer(gatherOptions);
// Prepare to signal local candidates as well as "end of candidates"
iceGatherer.onlocalcandidate = function (event) {
  mySendLocalCandidate(event.candidate);
}; 
// Set up response function
mySignaller.onResponse = function(responseSignaller,response) {
  // The Microsoft Edge ORTC implementation only supports a single response. 
};

mySignaller.send({
   "ice": iceGatherer.getLocalParameters()
});

// Helper functions used in all the examples (helper.js)
function trace(text) {
  // This function is used for logging.
  if (text[text.length - 1] === '\n') {
    text = text.substring(0, text.length - 1);
  }
  if (window.performance) {
    var now = (window.performance.now() / 1000).toFixed(3);
    console.log(now + ': ' + text);
  } else {
    console.log(text);
  }
}

function errorHandler (error) {
  trace('Error encountered: ' + error.name);
}

function mySendLocalCandidate(candidate, component, kind){
  // Set default values
  kind = kind || "all";
  component = component || RTCIceComponent.RTP;
  parameters = parameters || null; 
  // Signal the local candidate 
  mySignaller.mySendLocalCandidate({
  "candidate": candidate,
  "component": component,
  "kind": kind
  });
}

function myIceTransportStateChange(name, state){
  switch(state){
  case RTCIceTransportState.new:
     trace('IceTransport: ' + name + ' Has been created');
     break;
  case RTCIceTransportState.checking:
     trace('IceTransport: ' + name + ' Is checking');
     break;
  case RTCIceTransportState.connected:
     trace('IceTransport: ' + name + ' Is connected');
     break;
  case RTCIceTransportState.disconnected:
     trace('IceTransport: ' + name + ' Is disconnected');
     break;
  case RTCIceTransportState.completed:
     trace('IceTransport: ' + name + ' Has finished checking (for now)');
     break;
  case RTCIceTransportState.closed:
     trace('IceTransport: ' + name + ' Is closed');
     break;
  default:
     trace('IceTransport: ' + name + ' Invalid state');
  }
}

function myDtlsTransportStateChange(name, state){
  switch(state){
  case RTCDtlsTransportState.new:
     trace('DtlsTransport: ' + name + ' Has been created');
     break;
  case RTCDtlsTransportState.connecting:
     trace('DtlsTransport: ' + name + ' Is connecting');
     break;
  case RTCDtlsTransportState.connected:
     trace('DtlsTransport: ' + name + ' Is connected');
     break;
  case RTCDtlsTransportState.closed:
     trace('DtlsTransport: ' + name + ' Is closed');
     break;
  default:
     trace('DtlsTransport: ' + name + ' Invalid state');
  }
}
 

Overview

An RTCIceTransport instance is associated to a transport object (such as RTCDtlsTransport), and provides RTC related methods to it. The Microsoft Edge implementation does not support the oncandidatepairchange event handler.

Operation

An RTCIceTransport instance is constructed from an optional RTCIceGatherer object.

Interface Definition

readonly attribute RTCIceGatherer? iceGatherer

The iceGatherer attribute is set to the value of gatherer passed in the constructor or the latest call to start().

readonly attribute RTCIceRole role

The current role of the ICE transport.

readonly attribute RTCIceComponent component

The component-id of the RTCIceTransport.

readonly attribute RTCIceTransportState state

The current state of the ICE transport.

sequence<RTCIceCandidate> getRemoteCandidates()

Retrieve the sequence of candidates associated with the remote RTCIceTransport. Only returns the candidates previously added using setRemoteCandidates() or addRemoteCandidate().

RTCIceCandidatePair? getNominatedCandidatePair()

Retrieves the selected candidate pair on which media is flowing. If there is no selected pair yet, or consent is lost on the selected pair, NULL is returned.

void start(RTCIceGatherer gatherer, RTCIceParameters remoteParameters, optional RTCIceRole role)

The first time start() is called, candidate connectivity checks are started and the ICE transport attempts to connect to the remote RTCIceTransport. If remoteParameters.iceLite is "true" then the remote peer supports ICE lite; if it is "false" or unset then the remote peer supports full ICE. If start() is called with invalid parameters, throw an InvalidParameters exception. For example, if gatherer.component has a value different from iceTransport.component, throw an InvalidParameters exception. If state is "closed", throw an InvalidStateError exception. When start() is called again, RTCIceTransportState transitions to the "connected" state, all remote candidates are flushed, and addRemoteCandidate() or setRemoteCandidates() must be called to add the remote candidates back or replace them.

If start() is called again, an InvalidStateError exception is thrown.

As noted in [[!RFC5245]] Section 7.1.2.3, an incoming connectivity check utilizes the local/remote username fragment and the local password, whereas an outgoing connectivity check utilizes the local/remote username fragment and the remote password. Since start() provides role information, as well as the remote username fragment and password, once start() is called an RTCIceTransport object can respond to incoming connectivity checks based on its configured role, as well as initiating connectivity checks.

void stop()

Stops and closes the current object. Calling stop() when state is "closed" has no effect.

RTCIceParameters? getRemoteParameters()

Obtain the current ICE parameters of the remote RTCIceTransport.

RTCIceTransport createAssociatedTransport ()

Create an associated RTCIceTransport for RTCP. If called more than once for the same component, or if state is "closed", throw an InvalidStateError exception. If called when component is "RTCP", throw an InvalidStateError exception.

void addRemoteCandidate(RTCIceGatherCandidate remoteCandidate)

Add a remote candidate associated with the remote RTCIceTransport. If state is "closed", throw an InvalidStateError exception. Since Microsoft Edge only supports "half-trickle", Edge will not begin candidate pair checks until RTCIceComplete has been passed as an argument to addRemoteCandidate().

void setRemoteCandidates(sequence<RTCIceCandidate> remoteCandidates)

Set the sequence of candidates associated with the remote RTCIceTransport. If state is "closed", throw an InvalidStateError exception.

attribute EventHandler? onicestatechange

This event handler, of event handler type icestatechange, uses the RTCIceTransportStateChangedEvent interface. It MUST be supported by all objects implementing the RTCIceTransport interface. It is called any time the RTCIceTransportState changes.

RTCIceComponent Enum

RTCIceComponent provides the component-id of the RTCIceTransport, which will be "RTP" unless RTP and RTCP are not multiplexed and the RTCIceTransport object was returned by createAssociatedTransport().

RTP

The RTP component ID, defined (as '1') in [[!RFC5245]] Section 4.1.1.1.

RTCP

The RTCP component ID, defined (as '2') in [[!RFC5245]] Section 4.1.1.1.

RTCIceRole Enum

RTCIceRole contains the current role of the ICE transport.

controlling

controlling state

controlled

controlled state

RTCIceTransportState Enum

RTCIceTransportState represents the current state of the ICE transport.

new

The RTCIceTransport object is waiting for remote candidates to be supplied. In this state the object can respond to incoming connectivity checks.

checking

The RTCIceTransport has received at least one remote candidate, and a local and remote RTCIceCandidateComplete dictionary was not added as the last candidate. In this state the RTCIceTransport is checking candidate pairs but has not yet found a successful candidate pair, or liveness checks have failed (such as those in [[!RFC7675]]) on a previously successful candidate pair.

connected

The RTCIceTransport has received a response to an outgoing connectivity check, or has received incoming DTLS/media after a successful response to an incoming connectivity check, but is still checking other candidate pairs to see if there is a better connection. In this state outgoing media is permitted.

completed

A local and remote RTCIceCandidateComplete dictionary was added as the last candidate to the RTCIceTransport and all appropriate candidate pairs have been tested and at least one functioning candidate pair has been found.

disconnected

The RTCIceTransport has received at least one local and remote candidate, and a local and remote RTCIceCandidateComplete dictionary was not added as the last candidate, but all appropriate candidate pairs thus far have been tested and failed (or consent checks [[!RFC7675]], once successful, have now failed). Other candidate pairs may become available for testing as new candidates are trickled, and therefore the "failed" state has not been reached.

closed

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

The non-normative ICE state transitions are:

RTCIceTransportStateChangedEvent

The icestatechange event of the RTCIceTransport object uses the RTCIceTransportStateChangedEvent interface.

Firing an RTCIceTransportStateChangedEvent event named e with an RTCIceTransportState state 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 RTCIceTransportStateChangedEvent interface with the state attribute set to the new RTCIceTransportState, MUST be created and dispatched at the given target.

readonly attribute RTCIceTransportState state

The state attribute is the new RTCIceTransportState that caused the event.

RTCIceTransportState? state

The state attribute is the new RTCIceTransportState that caused the event.

RTCIceCandidatePair Dictionary

The RTCIceCandidatePair contains the currently selected ICE candidate pair.

RTCIceCandidate local

The local ICE candidate.

RTCIceCandidate remote

The remote ICE candidate.

Overview

Microsoft Edge does not support the getRemoteCertificates() method, or a state value of "failed". Since Microsoft Edge requires support for RTP/RTCP mux with DTLS, an RTCDtlsTransport object can only be constructed from an RTP RTCIceTransport object.

Operation

A RTCDtlsTransport instance is constructed using an RTCIceTransport object.

A newly constructed RTCDtlsTransport MUST listen and respond to incoming DTLS packets before start() is called. However, to complete the negotiation it is necessary to verify the remote fingerprint, which is dependent on remoteParameters, passed to start(). After the DTLS handshake exchange completes (but before the remote fingerprint is verified) incoming media packets may be received. A modest buffer MUST be provided to avoid loss of media prior to remote fingerprint validation (which can begin after start() is called).

If an attempt is made to construct a RTCDtlsTransport instance from an RTCIceTransport in the "closed" state, an InvalidStateError exception is thrown. Since the Datagram Transport Layer Security (DTLS) negotiation occurs between transport endpoints determined via ICE, implementations of this specification MUST support multiplexing of STUN, TURN, DTLS and RTP and RTCP. This multiplexing, originally described in [[!RFC5764]] Section 5.1.2, is being revised in [[RFC7983]].

Interface Definition

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

void start(RTCDtlsParameters remoteParameters)

Start DTLS transport negotiation with the parameters of the remote DTLS transport, including verification of the remote fingerprint, then once the DTLS transport session is established, negotiate a DTLS-SRTP [[!RFC5764]] session to establish keys so as protect media using SRTP [[!RFC3711]]. Since symmetric RTP [[!RFC4961]] is utilized, the DTLS-SRTP session is bi-directional.

If remoteParameters is invalid, throw an InvalidParameters exception. If start() is called after a previous start() call, or if state is "closed", throw an InvalidStateError exception. Only a single DTLS transport can be multiplexed over an ICE transport. Therefore if a RTCDtlsTransport object dtlsTransportB is constructed with an RTCIceTransport object iceTransport previously used to construct another RTCDtlsTransport object dtlsTransportA, then if dtlsTransportB.start() is called prior to having called dtlsTransportA.stop(), then throw an InvalidStateError exception.

void stop()

Stops and closes the DTLS transport object. Calling stop() when state is "closed" has no effect.

attribute EventHandler? ondtlsstatechange

This event handler, of event handler type dtlsstatechange, uses the RTCDtlsTransportStateChangedEvent interface. It MUST be supported by all objects implementing the RTCDtlsTransport interface. It is called any time the RTCDtlsTransportState changes.

attribute EventHandler? onerror

This event handler, of event handler type error, MUST be supported by all objects implementing the RTCDtlsTransport interface. This event MUST be fired on reception of a DTLS alert.

RTCDtlsParameters Dictionary

The RTCDtlsParameters object includes information relating to DTLS configuration.

RTCDtlsRole role="auto"

The DTLS role, with a default of auto.

sequence<RTCDtlsFingerprint> fingerprints

Sequence of fingerprints.

RTCDtlsFingerprint Dictionary

The RTCDtlsFingerprint object includes the hash function algorithm and certificate fingerprint as described in [[!RFC4572]].

DOMString algorithm

One of the the hash function algorithms defined in the 'Hash function Textual Names' registry, initially specified in [[!RFC4572]] Section 8.

DOMString value

The value of the certificate fingerprint in lowercase hex string as expressed utilizing the syntax of 'fingerprint' in [[!RFC4572]] Section 5.

RTCDtlsRole Enum

RTCDtlsRole indicates the role of the DTLS transport.

auto

RTCDtlsRole is determined based on the resolved ICE role: the "controlled" role acts as the DTLS client and the "controlling" role acts as the DTLS server. Since RTCDtlsRole is initialized to "auto" on construction of an RTCDtlsTransport object, getLocalParameters().role will always return "auto".

client

The DTLS client role.

server

The DTLS server role.

DTLS role determination

To diagnose DTLS role issues, an application may wish to determine the desired and actual DTLS role of an RTCDtlsTransport. In Edge ORTC, a RTCDtlsTransport object assumes a DTLS role of auto upon construction. This implies that the DTLS role is determined by the ICE role. Since getLocalParameters().role always returns the role assigned to an RTCDtlsTransport object upon construction (auto for Edge), the getLocalParameters method cannot be used to determine the desired or actual role of an RTCDtlsTransport.

An application can determine the desired role of an RTCDtlsTransport from the value of remoteParameters.role passed to RTCDtlsTransport.start(remoteParameters). If remoteParameters.role is server then the desired role of the RTCDtlsTransport is client. If remoteParameters.role is client then the desired role of the RTCDtlsTransport is server.

The RTCDtlsTransport.transport.onicestatechange EventHandler can be used to determine whether an RTCDtlsTransport transitions to the desired role. When RTCDtlsTransport.transport.state transitions to connected, if RTCDtlsTransport.transport.role is controlled then the role of the RTCDtlsTransport is client. If RTCDtlsTransport.transport.role is controlling then the role of the RTCDtlsTransport is server.

RTCDtlsTransportState Enum

RTCDtlsTransportState indicates the state of the DTLS transport.

new

The RTCDtlsTransport object has been created and has not started negotiating yet.

connecting

DTLS is in the process of negotiating a secure connection. Once a secure connection is negotiated and DTLS-SRTP has derived keys (but prior to verification of the remote fingerprint, enabled by calling start()), incoming media can flow through.

connected

DTLS has completed negotiation of a secure connection (including DTLS-SRTP and remote fingerprint verification). Outgoing media can now flow through.

closed

The DTLS connection has been closed intentionally via a call to stop(), or as the result of an error. Calling transport.stop() will also result in a transition to the "closed" state.

RTCDtlsTransportStateChangedEvent

The dtlsstatechange event of the RTCDtlsTransport object uses the RTCDtlsTransportStateChangedEvent interface.

Firing an RTCDtlsTransportStateChangedEvent event named e with an RTCDtlsTransportState state 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 RTCDtlsTransportStateChangedEvent interface with the state attribute set to the new RTCDtlsTransportState, MUST be created and dispatched at the given target.

readonly attribute RTCDtlsTransportState state

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

RTCDtlsTransportState? state

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

Examples

// 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, when RTP and RTCP are multiplexed. 
// Assume that we have a way to signal (mySignaller). 
// Include some helper functions
import "helper.js";
function initiate(mySignaller) {
  // Prepare the ICE gatherer
  var gatherOptions = new RTCIceGatherOptions();
  gatherOptions.gatherPolicy = RTCIceGatherPolicy.all; 
  gatherOptions.iceservers = [ { urls: "stun:stun1.example.net" } , 
    { urls:"turn:turn.example.org", username: "user", credential:"myPassword"} ]; 
  var iceGatherer = new RTCIceGatherer(gatherOptions); 
  iceGatherer.onlocalcandidate = function(event) {
    mySignaller.mySendLocalCandidate(event.candidate);
  }; 
  // Create ICE and DTLS transports
  var ice = new RTCIceTransport();
  var dtls = new RTCDtlsTransport(ice);
  // Prepare to handle remote ICE candidates
  mySignaller.onRemoteCandidate = function(candidate){
   ice.addRemoteCandidate(candidate);
  }
  // ... create RtpSender/RtpReceiver objects as illustrated in Section 7.5 Example 9.

  mySignaller.mySendInitiate({
    "ice": iceGatherer.getLocalParameters(),
    "dtls": dtls.getLocalParameters(),
    // ... include RTP info from other example
  }, function(remote) {
    // Start the ICE transport
    ice.start(iceGatherer, remote.ice, RTCIceRole.controlling);
    dtls.start(remote.dtls);
    // ... configure RtpSender/RtpReceiver objects as illustrated in Section 7.5 Example 9.
  });
}
    

// This is an example of how to answer with ICE and DTLS
// and DTLS parameters and ICE candidates and start both ICE and DTLS,
// assuming that RTP and RTCP are multiplexed.
// Include some helper functions
import "helper.js";
// Assume that remote info is signalled to us. 
function accept(mySignaller, remote) {
  var gatherOptions = new RTCIceGatherOptions();
  gatherOptions.gatherPolicy = RTCIceGatherPolicy.all;
  gatherOptions.iceservers = [ { urls: "stun:stun1.example.net" } , 
    { urls:"turn:turn.example.org", username: "user", credential:"myPassword"} ] ;
  var iceGatherer = new RTCIceGatherer(gatherOptions);
  iceGatherer.onlocalcandidate = function(event) {
    mySignaller.mySendLocalCandidate(event.candidate);
  };
  // Create ICE and DTLS transports
  var ice = new RTCIceTransport();
  var dtls = new RTCDtlsTransport(ice);
  // Prepare to handle remote ICE candidates
  mySignaller.onRemoteCandidate = function(candidate){
    ice.addRemoteCandidate(candidate);
  }
  // ... create RtpSender/RtpReceiver objects as illustrated in Section 7.5 Example 9.

  mySignaller.mySendAccept({
    "ice": iceGatherer.getLocalParameters(),
    "dtls": dtls.getLocalParameters()
    // ... marshall RtpSender/RtpReceiver capabilities as illustrated in Section 7.5 Example 9.
  });
  // Start the ICE transport with an implicit gather policy of "all"
  ice.start(iceGatherer, remote.ice, RTCIceRole.controlled);
  // Start the DTLS transport
  dtls.start(remote.dtls);
  // ... configure RtpSender/RtpReceiver objects as illustrated in Section 7.5 Example 9. 
}

Overview

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

Operation

An RTCSrtpSdesTransport instance is constructed from an RTCIceTransport, as well as the encryption parameters (obtained from the local peer) and the decryption parameters (obtained from the remote peer). Both multiplexed and non-multiplexed RTP/RTCP are supported with RTCSrtpSdesTransport objects. If RTP and RTCP are not multiplexed, the RTP RTCIceTransport instance transport passed in the constructor is sufficient; if there is an "associated" RTCP transport rtcpTransport, it is provided implicitly. Since an RTCSrtpSdesTransport is ready to function as soon as it is created, there is no need for start() and stop() methods.

If either encryptParameters or decryptParameters contain a sequence of more than one keyParams dictionary, then keyParams.mkiValue and keyParams.mkiLength MUST be set to a value greater than zero for each keyParams dictionary entry or an InvalidParameters exception is thrown.

Interface Definition

readonly attribute RTCIceTransport transport

The associated RTCIceTransport instance. If transport.createAssociatedTransport() has been previously called and the constructed RTCP RTCIceTransport is not in the "closed" state, this indicates the desire to not multiplex RTP and RTCP. If transport.component is "RTCP" throw an InvalidParameters exception.

static sequence<RTCSrtpSdesParameters> getLocalParameters()

Obtain the local SRTP/SDES parameter sets.

attribute EventHandler? onerror

Set this handler to receive error events.

RTCSrtpSdesParameters Dictionary

The RTCSrtpSdesParameters object includes information relating to SRTP/SDES configuration.

unsigned short tag

The tag identifying the parameters set, in the syntax defined for 'tag' in [[!RFC4568]] Section 9.1.

DOMString cryptoSuite

The ciphersuite to be utilized, in the syntax defined for 'srtp-crypto-suite' in [[!RFC4568]] Section 9.2

sequence<RTCSrtpKeyParam> keyParams

The key parameters to be utilized, as described in [[!RFC4568]] Section 6.1. Calls to RTCSrtpSdesTransport.getLocalParameters SHOULD return only a single RTCSrtpKeyParam dictionary entry.

sequence<DOMString> sessionParams

A sequence of session parameters to be utilized, each in the syntax defined for 'session-param' in [[!RFC4568]] Section 9.1

RTCSrtpKeyParam Dictionary

DOMString keyMethod

The key method to be utilized, in the syntax defined for 'srtp-key-method' in [[!RFC4568]] Section 9.2.

DOMString keySalt

The key and salt to be utilized, in the syntax defined for 'key-salt' in [[!RFC4568]] Sections 9.2.

DOMString lifetime

The key lifetime to be utilized, in the syntax defined for 'lifetime' in [[!RFC4568]] Section 9.2.

unsigned short mkiValue

The master key index to be utilized.

unsigned short mkiLength

The master key index length in decimal digits, in the syntax defined for 'mki-length' in [[!RFC4568]] Section 9.2.

Examples

// This is an example of  how to offer ICE and SRTP/SDES parameters and 
// ICE candidates and get back ICE and SRTP/SDES parameters and ICE candidates,
// and start both ICE and SRTP/SDES, when RTP and RTCP are multiplexed. 
// Assume that we have a way to signal (mySignaller). 
// Include some helper functions
import "helper.js";
function initiate(mySignaller) {
  // Prepare the ICE gatherer
  var gatherOptions = new RTCIceGatherOptions();
  gatherOptions.gatherPolicy = RTCIceGatherPolicy.all; 
  gatherOptions.iceservers = [ { urls: "stun:stun1.example.net" } , 
    { urls:"turn:turn.example.org", username: "user", credential:"myPassword"} ]; 
  var iceGatherer = new RTCIceGatherer(gatherOptions); 
  iceGatherer.onlocalcandidate = function(event) {
    mySignaller.mySendLocalCandidate(event.candidate);
  }; 
  // Create ICE transport
  var ice = new RTCIceTransport();
  // Get SRTP/SDES encryption parameters
  var encryptParams = RTCSrtpSdesTransport.getLocalParameters(); 
  // Prepare to handle remote ICE candidates
  mySignaller.onRemoteCandidate = function(candidate){
   ice.addRemoteCandidate(candidate);
  }
  // ... create RtpSender/RtpReceiver objects as illustrated in Section 7.5 Example 9

  mySignaller.mySendInitiate({
    "ice": iceGatherer.getLocalParameters(),
    "srtpsdes": encryptParams, 
    // ... include RTP info from other example
  }, function(remote) {
    // Start the ICE transport
    ice.start(iceGatherer, remote.ice, RTCIceRole.controlling);
    // Construct the SRTP/SDES transport (which auto-starts)
    var srtpsdes = new RTCSrtpSdesTransport(ice, encryptParams, remote.srtpsdes);  
    // ... configure RtpSender/RtpReceiver objects as illustrated in Section 7.5 Example 9
  });
}
    

// This is an example of how to answer with ICE and SRTP/SDES
// parameters and ICE candidates and start both ICE and SRTP/SDES, 
// assuming that RTP and RTCP are multiplexed.
// Include some helper functions
import "helper.js";
// Assume that remote info is signalled to us. 
function accept(mySignaller, remote) {
  var gatherOptions = new RTCIceGatherOptions();
  gatherOptions.gatherPolicy = RTCIceGatherPolicy.all;
  gatherOptions.iceservers = [ { urls: "stun:stun1.example.net" } , 
    { urls:"turn:turn.example.org", username: "user", credential:"myPassword"} ] ;
  var iceGatherer = new RTCIceGatherer(gatherOptions);
  iceGatherer.onlocalcandidate = function(event) {
    mySignaller.mySendLocalCandidate(event.candidate);
  };
  // Create ICE transport
  var ice = new RTCIceTransport();
  // Get SRTP/SDES encryption parameters
  var encryptParams = RTCSrtpSdesTransport.getLocalParameters();
  // Prepare to handle remote ICE candidates
  mySignaller.onRemoteCandidate = function(candidate){
    ice.addRemoteCandidate(candidate);
  }
  // ... create RtpSender/RtpReceiver objects as illustrated in Section 7.5 Example 9. 

  mySignaller.mySendAccept({
    "ice": iceGatherer.getLocalParameters(),
    "srtpsdes": encryptParams, 
    // ... marshall RtpSender/RtpReceiver capabilities as illustrated in Section 7.5 Example 9. 
  });
  // Start the ICE transport with an implicit gather policy of "all"
  ice.start(iceGatherer, remote.ice, RTCIceRole.controlled);
    // Construct the SRTP/SDES transport (which auto-starts)
    var srtpsdes = new RTCSrtpSdesTransport(ice, encryptParams, remote.srtpsdes);
  // ... configure RtpSender/RtpReceiver objects as illustrated in Section 7.5 Example 9. 
}
    

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 or an RTCSrtpSdesTransport. If an attempt is made to construct an RTCRtpSender object with transport.state or rtcpTransport.state "closed", throw an InvalidStateError exception.

Interface Definition

readonly attribute MediaStreamTrack track

The associated MediaStreamTrack instance.

readonly attribute RTCTransport transport

The associated transport (either an RTCDtlsTransport or an RTCSrtpSdesTransport) instance.

void setTransport(RTCTransport transport)

setTransport() attempts to replace the transport (either RTCDtlsTransport or RTCSrtpSdesTransport) with the transport provided. Only RTP/RTCP multiplexing is supported if transport is an RTCDtlsTransport.

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

1. Let sender be the RTCRtpSender object on which setTransport() is invoked.

2. If sender.stop() has been called, throw an InvalidStateError exception.

3. Let withTransport be the argument to this method.

4. If setTransport() is called with no arguments, or if withTransport is unset, throw an InvalidParameters exception.

5. If withTransport.transport.component is rtcp, throw an InvalidParameters exception.

6. If withTransport is set and withTransport.state is closed, throw an InvalidStateError exception.

7. Replace transport with withTransport and seamlessly send over the new transport(s).

void setTrack(MediaStreamTrack track)

Set the track. If track.kind is changed, or if the new track has different peerIdentity constraints, throw an InvalidParameter Exception.

static RTCRtpCapabilities getCapabilities(optional DOMString kind)

Obtain the sender capabilities, based on kind. If kind is omitted or is set to "", then all capabilities are returned. Microsoft Edge does not support codecs such as retransmission [[!RFC4588]], redundancy [[RFC2198]] or Forward Error Correction which do not have an associated value of kind (and therefore would always be returned).

void send(RTCRtpParameters parameters)

Media to be sent is controlled by parameters. If send() is called with invalid parameters, throw an InvalidParameters exception. If transport is an RTCDtlsTransport and send(parameters) is called with parameters.rtcp.mux set to false, throw an InvalidParameters exception. The send() method does not update parameters based on what is currently being sent, so that the value of parameters remains that last passed to the send() method. The RTCRtpSender object starts sending when send() is called for the first time, and changes the sending parameters when send() is called again. The RTCRtpSender object stops sending when stop() is called.

void stop()

Stops sending the track on the wire, and sends an RTCP BYE. Stop is final as in MediaStreamTrack.stop()

void msSmartCrop(boolean on = false)

Indicates whether the sender will send crop information. By default, cropping is turned off.

attribute EventHandler? onerror

This event handler, of event handler type error, MUST be supported by all objects implementing the RTCRtpSender interface. This event MUST be fired if an issue is found with the RTCRtpParameters object passed to send(), that is not immediately detected.

attribute EventHandler? onmsquality

This event handler, of event handler type msquality, MUST be fired when an event affecting session quality occurs.

msquality

The msquality event uses the MSQualityEvent interface.

Firing a msquality event named e with messages 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 MSQualityEvent interface with the messages attribute MUST be created and dispatched at the given target.

readonly attribute sequence<MSQualityMessage> messages

The messages attribute contains the quality events that have been fired.

sequence<MSQualityMessage> messages

The messages attribute contains the quality events that have been fired.

MSQualityMessage Dictionary

The MSQualityMessages dictionary contains the name and value of a quality event, contained in the table below:

DOMString name

The name of the quality event.

DOMString value

The value of the quality event.

Overview

An RTCRtpReceiver instance is associated to a receiving MediaStreamTrack and provides RTC related methods to it. Microsoft Edge requires kind to be set in the constructor so as to allow a newly constructed RTCRtpReceiver to be used with an audio or video tag immediately, rather than having to wait until receive() is called for the value of kind to be determined.

Operation

A RTCRtpReceiver instance is constructed from an RTCDtlsTransport object or an RTCSrtpSdesTransport object. If an attempt is made to construct an RTCRtpReceiver object with transport.state or rtcpTransport.state "closed", throw an InvalidStateError exception.

Interface Definition

readonly attribute MediaStreamTrack? track

The associated MediaStreamTrack instance.

readonly attribute RTCTransport transport

The associated transport instance (either an RTCDtlsTransport or a RTCSrtpSdesTransport).

void setTransport(RTCTransport transport)

setTransport() attempts to replace the transport (either RTCDtlsTransport or RTCSrtpSdesTransport) with the transport provided. Only RTP/RTCP multiplexing is supported if transport is an RTCDtlsTransport.

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

1. Let receiver be the RTCRtpReceiver object on which setTransport() is invoked.

2. If receiver.stop() has been called, throw an InvalidStateError exception.

3. Let withTransport be the argument to this method.

4. If setTransport() is called with no arguments, or if withTransport is unset, throw an InvalidParameters exception.

5. If withTransport.transport.component is rtcp, throw an InvalidParameters exception.

6. If withTransport is set and withTransport.state is closed, throw an InvalidStateError exception.

7. Replace transport with withTransport and seamlessly receive over the new transport.

static RTCRtpCapabilities getCapabilities(optional DOMString kind)

Obtain the receiver capabilities, based on kind. If kind is omitted or set to "", then all capabilities are returned. Capabilities such as retransmission [[!RFC4588]], redundancy [[RFC2198]], and Forward Error Correction that do not have an associated value of kind are always included, regardless of the value of kind passed to getCapabilities(). To avoid confusion, getCapabilities(kind) should return codecs with a matching intrinsic kind value, as well as codecs with no intrinsic kind (such as redundancy [[RFC2198]]). For codecs with no intrinsic kind, RTCRtpCapabilities.RTCRtpCodecCapability[i].kind returned by getCapabilities(kind) should be set to the value of kind if kind is equal to "audio" or "video". If the kind argument was omitted or set to "", then the value of RTCRtpCapabilities.RTCRtpCodecCapability[i].kind is set to "".

sequence<RTCRtpContributingSource> getContributingSources()

Retrieve the sequence of contributing sources.

void receive(RTCRtpParameters parameters)

Media to be received is controlled by parameters. If receive(parameters) is called with invalid parameters, throw an InvalidParameters exception. If transport is an RTCDtlsTransport and receive(parameters) is called with parameters.rtcp.mux set to false, throw an InvalidParameters exception. The receive() method does not update parameters based on what is currently being received, so that the value of parameters remains that last passed to the receive() method. The RTCRtpReceiver object starts receiving when receive() is called for the first time, and changes the receiving parameters when receive() is called again. The RTCRtpReceiver object stops receiving when stop() is called. After receive() returns, track is set. The value of track.kind is determined based on the kind used in the constructor, which must match that of the codecs provided in parameters.codecs. If parameters.codecs are of mixed kind, or are of a single kind which does not match the value used in the constructor, throw an InvalidParameters exception. For this purpose a kind of "" is not considered mixed.

void stop()

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

void msSmartCrop(boolean on = false)

Indicates whether the receiver will utilize crop information if it is provided by the sender. By default, cropping is turned off.

attribute EventHandler? onerror

This event handler, of event handler type error, MUST be supported by all objects implementing the RTCRtpReceiver interface. This event MUST be fired if an issue is found with the RTCRtpParameters object passed to receive(), that is not immediately detected.

attribute EventHandler? onmsdsh

This event handler, of event handler type msdsh, MUST be fired when a Dominant Speaker History (DSH) RTCP packet is received, indicating a change in the dominant speaker(s).

attribute EventHandler? onmsdecodercapacitychange

This event handler, of event handler type msdecodercapacitychange, MUST be fired when the decoder capacity changes.

attribute EventHandler? onmsquality

This event handler, of event handler type msquality, MUST be fired when an event affecting session quality occurs.

RTCRtpContributingSource Dictionary

DOMHighResTimeStamp timestamp

Timestamp indicating when an RTP packet containing the contributing source was last received. The time is relative to the UNIX epoch (Jan 1, 1970, UTC).

unsigned long csrc

The contributing source.

dsh

The msdsh event of the RTCRtpReceiver object uses the MSDSHEvent interface.

Firing a msdsh event named e with timestamp and sources 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 MSDSHEvent interface MUST be created and dispatched at the given target.

readonly attribute DOMHighResTimeStamp timestamp

Timestamp indicating when an RTP packet containing the contributing source was last received. The time is relative to the UNIX epoch (Jan 1, 1970, UTC).

readonly attribute sequence<unsigned long> sources

The sources attribute contains the sequence of new dominant speakers that caused the event.

DOMHighResTimeStamp timestamp

Timestamp indicating when an RTP packet containing the contributing source was last received. The time is relative to the UNIX epoch (Jan 1, 1970, UTC).

sequence<unsigned long> sources

The sources attribute contains the sequence of new dominant speakers that caused the event.

msdecodercapacitychange

The msdecodercapacitychange event of the RTCRtpReceiver object uses the MSDCCEvent interface.

Firing a msdecodercapacitychange event named e with maxFr and maxFs 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 MSDCCEvent interface with the maxFr maxFs attributes MUST be created and dispatched at the given target.

readonly attribute unsigned long maxFr

The maxFr attribute contains the maximum frame rate per second capacity.

readonly attribute unsigned long maxFs

The maxFs attribute contains the maximum macroblock per second capacity.

unsigned long maxFr

The maxFr attribute contains the maximum frame rate per second capacity.

unsigned long maxFs

The maxFs attribute contains the maximum macroblock per second capacity.

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.
// The example assumes that RTP and RTCP are multiplexed. 
function myInitiate(mySignaller, transport, audioTrack, videoTrack) {
  var audioSender = new RTCRtpSender(audioTrack, transport);
  var videoSender = new RTCRtpSender(videoTrack, transport);
  var audioReceiver = new RTCRtpReceiver(transport, 'audio');
  var videoReceiver = new RTCRtpReceiver(transport, 'video');

// Retrieve the audio and video receiver capabilities
  var recvAudioCaps = RTCRtpReceiver.getCapabilities('audio');
  var recvVideoCaps = RTCRtpReceiver.getCapabilities('video');   
// Retrieve the audio and video sender capabilities
  var sendAudioCaps = RTCRtpSender.getCapabilities('audio'); 
  var sendVideoCaps = RTCRtpSender.getCapabilities('video'); 

  mySignaller.myOfferTracks({
    // The initiator offers its receiver and sender capabilities. 
    "recvAudioCaps": recvAudioCaps, 
    "recvVideoCaps": recvVideoCaps,
    "sendAudioCaps": sendAudioCaps,
    "sendVideoCaps": sendVideoCaps 
  }, function(answer) {
    // The responder answers with its receiver capabilities

    // Derive the send and receive parameters
    var audioSendParams = myCapsToSendParams(sendAudioCaps, answer.recvAudioCaps); 
    var videoSendParams = myCapsToSendParams(sendVideoCaps, answer.recvVideoCaps); 
    var audioRecvParams = myCapsToRecvParams(recvAudioCaps, answer.sendAudioCaps);
    var videoRecvParams = myCapsToRecvParams(recvVideoCaps, answer.sendVideoCaps); 
    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. 
// The example assumes that RTP and RTCP are multiplexed. 
function myAccept(mySignaller, remote, transport, audioTrack, videoTrack) {
  var audioSender = new RTCRtpSender(audioTrack, transport);
  var videoSender = new RTCRtpSender(videoTrack, transport);
  var audioReceiver = new RTCRtpReceiver(transport, 'audio');
  var videoReceiver = new RTCRtpReceiver(transport, 'video');

// Retrieve the send and receive capabilities
  var recvAudioCaps = RTCRtpReceiver.getCapabilities('audio');
  var recvVideoCaps = RTCRtpReceiver.getCapabilities('video');
  var sendAudioCaps = RTCRtpSender.getCapabilities('audio'); 
  var sendVideoCaps = RTCRtpSender.getCapabilities('video'); 

  mySignaller.myAnswerTracks({
    "recvAudioCaps": recvAudioCaps,
    "recvVideoCaps": recvVideoCaps,
    "sendAudioCaps": sendAudioCaps,
    "sendVideoCaps": sendVideoCaps
  });

    // Derive the send and receive parameters using Javascript functions defined in Section 17.2.
    var audioSendParams = myCapsToSendParams(sendAudioCaps, remote.recvAudioCaps);
    var videoSendParams = myCapsToSendParams(sendVideoCaps, remote.recvVideoCaps);
    var audioRecvParams = myCapsToRecvParams(recvAudioCaps, remote.sendAudioCaps);
    var videoRecvParams = myCapsToRecvParams(recvVideoCaps, remote.sendVideoCaps);
    audioSender.send(audioSendParams);
    videoSender.send(videoSendParams);
    audioReceiver.receive(audioRecvParams);
    videoReceiver.receive(videoRecvParams);

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

Overview

An MSRTCConfConfig object provides configuration for RTCIceGatherer objects.

Operation

An MSRTCConfConfig object is (optionally) constructed from an MSRTCConfSettings object.

Interface Definition

attribute EventHandler? onmsvideoreceivers

This event handler, of event handler type msvideoreceivers, MUST be fired when the number of potential video receivers changes.

MSRTCConfSettings Dictionary

The MSRTCConfSettings dictionary provides configuration settings for the conference.

boolean msConfMode = false

msConfMode has the value true if the configuration is associated with a conferencing server, false otherwise. By default msConfMode is set to false.

MSRTCSystemSettings msSysSettings

The configuration corresponding to this conference.

MSRTCSystemSettings Dictionary

The MSRTCSystemSettings dictionary provides system configuration information.

sequence<MSDeviceDriver> hardwareVideoEncoderBlockList

A sequence of dictionaries indicating graphics drivers that do not have compatible hardware encoding support.

MSDeviceDriver Dictionary

The MSDeviceDriver dictionary provides information on unsupported devices, such as the identifier and device driver versions.

DOMString vendorId

The vendor ID.

DOMString deviceId

The PNP Device ID in hex format. Zero (0) means all.

DOMString deviceDriverVersionRangeMin

Starting graphics driver version (inclusive) to be blocked.

DOMString deviceDriverVersionRangeMax

Ending graphics driver version (inclusive) to be blocked.

msvideoreceivers

The msvideoreceivers event of the MSRTCConfConfig object uses the MSVideoReceiversEvent interface.

Firing a msvideoreceivers event named e with maxReceivers 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 MSVideoReceiversEvent interface with the maxReceivers attribute MUST be created and dispatched at the given target.

readonly attribute unsigned long maxReceivers

The maxReceivers attribute contains the maximum number of video receivers.

unsigned long maxReceivers

The maxReceivers attribute contains the maximum number of video receivers.

RTCRtpCapabilities Dictionary

The RTCRtpCapabilities object expresses the capabilities of RTCRtpSender and RTCRtpReceiver objects. Features which are mandatory to implement in [[!RTP-USAGE]], such as RTP/RTCP multiplexing [[!RFC5761]], audio/video multiplexing [[!RTP-MULTI-STREAM]] and reduced size RTCP [[!RFC5506]] are assumed to be available and are therefore not included in RTCRtpCapabilities, although these features can be set via RTCRtpParameters.

sequence<RTCRtpCodecCapability> codecs

Supported codecs.

sequence<RTCRtpHeaderExtension> headerExtensions

Supported RTP header extensions.

sequence<DOMString> fecMechanisms

Supported Forward Error Correction (FEC) mechanisms. Values include "red", "red+ulpfec", "x-ulpfecuc" and "flexfec".

RTCRtcpFeedback Dictionary

RTCRtcpFeedback provides information on RTCP feedback messages. Microsoft Edge ORTC supports the Generic NACK [[!RFC4585]] and PLI [[!RFC4585]] feedback messages, as well as the Google Receiver Estimated Maximum Bitrate ("goog-remb") feedback message [[REMB]]. In addition, [[MS-SDPEXT]] Section 3.1.5.30.2 describes Microsoft proprietary feedback messages supported in Edge ORTC, including the Dominant Speaker History Notification (dsh), Video Source Request (src), and Picture Loss Indicator (x-pli) messages.

DOMString type

Valid values for type are the "RTCP Feedback" Attribute Values enumerated in [[!IANA-SDP-14]] ("ack", "ccm", "nack", etc.), as well as "goog-remb" [[!REMB]]

DOMString parameter

For a type of "ack" or "nack", valid values for parameter are the "ack" and "nack" Attribute Values enumerated in [[!IANA-SDP-15]] ("sli", "rpsi", etc.). For the Generic NACK feedback message defined in [[!RFC4585]] Section 6.2.1, the type attribute is set to "nack" and the parameter attribute is unset. For a type of "ccm", valid values for parameter are the "Codec Control Messages" enumerated in [[!IANA-SDP-19]] ("fir", "tmmbr" (includes "tmmbn"), etc.).

RTCRtpCodecCapability Dictionary

RTCRtpCodecCapability provides information on the capabilities of a codec.

DOMString name

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

DOMString kind

The media supported by the codec: "audio", "video" or "" for both.

unsigned long clockRate

Codec clock rate expressed in Hertz, null if unset.

payloadtype preferredPayloadType

The preferred RTP payload type for the codec denoted by RTCRtpCodecCapability.name. This attribute was added to make it possible for the sender and receiver to pick a matching payload type when creating sender and receiver parameters. When returned by RTCRtpSender.getCapabilities(), RTCRtpCapabilities.codecs.preferredPayloadtype represents the preferred RTP payload type for sending. When returned by RTCRtpReceiver.getCapabilities(), RTCRtpCapabilities.codecs.preferredPayloadtype represents the preferred RTP payload type for receiving. To avoid payload type conflicts, each value of RTCRtpCodecCapability.name should have a unique value of RTCRtpCodecCapability.preferredPayloadtype.

unsigned long maxptime

The maximum packetization time supported by the RTCRtpReceiver.

unsigned long ptime

The preferred duration of media represented by a packet in milliseconds for the RTCRtpSender or RTCRtpReceiver. For an RTCRtpReceiver, must be less than the value of maxptime.

unsigned long numChannels

The number of channels supported (e.g. stereo). For video, this will be unset.

sequence<RTCRtcpFeedback> rtcpFeedback

Transport layer and codec-specific feedback messages for this codec.

Dictionary parameters

Codec-specific parameters that must be signaled to the remote party.

Dictionary options

Codec-specific parameters available for signaling.

unsigned short maxTemporalLayers = 0

Maximum number of temporal layer extensions supported by this codec (e.g. a value of 1 indicates support for up to 2 temporal layers). A value of 0 indicates no support for temporal scalability.

unsigned short maxSpatialLayers = 0

Maximum number of spatial layer extensions supported by this codec (e.g. a value of 1 indicates support for up to 2 spatial layers). A value of 0 indicates no support for spatial scalability.

boolean svcMultiStreamSupport

Whether the implementation can send SVC layers utilizing distinct SSRCs. Unset for audio codecs. For video codecs, only set if the codec supports scalable video coding with multiple streams.

{
  "name": "PCMU",
  "kind": "audio",
  "clockRate": 8000,
  "preferredPayloadType": 0,
  "maxptime": 60,
  "ptime": 20,
  "numChannels": 1,
  "rtcpFeedback": [
    {
      "type": "x-message",
      "parameter": "app send:dsh recv:dsh"
    }
  ],
  "parameters": {},
  "options": {},
  "maxTemporalLayers": 0,
  "maxSpatialLayers": 0,
  "svcMultiStreamSupport": false
},
{
  "name": "PCMA",
  "kind": "audio",
  "clockRate": 8000,
  "preferredPayloadType": 8,
  "maxptime": 60,
  "ptime": 20,
  "numChannels": 1,
  "rtcpFeedback": [
    {
      "type": "x-message",
      "parameter": "app send:dsh recv:dsh"
    }
  ],
  "parameters": {},
  "options": {},
  "maxTemporalLayers": 0,
  "maxSpatialLayers": 0,
  "svcMultiStreamSupport": false
}
   

{
  "name": "G722",
  "kind": "audio",
  "clockRate": 8000,
  "preferredPayloadType": 9,
  "maxptime": 60,
  "ptime": 20,
  "numChannels": 1,
  "rtcpFeedback": [
    {
      "type": "x-message",
      "parameter": "app send:dsh recv:dsh"
    }
  ],
  "parameters": {},
  "options": {},
  "maxTemporalLayers": 0,
  "maxSpatialLayers": 0,
  "svcMultiStreamSupport": false
}
   

{
  "name": "CN",
  "kind": "audio",
  "clockRate": 8000,
  "preferredPayloadType": 13,
  "maxptime": 0,
  "ptime": 0,
  "numChannels": 1,
  "rtcpFeedback": [],
  "parameters": {},
  "options": {},
  "maxTemporalLayers": 0,
  "maxSpatialLayers": 0,
  "svcMultiStreamSupport": false
},
{
  "name": "CN",
  "kind": "audio",
  "clockRate": 16000,
  "preferredPayloadType": 118,
  "maxptime": 0,
  "ptime": 0,
  "numChannels": 1,
  "rtcpFeedback": [],
  "parameters": {},
  "options": {},
  "maxTemporalLayers": 0,
  "maxSpatialLayers": 0,
  "svcMultiStreamSupport": false
}
   

{
  "name": "telephone-event",
  "kind": "audio",
  "clockRate": 8000,
  "preferredPayloadType": 101,
  "maxptime": 0,
  "ptime": 0,
  "numChannels": 1,
  "rtcpFeedback": [],
  "parameters": {
    "events": "0-16"
  },
  "options": {},
  "maxTemporalLayers": 0,
  "maxSpatialLayers": 0,
  "svcMultiStreamSupport": false
}
   

{
  "name": "opus",
  "kind": "audio",
  "clockRate": 48000,
  "preferredPayloadType": 102,
  "maxptime": 60,
  "ptime": 20,
  "numChannels": 2,
  "rtcpFeedback": [
    {
      "type": "x-message",
      "parameter": "app send:dsh recv:dsh"
    }
  ],
  "parameters": {},
  "options": {},
  "maxTemporalLayers": 0,
  "maxSpatialLayers": 0,
  "svcMultiStreamSupport": false
}
   

{
  "name": "SILK",
  "kind": "audio",
  "clockRate": 8000,
  "preferredPayloadType": 103,
  "maxptime": 60,
  "ptime": 20,
  "numChannels": 1,
  "rtcpFeedback": [
    {
      "type": "x-message",
      "parameter": "app send:dsh recv:dsh"
    }
  ],
  "parameters": {},
  "options": {},
  "maxTemporalLayers": 0,
  "maxSpatialLayers": 0,
  "svcMultiStreamSupport": false
},
{
  "name": "SILK",
  "kind": "audio",
  "clockRate": 16000,
  "preferredPayloadType": 104,
  "maxptime": 100,
  "ptime": 20,
  "numChannels": 1,
  "rtcpFeedback": [
    {
      "type": "x-message",
      "parameter": "app send:dsh recv:dsh"
    }
  ],
  "parameters": {},
  "options": {},
  "maxTemporalLayers": 0,
  "maxSpatialLayers": 0,
  "svcMultiStreamSupport": false
}
   

{
  "name": "RED",
  "kind": "audio",
  "clockRate": 8000,
  "preferredPayloadType": 97,
  "maxptime": 0,
  "ptime": 0,
  "numChannels": 1,
  "rtcpFeedback": [],
  "parameters": {},
  "options": {},
  "maxTemporalLayers": 0,
  "maxSpatialLayers": 0,
  "svcMultiStreamSupport": false
}
    

{
  "codecs": [
    {
      "name": "X-H264UC",
      "kind": "video",
      "clockRate": 90000,
      "preferredPayloadType": 122,
      "maxptime": 0,
      "ptime": 0,
      "numChannels": 1,
      "rtcpFeedback": [
        {
          "type": "x-message",
          "parameter": "app send:src,x-pli recv:src,x-pli"
        }
      ],
      "parameters": {
        "packetization-mode": "1",
        "mst-mode": "NI-TC"
      },
      "options": {},
      "maxTemporalLayers": 3,
      "maxSpatialLayers": 0,
      "svcMultiStreamSupport": true
    },
    {
      "name": "x-ulpfecuc",
      "kind": "video",
      "clockRate": 90000,
      "preferredPayloadType": 123,
      "maxptime": 0,
      "ptime": 0,
      "numChannels": 1,
      "rtcpFeedback": [],
      "parameters": {},
      "options": {},
      "maxTemporalLayers": 0,
      "maxSpatialLayers": 0,
      "svcMultiStreamSupport": false
    }
  ],
  "headerExtensions": [
    {
      "kind": "video",
      "uri": "http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time",
      "preferredId": 1,
      "preferredEncrypt": false
    },
    {
      "kind": "video",
      "uri": "http://skype.com/experiments/rtp-hdrext/fast_bandwidth_feedback#version_2",
      "preferredId": 3,
      "preferredEncrypt": false
    }
  ],
  "fecMechanisms": []
}
   

{
  "name": "H264",
  "kind": "video",
  "clockRate": 90000,
  "preferredPayloadType": 107,
  "maxptime": 0,
  "ptime": 0,
  "numChannels": 1,
  "rtcpFeedback": [
    {
      "type": "nack",
      "parameter": ""
    },
    {
      "type": "nack",
      "parameter": "pli"
    },
    {
      "type": "goog-remb",
      "parameter": ""
    }
  ],
  "parameters": {
    "profile-level-id": "42C02A",
    "packetization-mode": "1"
  },
  "options": {},
  "maxTemporalLayers": 3,
  "maxSpatialLayers": 0,
  "svcMultiStreamSupport": false
}
    

{
  "name": "VP8",
  "kind": "video",
  "clockRate": 90000,
  "preferredPayloadType": 100,
  "maxptime": 0,
  "ptime": 0,
  "numChannels": 1,
  "rtcpFeedback": [
    {
      "type": "nack",
      "parameter": ""
    },
    {
      "type": "nack",
      "parameter": "pli"
    },
    {
      "type": "goog-remb",
      "parameter": ""
    }
  ],
  "parameters": {
    "max-fr": "30",
    "max-fs": "3600"
   },
   "options": {},
   "maxTemporalLayers": 0,
   "maxSpatialLayers": 0,
   "svcMultiStreamSupport": false
}
    

{
  "codecs": [
    {
      "name": "H264",
      "kind": "video",
      "clockRate": 90000,
      "preferredPayloadType": 107,
      "maxptime": 0,
      "ptime": 0,
      "numChannels": 1,
      "rtcpFeedback": [
        {
          "type": "nack",
          "parameter": ""
        },
        {
          "type": "nack",
          "parameter": "pli"
        },
        {
          "type": "goog-remb",
          "parameter": ""
        }
      ],
      "parameters": {
        "profile-level-id": "42C02A",
        "packetization-mode": "1"
      },
      "options": {},
      "maxTemporalLayers": 3,
      "maxSpatialLayers": 0,
      "svcMultiStreamSupport": false
    },
    {
      "name": "VP8",
      "kind": "video",
      "clockRate": 90000,
      "preferredPayloadType": 100,
      "maxptime": 0,
      "ptime": 0,
      "numChannels": 1,
      "rtcpFeedback": [
        {
          "type": "nack",
          "parameter": ""
        },
        {
          "type": "nack",
          "parameter": "pli"
        },
        {
          "type": "goog-remb",
          "parameter": ""
        }
      ],
      "parameters": {
        "max-fr": "30",
        "max-fs": "3600"
      },
      "options": {},
      "maxTemporalLayers": 0,
      "maxSpatialLayers": 0,
      "svcMultiStreamSupport": false
    },
    {
      "name": "rtx",
      "kind": "video",
      "clockRate": 90000,
      "preferredPayloadType": 99,
      "maxptime": 0,
      "ptime": 0,
      "numChannels": 1,
      "rtcpFeedback": [],
      "parameters": {
        "apt": "107"
      },
      "options": {},
      "maxTemporalLayers": 0,
      "maxSpatialLayers": 0,
      "svcMultiStreamSupport": false
    },
    {
      "name": "rtx",
      "kind": "video",
      "clockRate": 90000,
      "preferredPayloadType": 96,
      "maxptime": 0,
      "ptime": 0,
      "numChannels": 1,
      "rtcpFeedback": [],
      "parameters": {
        "apt": "100"
      },
      "options": {},
      "maxTemporalLayers": 0,
      "maxSpatialLayers": 0,
      "svcMultiStreamSupport": false
    }
  ],
  "headerExtensions": [
    {
      "kind": "video",
      "uri": "http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time",
      "preferredId": 1,
      "preferredEncrypt": false
    },
    {
      "kind": "video",
      "uri": "http://skype.com/experiments/rtp-hdrext/fast_bandwidth_feedback#version_2",
      "preferredId": 3,
      "preferredEncrypt": false
    }
  ],
  "fecMechanisms": []
}
    

RTCRtpParameters Dictionary

RTCRtpParameters contains the RTP stack settings.

DOMString muxId=""

The muxId assigned to the RTP stream, if any, empty string if unset. In an RTCRtpReceiver or RTCRtpSender object, this corresponds to MID RTP header extension defined in [[!BUNDLE]]. This is a stable identifier that permits the track corresponding to an RTP stream to be identified, rather than relying on an SSRC. An SSRC is randomly generated and can change arbitrarily due to conflicts with other SSRCs, whereas the muxId has a value whose meaning can be defined in advance between RTP sender and receiver, assisting in RTP demultiplexing. Note that including muxId in RTCRtpParameters rather than in RTCRtpEncodingParameters implies that if it is desired to send simulcast streams with different muxId values for each stream, then multiple RTCRtpSender objects are needed.

Edge Interop Note: Microsoft Edge currently does not support the muxId attribute, or the MID RTP header extension.

sequence<RTCRtpCodecParameters> codecs

The codecs to send or receive (could include RED [[RFC2198]], RTX [[!RFC4588]] and CN [[RFC3389]]).

sequence<RTCRtpHeaderExtensionParameters> headerExtensions

Configured header extensions.

sequence<RTCRtpEncodingParameters> encodings

The "encodings" or "layers" to be used for simulcast and Scalable Video Coding, both unsupported.

RTCRtcpParameters rtcp

Parameters to configure RTCP.

RTCDegradationPreference degradationPreference = "balanced"

When bandwidth is constrained and the RTCRtpSender needs to choose between degrading resolution or degrading framerate, degradationPreference indicates which is preferred. degradationPreference is ignored in an RTCRtpReceiver object.

RTCRtpHeaderExtension Dictionary

DOMString kind

The media supported by the header extension: "audio" for an audio codec, "video" for a video codec, and "" for both.

DOMString uri

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

unsigned short preferredId

The preferred ID value that goes in the packet.

boolean preferredEncrypt=false

If true, it is preferred that the value in the header be encrypted as per [[!RFC6904]]. Default is to prefer unencrypted.

RTCRtpHeaderExtensionParameters Dictionary

DOMString uri

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

unsigned short id

The value that goes in the packet.

boolean encrypt=false

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

RTP header extensions

Registered RTP header extensions are listed in [[!IANA-RTP-10]]. Header extensions to be supported in Edge ORTC include:

RTCDegradationPreference Enum

RTCDegradationPreference can be used to indicate the desired choice between degrading resolution and degrading framerate when bandwidth is constrained.

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.

RTCRtcpParameters Dictionary

RTCRtcpParameters provides information on RTCP settings.

unsigned long ssrc

For an RTCRtpReceiver this represents the SSRC to be used in the "SSRC of packet sender" field defined in [[!RFC3550]] Section 6.4.2 (Receiver Report) and [[!RFC4585]] Section 6.1 (Feedback Messages), as well as the "SSRC" field defined in [[!RFC3611]] Section 2 (Extended Reports). For an RTCRtpSender, this represents the value to match against the "SSRC of packet sender" field in order to route RTCP packets intended for that object (such as REMB and Receiver Reports). If unset, ssrc is chosen by the browser, and the chosen value is not reflected in RTCRtcpParameters.ssrc. If the browser chooses the ssrc it may change it in event of a collision, as described in [[!RFC3550]].

DOMString cname

The Canonical Name (CNAME) used by RTCP (e.g. in SDES messages). Guidelines for CNAME generation are provided in [[!RTP-USAGE]] Section 4.9 and [[!RFC7022]]. By default, ORTC implementations SHOULD set the CNAME to be the same within all RTCRtcpParameter objects created within the same Javascript sandbox. For backward compatibility with WebRTC 1.0, applications MAY set cname; if unset, cname is chosen by the browser.

boolean compound=true

Whether reduced size RTCP [[!RFC5506]] is configured (if set to false) or compound RTCP as specified in [[!RFC3550]] (if set to true). The default is true.

boolean mux=true

Whether RTP and RTCP are multiplexed, as specified in [[!RFC5761]]. The default is true. If set to false, the RTCIceTransport MUST have an associated RTCIceTransport object with a component of "RTCP", in which case RTCP will be sent on the associated RTCIceTransport.

RTCRtpCodecParameters Dictionary

RTCRtpCodecParameters provides information on codec settings.

DOMString name

The MIME media type. Valid types are listed in [[!IANA-RTP-2]]. The name MUST always be provided.

payloadtype payloadType

The value that goes in the RTP Payload Type Field [[!RFC3550]]. The payloadType MUST always be provided.

unsigned long clockRate

Codec clock rate expressed in Hertz, null if unset.

unsigned long maxptime

The maximum packetization time set on the RTCRtpSender. Not specified if unset.

unsigned long ptime

The duration of media represented by a packet in milliseconds for the RTCRtpSender. If unset, the RTCRtpSender may select any value up to maxptime.

unsigned long numChannels

The number of channels supported (e.g. stereo). If unset for audio, use the codec default. For video, this can be left unset.

sequence<RTCRtcpFeedback> rtcpFeedback

Transport layer and codec-specific feedback messages for this codec.

Dictionary parameters

Codec-specific parameters available for signaling.

RTCRtpEncodingParameters Dictionary

unsigned long ssrc=null

The SSRC for this layering/encoding. If ssrc is unset in a RTCRtpEncodingParameters object passed to the RTCRtpReceiver.receive method, then matching will occur based on payload type. If ssrc is unset in a RTCRtpEncodingParameters object passed to the RTCRtpSender.send method, the browser will choose, and the chosen value is not reflected in RTCRtpEncodingParameters.ssrc. The Microsoft ORTC API implementation does not support detection or healing SSRC collisions. In the event that the browser chooses the ssrc, it will not change due to a collision.

payloadtype codecPayloadType

For per-encoding codec specifications, give the codec Payload Type here. If unset, the browser will choose.

RTCRtpFecParameters fec

Specifies the FEC mechanism if set.

RTCRtpRtxParameters rtx

Specifies the RTX [[!RFC4588]] parameters (such as the payload type to use for retransmitting this stream) if set. The payload type to be retransmitted is specified in codecPayloadType.

double maxFramerate

The maximum framerate to use for this encoding. This setting is not used for scalable video coding.

boolean active=true

For an RTCRtpSender, indicates whether 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. If unset, the default (true) is assumed. For an RTCRtpReceiver, indicates that this encoding is being decoded. Setting it to false causes this encoding to no longer be decoded. Setting it to true causes this encoding to be decoded. If unset, the default (true) is assumed. Setting active to "false" is different than omitting the encoding, since it can keep resources available to re-activate more quickly than re-adding the encoding. As noted in [[RFC3264]] Section 5.1, RTCP is still sent, regardless of the value of the active attribute.

RTCRtpFecParameters Dictionary

unsigned long ssrc

The SSRC to use for FEC. If unset in an RTCRtpSender object, the browser will choose.

DOMString mechanism

The Forward Error Correction (FEC) mechanism to use.

RTCRtpRtxParameters Dictionary

unsigned long ssrc

The SSRC to use for retransmission, as specified in [[!RFC4588]]. If unset when passed to RTCRtpSender.send(), the browser will choose.

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)

The insertDTMF() method is used to send DTMF tones. Since DTMF tones cannot be sent without configuring the DTMF codec, if insertDTMF() is called prior to sender.send(parameters), or if sender.send(parameters) was called but parameters did not include the DTMF codec, throw an InvalidStateError exception.

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

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

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

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

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.

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

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.

DTMF Example

Examples assume that sendObject is an RTCRtpSender object.

Sending the DTMF signal "1234" with 500 ms duration per tone:

var sender = new RTCDtmfSender(sendObject);
if (sender.canInsertDTMF) {
var duration = 500;
sender.insertDTMF("1234", duration);
} else {
trace("DTMF function not available");
}      

Send the DTMF signal "1234", and light up the active key using lightKey(key) while the tone is playing (assuming that lightKey("") will darken all the keys):

var sender = new RTCDtmfSender(sendObject);
sender.ontonechange = function (e) {
if (!e.tone)
return;
// light up the key when playout starts
lightKey(e.tone);
// turn off the light after tone duration
setTimeout(lightKey, sender.duration, "");
};
sender.insertDTMF("1234");

Send a 1-second "1" tone followed by a 2-second "2" tone:

var sender = new RTCDtmfSender(sendObject);
sender.ontonechange = function (e) {
if (e.tone == "1")
sender.insertDTMF("2", 2000);
};
sender.insertDTMF("1", 1000);

It is always safe to append to the tone buffer. This example appends before any tone playout has started as well as during playout.

var sender = new RTCDtmfSender(sendObject);
sender.insertDTMF("123");
// append more tones to the tone buffer before playout has begun
sender.insertDTMF(sender.toneBuffer + "456");

sender.ontonechange = function (e) {
if (e.tone == "1")
// append more tones when playout has begun
sender.insertDTMF(sender.toneBuffer + "789");
};

Send the DTMF signal "123" and abort after sending "2".

var sender = new RTCDtmfSender(sendObject);
sender.ontonechange = function (e) {
if (e.tone == "2")
// empty the buffer to not play any tone after "2"
sender.insertDTMF("");
};
sender.insertDTMF("123");

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.

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). The timestamp for local measurements corresponds to the to the local clock and for remote measurements corresponds to the timestamp indicated in the incoming RTCP Sender Report (SR), Receiver Report (RR) or Extended Report (XR).

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.

RTP/RTCP routing rules

Edge implements a subset of the RTP routing rules described in [[!BUNDLE]] Section 10.2. Since Edge does not support the MID RTP header extension, it does not route RTP packets based on the contents of that header extension, nor does it support the RTCRtpParameters.muxId attribute. However, Edge does support RTP packet routing based on the Payload Type (PT) as well as SSRCs. Since Edge does not support the RTCRtpListener object, RTP packets that cannot be routed to an RTCRtpReceiver are dropped.

Since statistics are retrieved from objects within the ORTC API, and information within RTCP packets is used to maintain some of the statistics, the routing of RTCP packets is important to the operation of the statistics API as well as to the operation of congestion control.

RTCP packets arriving on an RTCDtlsTransport are decrypted and a notification is sent to all RTCRtpSender and RTCRtpReceiver objects utilizing that transport. RTCRtpSender and RTCRtpReceiver objects then examine the RTCP packets to determine the information relevant to their operation and the statistics maintained by them.

RTCP packets should be queued for 30 seconds and all RTCRtpSender and RTCRtpReceiver objects on the related RTCDTlsTransport have access to those packets until the packet is removed from the queue, should the RTCRtpSender or RTCRtpReceiver objects need to examine them.

Relevant SSRC fields within selected RTCP packets are summarized within [[!RFC3550]] Section 6.4.1 (Sender Report), Section 6.4.2 (Receiver Report), Section 6.5 (SDES), Section 6.6 (BYE), [[!RFC4585]] Section 6.1 (Feedback Messages), and [[!RFC3611]] Section 2 (Extended Reports).

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 mySender = new RTCRtpSender(myTrack); 
var myPreviousReport = null;

// ... wait a bit
setTimeout(function () {
mySender.getStats().then(function (report) {
processStats(report);
myPreviousReport = report;
});
}, aBit);

function processStats(currentReport) {
if (myPreviousReport === null) return;
// currentReport + myPreviousReport are an RTCStatsReport interface
// compare the elements from the current report with the baseline
for (var i in currentReport) {
var now = currentReport[i]; 
if (now.type != "outboundrtp")
continue;
// get the corresponding stats from the previous report
base = myPreviousReport[now.id];
// base + now will be of RTCRtpStreamStats dictionary type
if (base) {
remoteNow = currentReport[now.associateStatsId];
remoteBase = myPreviousReport[base.associateStatsId];
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;
}
}
}

H.264UC extensions

The extensions defined in this section relate to Microsoft's implementation of the H.264/SVC codec ("H.264UC"), documented in [[MS-H264PF]].

Microsoft statistics extensions

The Microsoft statistics extensions enable retrieval of end-of-call statistics relating to RTCRtpSender, RTCRtpReceiver and RTCIceTransport objects.

Promise<RTCStatsReport> msGetStats()

Gathers stats for the given object and reports the result asynchronously. If the object has not yet begun to send or receive data, the returned stats will reflect this. If the object is in the closed state, the returned stats will reflect the stats at the time the object transitioned to the closed state.

When the msGetStats() method is invoked, the user agent MUST queue a task to run the following steps:

1. Let p be a new promise.

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

3. Start gathering the stats.

4. When the relevant stats have been gathered, return a new RTCStatsReport object, representing the gathered stats.