This document describes the Microsoft Edge ORTC API supported in the Windows 10 Fall Creators Update, as of October 2017.

The Microsoft Edge ORTC API implementation differs from the most recent version of the ORTC API since ORTC has continued to evolve since the development of Microsoft Edge got underway. In addition, Microsoft Edge does not implement every object or method within the ORTC API, and includes some extensions not currently incorporated within the specification. Since both Microsoft Edge and this document represent works-in-progress, the behavior of Microsoft Edge can change substantially from build-to-build. Please bring questions, errors and omissions to the attention of the Edge RTC team (Bernard Aboba, bernarda@microsoft and Angelina Gambo, agambo@microsoft.com).

Overview

Microsoft's Object Real-Time Communications (ORTC) API implementation enables the development of realtime communications applications. Within Microsoft's implementation, the relationship between the application and the objects, as well as between the objects themselves is shown below. Horizontal or slanted arrows denote the flow of media or data, whereas vertical arrows denote interactions via methods and events.

The non-normative ORTC Big Picture Diagram

In the figure above, the RTCRtpSender (Section 6) encodes the track provided as input, which is transported over a RTCDtlsTransport (Section 4) or an RTCSrtpSdesTransport (Section 5). Sending of Dual Tone Multi Frequency (DTMF) tones is supported via the RTCDtmfSender (Section 9).

The RTCDtlsTransport and RTCSrtpSdesTransport utilize an RTCIceTransport (Section 3) to select a communication path to reach the receiving peer's RTCIceTransport, which is in turn associated with an RTCDtlsTransport or RTCSrtpSdesTransport which de-multiplexes media to the RTCRtpReceiver (Section 7). The RTCRtpReceiver then decodes media, producing a track which is rendered by an audio or video tag.

Several other objects also play a role. The RTCIceGatherer (Section 2) gathers local ICE candidates for use by a single RTCIceTransport object.

Edge Interop Note: Since Microsoft Edge does not implement the data channel, the RTCDataChannel and RTCSctpTransport objects are not supported.

Remaining sections of the specification fill in details relating to RTP capabilities and parameters, operational statistics and compatibility with the WebRTC 1.0 API. RTP dictionaries are described in Section 8, the Statistics API is described in Section 10, Microsoft extensions related to the H.264UC codec [[MS-H264PF]] and statistics are described in Section 11, an event summary is provided in Section 12, a list of error codes is provided in Section 13 and WebRTC 1.0 compatibility issues are discussed in Section 14.

Complete examples are provided in Section 15.

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.

The RTCIceGatherer Object

The RTCIceGatherer gathers local host, server reflexive and relay candidates, as well as enabling the retrieval of local Interactive Connectivity Establishment (ICE) parameters which can be exchanged in signaling.

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.

Edge Interop Note: In the Microsoft Edge implementation, an RTCIceGatherer instance can only be associated to a single RTCIceTransport object. As a result, forking scenarios are not supported. The RTCIceGatherer prunes local candidates when its associated RTCIceTransport object enters the "completed" state.

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

The RTCIceParameters Object

The RTCIceParameters object 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.

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.

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.

The RTCIceProtocol

The RTCIceProtocol includes the protocol of the ICE candidate.

udp

A UDP candidate, as described in [[!RFC5245]].

tcp

A TCP candidate, as described in [[!RFC6544]].

The RTCIceTcpCandidateType

The RTCIceTcpCandidateType includes the type of the ICE TCP candidate, as described in [[!RFC6544]]. Browsers MUST gather active TCP candidates and only active TCP candidates. Servers and other endpoints MAY gather active, passive or so candidates.

active

An active TCP candidate is one for which the transport will attempt to open an outbound connection but will not receive incoming connection requests.

passive

A passive TCP candidate is one for which the transport will receive incoming connection attempts but not attempt a connection.

so

An so candidate is one for which the transport will attempt to open a connection simultaneously with its peer.

The RTCIceCandidateType

The RTCIceCandidateType includes the type of the ICE candidate.

host

A host candidate.

srflx

A server reflexive candidate.

prflx

A peer reflexive candidate.

relay

A relay candidate.

dictionary RTCIceCandidateComplete

RTCIceCandidateComplete is a dictionary signifying 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.

dictionary RTCIceGatherOptions

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

dictionary MSPortRange

unsigned short min

Beginning of the port range.

unsigned short max

End of the port range.

enum RTCIceGatherPolicy

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

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.

An example of an array of RTCIceServer objects supporting the STUN and TURN standards:

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

An example of an array of RTCIceServer objects supporting [[MS-TURN]]:

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

Edge Interop Note: Inclusion of the MSTURN or MSTURN-V2 URI triggers use of a proprietary TURN variant described in [[MS-TURN]], as well as proprietary ICE behavior described in [[MS-ICE]] and [[MS-ICE2]]. The MSTURN or MSTURN-V2 URI should therefore not be used in scenarios requiring interoperability with other browsers. The STUN URI is not currently supported.

(DOMString or sequence<DOMString>) urls

STUN or TURN URI(s) as defined in [[!RFC7064]] and [[!RFC7065]] or other URI types (such as the MSTURN URI, described in [[MS-TURN]]).

DOMString username

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

DOMString credential

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

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');
  }
}
 

The RTCIceTransport Object

The RTCIceTransport includes information relating to Interactive Connectivity Establishment (ICE).

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.

Edge Interop Note: The Microsoft Edge ICE implementation only supports regular nomination. In connectivity checks that it sends, Edge will only set the USE-CANDIDATE flag for the selected pair. Also, Edge will only respond to the first connectivity check setting the USE-CANDIDATE flag, and will ignore all subsequent connectivity checks with the USE-CANDIDATE flag set.

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.

enum RTCIceComponent

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

enum RTCIceRole

RTCIceRole contains the current role of the ICE transport.

controlling

controlling state

controlled

controlled state

enum RTCIceTransportState

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.

Edge Interop Note: The Microsoft Edge ORTC API implementation does not support the "failed" state, which is included in both the WebRTC 1.0 API as well as recent drafts of the ORTC API. One implication of this is that RTCIceTransport objects transition to the "closed" state under the conditions that would normally result in a transition to "failed".

The non-normative ICE state transitions are:

The non-normative ICE State Transition Diagram

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.

dictionary RTCIceCandidatePair

The RTCIceCandidatePair contains the currently selected ICE candidate pair.

RTCIceCandidate local

The local ICE candidate.

RTCIceCandidate remote

The remote ICE candidate.

The RTCDtlsTransport Object

The RTCDtlsTransport object includes information relating to Datagram Transport Layer Security (DTLS) transport.

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.

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

Sequence of fingerprints.

The RTCDtlsFingerprint Object

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.

enum RTCDtlsRole

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.

enum RTCDtlsTransportState

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.

Edge Interop Note: The Microsoft Edge ORTC API implementation does not support the "failed" state, which is proposed for inclusion in the WebRTC 1.0 API as well as the ORTC API. One implication of this is that RTCDtlsTransport objects transition to the "closed" state under the conditions that would normally result in a transition to "failed".

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

The RTCSrtpSdesTransport Object

The RTCSrtpSdesTransport includes information relating to SRTP/SDES transport [[RFC4568]]. Details relating to configuration of Microsoft's implementation of SRTP/SDES are described in [[MS-SDPEXT]].

SRTP/SDES support is forbidden by the IETF RTCWEB security specifications. To conform to this requirement, support for SRTP/SDES will be removed from Microsoft Edge in the future. Therefore, applications also need to support DTLS/SRTP so they will continue to function once SRTP/SDES support is removed.

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.

dictionary RTCSrtpSdesParameters

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

dictionary RTCSrtpKeyParam

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.

Edge Interop Note: Limitations of the Microsoft Edge SRTP/SDES implementation are described in [[MS-SDPEXT]] Extion 3.1.5.1. In Microsoft Edge, the value of 'lifetime' is ignored and is set internally to 2^31. 'mki-value' is defined in [[!RFC4568]] Section 9.2 as a string containing up to 128 decimal digits. However, the only supported value of 'mkiLength' is 1, so that Microsoft Edge only supports values of 'mki-value' from 0 to 255.

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

The RTCRtpSender Object

The RTCRtpSender includes information relating to the RTP sender.

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.

Edge Interop Note: The Microsoft Edge ORTC API implementation requires use of RTP/RTCP multiplexing with RTCDtlsTransport objects. Therefore only a single RTCDtlsTransport instance can be associated to an RTCRtpSender instance. RTP/RTCP non-mux is supported for RTCSrtpSdesTransport objects. Only a single RTCSrtpSdesTransport object is required to handle both RTP and RTCP.

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

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.

The RTCRtpReceiver Object

The RTCRtpReceiver includes information relating to the RTP receiver.

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.

Edge Interop Note: The Microsoft Edge ORTC API implementation requires use of RTP/RTCP multiplexing with RTCDtlsTransport objects. Therefore only a single RTCDtlsTransport instance can be associated to an RTCRtpReceiver instance. RTP/RTCP non-mux is supported for RTCSrtpSdesTransport objects. Only a single RTCSrtpSdesTransport object is required to handle both RTP and RTCP.

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.

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.

dictionary RTCRtpContributingSource

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

Dictionaries related to Rtp

dictionary RTCRtpCapabilities

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

dictionary RTCRtcpFeedback

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

dictionary RTCRtpCodecCapability

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.

Edge capabilities

This section describes the capabilities supported by the Microsoft Edge ORTC API implementation. These include capabilites relating to codecs, RTCP feedback, Retransmission (RTX)[[!RFC4588]], header extensions and Forward Error Correction (FEC).

As noted in [[!RFC7874]], the G.711, DTMF [[!RFC4733]], Opus [[!RFC6176]][[!RFC7587]] and Comfort Noise (CN) [[!RFC3389]] codecs are mandatory-to-implement in WebRTC. The Microsoft Edge ORTC implementation supports the G.711, DTMF, CN, Opus and SILK [[SILK]] audio codecs. G.722 is supported on ARM-based devices only.

As noted in [[!RFC7742]], the H.264 [[!RFC6184]] and VP8 [[!RFC6386]][[!RFC7741]] video codecs are mandatory-to-implement in WebRTC. Microsoft Edge currently supports the H.264UC video codec [[MS-H264PF]] which is based on H.264/SVC [[RFC6190]]. Work on support for H.264/AVC is in progress.

The capabilities of codecs supported by Microsoft Edge are described below.

G.711

Since G.711 is an audio codec there is no support for multi-stream transport or temporal or spatial scalability. Only mono operation is supported (numChannels set to 1). As noted in [[!RFC3551]] Section 6, G.711 has been assigned static payload types for the PCMU and PCMA variants, which Microsoft Edge provides as the preferred payload type.

The Dominant Speaker History Notification (dsh) application RTCP feedback message allows a mixer to provide dominant speaker history. The packet format is described in [[MS-RTP]] Section 2.2.12.3, and RTCP feedback messages supported by Edge (including dsh) are described in [[MS-SDPEXT]] Section 3.1.5.30.2. Since this application RTCP feedback message is only useful when communicating with a Skype for Business (SfB) mixer, in other situations this proprietary feedback message should not be configured within RTCRtpParameters passed as an argument in send() or receive().

Capabilities

{
  "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
}
   

G.722

The G.722 audio codec does not include any parameters or options in its capabilities. Since it is an audio codec there is no support for multi-stream transport or temporal or spatial scalability. As noted in [[!RFC3551]] Section 6, G.722 has been assigned a static payload type, which Microsoft Edge provides as the preferred payload type.

While G.722-stereo is described in [[MS-RTP]] Section 2.2.1.1 and [[MS-SDPEXT]] Section 3.5.1.3, the G.722 implementation in Edge only supports mono (numChannels set to 1).

Capabilities

{
  "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
}
   

Comfort Noise

The Comfort Noise (CN) audio codec does not include any parameters or options in its capabilities and settings. Since it is an audio codec, it does not support multi-stream transport or temporal or spatial scalability. Only mono operation is supported (numChannels set to 1). clockRate values of 8000 and 16000 are supported. As noted in [[!RFC3389]], CN has been assigned a static payload type for a clockRate value of 8000, which Microsoft Edge provides as the preferred payload type. For a clockRate value of 16000, Microsoft Edge assigns a dynamic payload type.

When CN is configured for use along with the G.711, G.722 and SILK codecs, CN clockRate is set to 8000. Since the Microsoft Edge implementation of Opus does not support Discontinuous Transmission (DTX), it is possible (though not advisable if interoperability is desired) to use CN along with Opus, in which case the CN value of clockRate to 16000 would be configured.

Capabilities

{
  "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
}
   

DTMF

The DTMF audio codec only includes a single parameter in its capabilities, as noted below. Since it is a mono audio codec, only a single channel is supported and it does not support multi-stream transport or temporal or spatial scalability. As noted in [[!RFC4733]] DTMF utilizes a dynamic payload type so that Microsoft Edge assigns a preferred payload type in the dynamic range.

As noted in [[MS-DTMF]], DTMF cannot be used with the Microsoft implementation of Redundant Audio Data [[MS-RTPRADEX]]. The Microsoft Edge implementation of DTMF supports events 0-15, as described in [[!RFC4733]].

The single capability and setting supported by DTMF is defined in [[!RFC4733]] Section 2.4:

Property Name Values Notes
events DOMString An indication of what telephony events are supported (or configured). Events are listed as one or more comma-separated elements. Each element can be either a single integer providing the value of an event code or an integer followed by a hyphen and a larger integer, presenting a range of consecutive event code values. The list does not have to be sorted. No white space is allowed in the argument. The union of all of the individual event codes and event code ranges designates the complete set of event numbers supported by the implementation.

Capabilities

{
  "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
}
   

Opus

The Microsoft Edge implementation of Opus does not support any parameters or options in Opus capabilities. While [[!RFC7587]] Section 7 describes Opus settings such as stereo, useinbandfec and usedtx, the Microsoft Edge implementation of Opus currently only supports mono operation, cannot support Discontinous Operation (DTX) and does not support inband FEC. While it is possible to configure external FEC (RED) for use with Opus to enhance robustness (distance of 3 is supported versus a distance of 1 for inband FEC), this will not interoperate with other Opus implementations. Interoperability issues may also be experienced if CN is configured to provide voice activity detection.

Since it is an audio codec, Opus does not support multi-stream transport or temporal or spatial scalability. While a numChannels value of 2 is supported, currently the numChannels value does not affect Opus codec operation (only mono is supported, regardless of the value of numChannels). Since Opus utilizes a dynamic payload type Microsoft Edge assigns a preferred payload type in the dynamic range. Currently clockRate can only be set to 48000.

Capabilities

{
  "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
}
   

SILK

For the SILK audio codec, Microsoft Edge does not support any parameters or options within the cabilities. Since it is an audio codec, SILK does not support multi-stream transport or temporal or spatial scalability. Only mono operation is supported (numChannels set to 1), along with clockRate values of 8000 and 16000. Since SILK utilizes a dynamic payload type Microsoft Edge assigns a preferred payload type in the dynamic range.

SILK settings are described in [[MS-SDPEXT]] Section 3.1.5.3. This includes a discussion of 8000 and 16000 clock rates, as well as the usedtx and useinbandfec settings. However, neither inband FEC or DTX is configurable in Microsoft Edge, although external FEC (RED) and CN may be configured.

Capabilities

{
  "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
}
   

RED

For use with audio codecs, Microsoft Edge supports Redundant Audio Data (RED) [[!RFC2198]] with extensions described in [[MS-RTPRADEX]]. Since it is only for use with audio, RED does not support multi-stream transport or temporal or spatial scalability. Only a single channel is supported. RED can be used to protect the G.711, G.722, SILK, CN and Opus payload types. When RED is configured, it is used to protect all configured audio codecs using only a single dynamically allocated RED payload type. There are no configuration parameters to set.

Edge Interop Note: As noted in [[MS-RTPRADEX]], within Microsoft's implementation of RED, only a single block of redundant audio data is supported, along with a block of primary data. The primary audio block and redundant audio block MUST use the same codec. In addition to advertising RED as an audio codec, Microsoft Edge capabilities also include RED as a mechanism for carriage of Forward Error Correction (FEC), since FEC is provided in the redundant audio data block, with a maximum distance of 3 (e.g. "fecMechanisms":["RED"]"). Since the FEC mechanism utilized with RED is proprietary, RED should not be configured within RTCRtpParameters when interoperation with other WebRTC implementations is desired.

Capabilities

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

H.264UC

Microsoft Edge supports the H.264UC [[MS-H264PF]] video codec, along with an end-to-end Forward Error Correction (FEC) scheme. For both H.264UC and FEC, Microsoft Edge assigns a preferred payload type in the dynamic range.

Capabilities

Microsoft Edge returns the example RTCRtpCapabilities object below in response to a call to getCapabilities("video"). H.264UC supports a maximum of 3 temporal layers using multi-stream transport, along with spatial simulcast.

The H.264UC codec utilizes MRST transport, along with packetization-mode 1. Temporal scalability (a maximum of 3 layers) and spatial simulcast (a maximum of 2 layers) are automatically enabled and the encoding is dynamically adjusted based on network conditions. As a result, rtcpFeedback, parameters and options SHOULD be configured as they are provided in the RTCRtpCapabilities object shown below. Since H.264UC does not support SRST transport or spatial scalability, svcMultiStreamSupport MUST be set to true and maxSpatialLayers MUST be set to 0. Note that setting maxTemporalLayers does not have an effect.

{
  "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": []
}
   

Edge Interop Note: H.264UC supports an end-to-end Forward Error Correction (FEC) scheme known as "ULPFECUC", described in [[MS-SDPEXT]] 3.1.5.3. Configuration of "ULPFECUC" is recommended when H.264UC is configured since this improves resilience against packet loss. For resilience, it is also recommended that the x-pli and src RTCP feedback messages be configured along with H.264UC. The x-pli RTCP feedback message is described in [[MS-RTP]] Section 2.2.12.1; it differs from the standard PLI message defined in [[!RFC4585]] Section 6.3.1 in that it contains only one Feedback Control Information (FCI) field.

There are no configurable settings for "ULPFECUC", and when using it, the fecMechanisms attribute is set to null as noted above. The "src" proprietary RTCP feedback message advertised as capability corresponds to the Video Source Request (VSR) RTCP feedback message described in [[MS-RTP]] Section 2.2.12.2.

H.264

H.264/AVC is on by default in Windows Insider preview. Microsoft Edge assigns a preferred payload type in the dynamic range. Currently simulcast is not supported for H.264/AVC. The following capabilities are supported for H.264/AVC, as described in [[RFC6184]] Section 8.1, and [[!RFC7742]] Section 6.2:

Property Name Values Receiver/Sender Notes
profile-level-id unsigned long Receiver/Sender This parameter describes the maximum capability of the decoder (for an RTCRtpReceiver) and an encoder (for an RTCRtpSender). Microsoft Edge currently advertises a value of "42c02a" for this capability.
packetization-mode sequence<unsigned short> Receiver/Sender A sequence of unsigned shorts, each ranging from 0 to 2, indicating supported packetizationMode values. As noted in [[!RFC7742]] Section 6.2, support for packetization-mode 1 is mandatory. Microsoft Edge only supports a packetization-mode value of 1.
maxMbps, maxFs, maxBr, maxFps unsigned long long Receiver As noted in [[!RFC7742]] Section 6.2, these parameters allow the implementation to specify that the decoder can support certain features of H.264 at higher rates and values than those indicated by profileLevelId. Microsoft Edge currently advertises the following capabilities (and values): maxMbps (3600), maxFs (240), maxBr (208) and maxFps (1500).

The following settings are defined for H.264:

Property Name Values Receiver/Sender Notes
profile-level-id unsigned long Sender This parameter indicates the configuration of the stream to be sent, as noted in [[RFC6184]] Section 8.2.2. It MUST be supported, as noted in [[!RFC7742]] Section 6.2. Microsoft Edge currently will not change the sender encoding based on this setting.
packetization-mode unsigned short Sender An unsigned short ranging from 0 to 2, indicating the packetizationMode value to be used by the sender. Microsoft Edge only supports a packetizationMode value of 1.

Microsoft Edge currently does not permitting setting the maxFs, maxMbps, maxBr or MaxFps values.

Capabilities

Microsoft Edge returns the example RTCRtpCapabilities object below in response to a call to getCapabilities("video").

{
  "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
}
    

VP8

VP8 support is now available within Windows Insider Preview. Microsoft Edge assigns a preferred payload type in the dynamic range. Currently simulcast is not supported for VP8. The following capabilities are supported for VP8, as described in [[RFC7741]] Section 6.1, and [[!RFC7742]] Section 6.1:

Property Name Values Receiver/Sender Notes
max-fr unsigned long Receiver This parameter indicates the maximum frame rate in frames per second that the decoder is capable of decoding.
max-fs unsigned long long Receiver This parameter indicates the maximum frame size in macroblocks that the decoder is capable of decoding.

The following sender settings are supported for VP8:

Property Name Values Receiver/Sender Notes
max-fr unsigned long Sender This parameter indicates the maximum frame rate in frames per second that the decoder is capable of decoding.
max-fs unsigned long long Sender This parameter indicates the maximum frame size in macroblocks that the decoder is capable of decoding.

Capabilities

Microsoft Edge returns the example RTCRtpCapabilities object below in response to a call to RTCRtpReceiver.getCapabilities("video").

{
  "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
}
    

RTX

The following capability is defined for "rtx", as noted in [[!RFC4588]] Section 8.6:

Property Name Values Receiver/Sender Notes
rtx-time unsigned long Sender As defined in [[!RFC4588]], the default time in milliseconds (measured from the time a packet was first sent) that the sender keeps an RTP packet in its buffers available for retransmission.

The "rtx" codec has a single setting exposed in Microsoft Edge:.

Property Name Values Receiver/Sender Notes
apt payloadType Receiver/Sender As defined in [[!RFC4588]], the associated payload type of the original stream being retransmitted. There will be an "rtx" entry in RTCRtpParameters.codecs[] for each media codec that can be retransmitted, each with their own apt parameter.

Capabilities

Microsoft Edge returns the example RTCRtpCapabilities object below in response to a call to RTCRtpReceiver.getCapabilities("video"). Note that multiple RTX codec capabilities are returned, one for each video codec that can be retransmitted.

{
  "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": []
}
    

RED

As defined in [[!RFC2198]] Section 5, "red" has no codec-specific capability parameters.

The following setting is defined for "red", as noted in [[!RFC2198]] Section 5:

Property Name Values Receiver/Sender Notes
payloadTypes sequence<payloadtype> Sender/Receiver A sequence of payload types to be encapsulated in RED.

Ulpfec

As noted in [[RFC5109]], "ulpfec" has no codec-specific capability parameters or settings.

dictionary RTCRtpParameters

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.

dictionary RTCRtpHeaderExtension

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.

dictionary RTCRtpHeaderExtensionParameters

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:

Header Extension Reference Attributes Notes
Absolute Send Time [[ABS-SEND-TIME]],[[REMB]] Section 3 None This extension enables the absolute send time to be conveyed.

enum RTCDegradationPreference

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.

dictionary RTCRtcpParameters

RTCRtcpParameters provides information on RTCP settings.

Edge Interop Note: Microsoft Edge currently does not support the cname attribute, and utilizes the compound attribute instead of the reducedSize attribute (a boolean with the opposite meaning). Also, Microsoft Edge requires that the ssrc attribute be set even when RTCRtpSender object(s) exists from which SSRC information could be obtained. In Microsoft Edge, the ssrc attribute is used not only to fill in fields within RTCP packets that are sent, but also in order to route incoming RTCP packets (see Section 10.4). This is necessary since Microsoft Edge utilizes RTCP APP packets that do not contain the SSRC fields supported by all other RTCP packets, allowing those packets to be routed to the relevant objects for processing. Also note that Microsoft Edge Receiver Report (RR) packets contain extensions documented in [[!MS-RTP]]: the RTCP Profile Specific Extension for Estimated Bandwidth (extension type 0x1, documented in [[!MS-RTP]] Section 2.2.11.1) and the RTCP Profile Specific Extension for Network Congestion Notification (extension type 0xd, documented in [[!MS-RTP]] Section 2.2.11.11).

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.

dictionary RTCRtpCodecParameters

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.

Codec parameters

The capabilities for commonly implemented codecs described in Section 9.4.2, are also used as codec parameters, with RTCRtpCodecCapability.parameters of the receiver used as RTCRtpCodecParameters.parameters of the sender, and RTCRtpCodecCapability.parameters of the sender used as RTCRtpCodecParameters.parameters of the receiver, with the Property Name and Values unchanged.

dictionary RTCRtpEncodingParameters

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.

dictionary RTCRtpFecParameters

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.

dictionary RTCRtpRtxParameters

unsigned long ssrc

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

The RTCDtmfSender Object

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");

Statistics API

The Statistics API enables retrieval of statistics relating to RTCRtpSender, RTCRtpReceiver, RTCDtlsTransport, RTCIceGatherer and RTCIceTransport objects. For detailed information on the Statistics API, consult [[!WEBRTC-STATS]].

Promise<RTCStatsReport> getStats()

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

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.

RTCStatsType DOMString

RTCStatsType is equal to one of the following strings defined in [IANA-TOBE]:

"inboundrtp"

Statistics for the inbound RTP stream. It is accessed via the RTCInboundRTPStreamStats defined in [[!WEBRTC-STATS]] Section 4.2.3. Local inbound RTP statistics can be obtained from the RTCRtpReceiver object; remote inbound RTP statistics can be obtained from the RTCRtpSender object.

"outboundrtp"

Statistics for the outbound RTP stream. It is accessed via the RTCOutboundRTPStreamStats defined in [[!WEBRTC-STATS]] Section 4.2.4. Local outbound RTP statistics can be obtained from the RTCRtpSender object; remote outbound RTP statistics can be obtained from the RTCRtpReceiver object.

"track"

Statistics relating to the MediaStreamTrack object. It is accessed via the RTCMediaStreamTrackStats defined in [[!WEBRTC-STATS]] Section 4.4.2.

"transport"

Transport statistics related to the RTCDtlsTransport object. It is accessed via the RTCTransportStats and RTCCertificateStats defined in [[!WEBRTC-STATS]] Sections 4.6 and 4.9.

"candidatepair"

ICE candidate pair statistics related to RTCIceTransport objects. It is accessed via the RTCIceCandidatePairStats defined in [[!WEBRTC-STATS]] Section 4.8.

"localcandidate"

ICE local candidates, related to RTCIceGatherer objects. It is accessed via the RTCIceCandidateAttributes defined in [[!WEBRTC-STATS]] Section 4.7.

"remotecandidate"

ICE remote candidate, related to RTCIceTransport objects. It is accessed via the RTCIceCandidateAttributes defined in [[!WEBRTC-STATS]] Section 4.7.

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;
}
}
}

Microsoft-specific extensions

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

Send CSRC

The requestSendCSRC method extends the RTCRtpReceiver object, requesting that a source identified by a CSRC be sent to the receiver. This extension is designed for use with the H.264UC codec, which supports an RTCP source request message.

void requestSendCSRC(unsigned long csrc)

Request that the source identified by csrc be sent to the RTCRtpReceiver object.

Source Range

The range extension to RTCRtpEncodingParameters enables an implementation of the H.264UC codec supporting MRST transport to demultiplex layers encoded with a range of SSRCs.

RTCSsrcRange ssrcRange

Associate a range of SSRC values with an RTCRtpReceiver or RTCRtpSender. When present in RTCRtpEncodingParameters passed in a call to to RTCRtpReceiver.receive, this extension tells an RTCRtpReceiver object to demultiplex RTP packets sent by an H.264UC encoder with MRST transport, utilizing a range of SSRCs. When present in RTCRtpEncodingParameters passed in a call to to RTCRtpSender.send, this extension instructs an RTCRtpSender object utilizing an H.264UC encoder to send RTP packets with MRST transport, utilizing a range of SSRCs. [[MS-SDPEXT]] Section 3.1.5.31 describes extensions for synchronization source range allocation.

dictionary RTCSsrcRange

unsigned long min

Beginning of the SSRC range.

unsigned long max

End of the SSRC range.

Microsoft statistics extensions

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

Due to the load placed on the browser, these statistics SHOULD NOT be continuously retrieved and are intended for collection of information on objects in or soon to be entering the "closed" state.

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.

RTCStats Dictionary extension

The Microsoft statistics extension extends the RTCStats dictionary to support new statistics types.

MSStatsType msType

The type of this object.

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

MSStatsType DOMString

MSStatsType is equal to one of the following strings:

"description"

Descriptive information relating to RTCRtpReceiver and RTCRtpSender objects. It is accessed via the MSDescription object. Local descriptive information can obtained from the RTCRtpReceiver and RTCRtpSender objects. Remote descriptive information is not supported.

"localclientevent"

Local client events, relating to RTCRtpReceiver and RTCRtpSender objects. It is accessed via the MSLocalClientEvent object. Local client events can obtained from the RTCRtpReceiver and RTCRtpSender objects. Remote client events are not supported.

"inbound-network"

Inbound network statistics. It is accessed via the MSNetwork object. Local inbound statistics can be obtained from the RTCRtpReceiver object. Remote inbound network statistics are not supported.

"outbound-network"

Outbound network statistics. It is accessed via the MSOutboundNetwork object. Local outbound statistics can be obtained from the RTCRtpSender object. Remote outbound network statistics are not supported.

"inbound-payload"

Statistics for the inbound RTP stream. It is accessed via MSVideoRecvPayload and MSAudioRecvPayload objects. Local inbound statistics can be obtained from the RTCRtpReceiver object. Remote inbound RTP statistics are not supported.

"outbound-payload"

Statistics for the outbound RTP stream. It is accessed via MSVideoSendPayload and MSAudioSendPayload objects. Local inbound statistics can be obtained from the RTCRtpSender object. Remote outbound RTP statistics are not supported.

"transportdiagnostics"

Transport diagostics related to the RTCIceTransport object. It is accessed via the MSTransportDiagnosticsStats object. Local transport diagnostics can be obtained fron the RTCIceTransport object. Remote transport diagnostics are not supported.

enum MSIceType

MSIceType contains information about the media path. It is described in [[MS-QoE]] Section 2.2.1.7 (Ice).

failed

This indicates that the local ICE state machine has failed to find a successful candidate pair.

direct

This indicates that the local candidate within the selected candidate pair is a host candidate.

relay

This indicates that the local candidate within the selected candidate pair is a relay candidate..

Dictionary MSIceWarningFlags

MSIceWarningFlags contains information about the ICE process described in bit flags. It is defined in [[MS-QoE]] Section 2.2.1.7.1, (IceWarningFlags), relating to footnote 57.

boolean turnTcpTimedOut

TURN server is unreachable.

boolean turnUdpAllocateFailed

An attempt to allocate a UDP port on the TURN server failed.

boolean turnUdpSendFailed

An attempt to send UDP on the TURN server failed.

boolean turnTcpAllocateFailed

An attempt to allocate a Transmission Control Protocol (TCP) port on the TURN server failed.

boolean turnTcpSendFailed

An attempt to send TCP on the TURN server failed.

boolean udpLocalConnectivityFailed

UDP local connectivity failed.

boolean udpNatConnectivityFailed

UDP NAT connectivity failed.

boolean udpRelayConnectivityFailed

UDP TURN server connectivity failed.

boolean tcpNatConnectivityFailed

TCP NAT connectivity failed.

boolean tcpRelayConnectivityFailed

TCP TURN server connectivity failed.

boolean connCheckMessageIntegrityFailed

Message integrity failed in connectivity check request.

boolean allocationMessageIntegrityFailed

The message integrity on the response message was incorrect.

boolean connCheckOtherError

Connectivity check request failed because of memory problem or other reasons that prevent sending packets.

boolean turnAuthUnknownUsernameError

TURN Server credentials expired or are unknown.

boolean noRelayServersConfigured

No TURN server configured.

boolean multipleRelayServersAttempted

Multiple TURN servers were attempted for the allocation.

boolean portRangeExhausted

Port range exhausted.

boolean alternateServerReceived

Received alternate TURN server.

boolean pseudoTLSFailure

Pseudo-TLS failure. See [[MS-TURN]] Section 2.1.1.

boolean turnTurnTcpConnectivityFailed

TCP-TCP connectivity checks failed over TURN Server.

boolean useCandidateChecksFailed

Use candidates check failed.

boolean fipsAllocationFailure

Allocation failure due to enforcement of FIPS policy (e.g. SHA-1 not allowed).

Dictionary MSRelayAddress

MSRelayAddress contains IP address related information of the relay server. It is described in [[MS-QoE]] Section 2.2.1.7.1 (RelayAddress).

DOMString relayAddress

The IP address of the relay.

unsigned short port

The port of the relay.

Dictionary MSConnectivity

MSConnectivity contains ICE connectivity information. It is described in [[MS-QoE]] Section 2.2.1.7 (Connectivity).

MSIceType iceType

Information about the media path.

MSIceWarningFlags iceWarningFlags

Information about ICE process described in bitflags.

MSRelayAddress relayAddress

IP address related information of the relay.

Dictionary MSNetworkConnectivityInfo

MSNetworkConnectivityInfo contains information specific to the network connection. It is described in [[MS-QoE]] Section 2.2.1.8 (NetworkConnectivityInfo).

boolean vpn

"True" if user is on VPN, "False" if not.

unsigned long long linkspeed

The link speed of the network interface of the endpoint, in bits per second.

DOMString networkConnectionDetails

Information about the interface type. Valid types include "Other" (an interface type other than Ethernet, WiFi, PPP, Tunnnel or Mobile BB), "Ethernet" (an interface identified as Ethernet by the operating system), "WiFi" (an IEEE 802.11 interface), "PPP" (a PPP interface, such as dialup, PPPoE or VPN), "Tunnel" (a tunnel interface such as a GRE or IPv6 tunnel), or "MobileBB" (a mobile broadband interface such as LTE). ISSUE: are the strings spelled correctly? Is an L2TP or PPTP VPN classified as a PPP or Tunnel interface?

Dictionary MSIPAddressInfo

MSIPAddressInfo contains information on the endpoint addresses. It is defined in [[MS-QoE]] Section 2.2.1.9 (AddrType).

DOMString ipAddr

The IP listening address for the stream in appropriate notation (IPv4 or IPv6).

unsigned short port

The listening port for the stream.

DOMString manufacturerMacAddrMask = ""

The OUI portion of the media access control address address of the network interface adapter associated with the IPAddr.

Dictionary MSDescription

MSDescription contains basic information relating to the endpoint.

MSConnectivity connectivity

ICE connectivity information.

RTCIceProtocol transport

Information on ICE candidate transport.

MSNetworkConnectivityInfo networkconnectivity

Information specific to the network connection.

MSIPAddressInfo localAddr

Internet Protocol (IP) address related information for the reporting endpoint, described in [[MS-QoE]] Section 2.2.1.6.1 (LocalAddr).

MSIPAddressInfo remoteAddr

IP address related information related for the remote endpoint, described in [[MS-QoE]] Section 2.2.1.6.1 (RemoteAddr).

DOMString deviceDevName = ""

This represents the "CaptureDev" (for an RtpReceiver) or a "RenderDev" (for an RtpSender), as described in [[MS-QoE]] Section 2.2.1.6.1.

MSIPAddressInfo reflexiveLocalIPAddr

The IP address from which the Media Relay received the allocate request, described in [[MS-QoE]] Section 2.2.1.6.1 (ReflexiveLocalIPAddress). This address is returned by the Media Relay.

Dictionary MSLocalClientEventBase

MSLocalClientEventBase contains information about the quality events detected by the endpoint. It is described in [[MS-QoE]] Section 2.2.1.29.

float networkReceiveQualityEventRatio

Fraction of the call that the reporting endpoint detected the network was causing poor quality of the audio received.

float networkBandwidthLowEventRatio

Fraction of the call that the reporting endpoint detected the available bandwidth or bandwidth policy was low enough to cause poor quality of the audio sent.

Dictionary MSAudioLocalClientEvent

MSAudioLocalClientEvent contains information about the quality events detected by the endpoint. It is described in [[MS-QoE]] Section 2.2.1.29.

float networkSendQualityEventRatio

Fraction of the call that the reporting endpoint detecteed the network was causing poor quality of the audio sent.

float networkDelayEventRatio

Fraction of the call that the reporting endpoint detected the network delay was significant enough to impact the ability to have real-time two-way communication.

float cpuInsufficientEventRatio

Fraction of the call that the reporting endpoint detected the CPU resources available were insufficient and caused poor quality of the audio sent and received.

float deviceHalfDuplexAECEventRatio

Fraction of the call that the reporting endpoint detected issues and operated the acoustic echo canceller in half-duplex mode, which impacted the ability to have real-time two-way communication.

float deviceRenderNotFunctioningEventRatio

Fraction of the call that the reporting endpoint detected the render device was not working properly.

float deviceCaptureNotFunctioningEventRatio

Fraction of the call that the reporting endpoint detected the capture device was not working properly.

float deviceGlitchesEventRatio

Fraction of the call that the reporting endpoint detected glitches or gaps in the audio played or captured that caused poor quality of the audio being sent or received.

float deviceLowSNREventRatio

Fraction of the call that the reporting endpoint detected low speech to noise level that caused poor quality of the audio being sent.

float deviceLowSpeechLevelEventRatio

Fraction of the call that the reporting endpoint detected low speech level that caused poor qualitiy of the audio being sent.

float deviceClippingEventRatio

Fraction of the call that the reporting endpoint detected clipping in the captured audio that caused poor quality of the audio being sent.

float deviceEchoEventRatio

Fraction of the call that the reporting endpoint detected echo that caused poor quality of the audio being sent.

float deviceRenderZeroVolumeEventRatio

Fraction of the call that device render volume is set to 0.

float deviceRenderMuteEventRatio

Fraction of the call that device render is muted.

unsigned long deviceMultipleEndpointsEventCount

Number of times during the call that the reporting endpoint detected mutliple endpoints in the same room or acoustic environment.

unsigned long deviceHowlingEventCount

Number of times during the call that the reporting endpoint detected two or more endpoints in the same room or acoustic environment that caused poor quality audio in the form of howling or screeching audio.

Dictionary MSJitter

MSJitter contains metrics related to jitter. It is described in [[MS-QoE]] Section 2.2.1.27 (Jitter).

unsigned long interArrival

The average inter-arrival jitter, as specified in [[!RFC3550]] Section 6.4.1, in ms.

unsigned long interArrivalMax

The maximum inter-arrival jitter, as specified in [[!RFC3550]] Section 6.4.1, in ms.

float interArrivalSD

The standard deviation of inter-arrival jitter, as specified in [[!RFC3550]] Section 6.4.1, in ms.

Dictionary MSDelay

MSDelay contains metrics related to delays. It is described in [[MS-QoE]] Section 2.2.1.26 (Delay).

unsigned long roundTrip

The average network propagation round-trip time computed as specified in [[!RFC3550]] Section 6.4.1, in ms.

unsigned long roundTripMax

The maximum network propagation round-trip time computed as specified in [[!RFC3550]] Section 6.4.1, in ms.

Dictionary MSPacketLoss

MSPacketLoss contains metrics related to packet loss. It is described in [[MS-QoE]] Section 2.2.1.24 (PacketLoss).

float lossRate

The average fraction lost, as specified in [[!RFC3550]] Section 6.4.1, computed over the duration of the session.

float lossRateMax

The maximum fraction lost, as specified in [[!RFC3550]] Section 6.4.1, computed over the duration of the session.

Dictionary MSUtilization

MSUtilization contains metrics related to network utilization. It is described in [[MS-QoE]] Section 2.2.1.23 (Utilization).

unsigned long packets

Number of Real-Time Transport Protocol (RTP) packets sent in the session.

unsigned long bandwidthEstimation

Estimated one way available bandwidth of the stream at the end of the session in bits/second.

unsigned long bandwidthEstimationMin

Minimal estimated one way available bandwidth of the stream at the end of the session in bits/second.

unsigned long bandwidthEstimationMax

Maximum estimated one way available bandwidth of the stream at the end of the session.

unsigned long bandwidthEstimationStdDev

Standard deviation of estimated one way available bandwidth of the stream at the end of the session.

unsigned long bandwidthEstimationAvg

Average estimated one way available bandwidth of the stream at the end of the session.

Dictionary MSNetwork

MSNetwork contains network-based metrics. It is described in [[MS-QoE]] Section 2.2.1.12 (Network).

MSJitter jitter

Jitter-related metrics.

MSDelay delay

Delay-related metrics.

MSPacketLoss packetLoss

Packet loss related metrics.

MSUtilization utilization

Utilization related metrics.

Dictionary MSOutboundNetwork

MSOutboundNetwork contains additonal information on outband bandwidth, in addition to the information provided in the MSNetwork base class. It is described in [[MS-QoE]] Section 2.2.1.5.1.

unsigned long appliedBandwidthLimit

The bandwidth limit applied for sending media in bits/second.

Dictionary MSPayloadBase

MSPayloadBase is the base object containing payload information. It is described in [[MS-QoE]] Section 2.2.1.15.

DOMString payloadDescription

Codec name, as specified in [[MS-SDPEXT]] Section 3.1.5.3 or [[!RFC3551]] Section 6.

Dictionary MSAudioRecvSignal

MSAudioRecvSignal contains information relating to the audio signal. It is described in [[MS-QoE]] Section 2.2.1.28 (Signal).

float initialSignalLevelRMS

The root-mean-square of the received signal for the first 30 seconds of the call.

long recvSignalLevelCh1

Average energy level of received audio classified as mono speech, or left channel of stereo speech, in dB.

long recvNoiseLevelCh1

Average energy level of received audio classified as noise, mono signal or the left channel of stereo signal, in dB.

float renderSignalLevel

Average render speech level after dynamic range compression or analog gain control is applied, in dBo.

float renderNoiseLevel

Average render noise level after dynamic range compression or analog gain control is applied, in dBo.

float renderLoopbackSignalLevel

Average level of speaker loopback signal (after any device offload effects have been applied), in dBo.

Dictionary MSAudioSendSignal

MSAudioSendSignal contains information relating to the audio signal being sent. It is described in [[MS-QoE]] Section 2.2.1.28.

long noiseLevel

The average energy level of received or sent audio classifed as noise, in dB.

long sendSignalLevelCh1

Average energy level of sent audio classified as mono speech, or left channel of stereo speech, in dB.

long sendNoiseLevelCh1

Average noise level of sent audio classified as mono speech, or left channel of stereo speech.

Dictionary MSAudioSendPayload

MSAudioSendPayload contains information relating to audio payloads being sent. It is described in [[MS-QoE]] Section 2.2.1.14.

unsigned long samplingRate

Audio sample rate in samples/second.

MSAudioSendSignal signal

Information relating to the audio signal being sent.

boolean audioFECUsed

"True means that audio forward error correction (FEC) was used at some point during the call. "False" means that no audio FEC was used during the call. Described in [[MS-QoE] Section 2.2.1.14.1.

float sendMutePercent

Percentage of session duration where the client was muted. Described in [[MS-QoE]] Section 2.2.1.14.1.

Dictionary MSVideoResolutionDistribution

MSVideoResolutionDistribution contains metrics representing the distribution of video resolutions. It is described in [[MS-QoE]] Section 2.2.1.17.

unsigned long cifQuality

The percentage of the duration of a call that is using the CIF resolution (0-100).

unsigned long vgaQuality

The percentage of the duration of the call that is using the VGA resolution (0-100).

unsigned long h720Quality

The percentage of the duration of the call that is using the HD720 resolution (0-100).

unsigned long h1080Quality

The percentage of the duration of the call that is using the HD1080 resolution (0-100).

unsigned long h1440Quality

The percentage of the duration of the call that is using the HD1440 resolution (0-100).

unsigned long h2160Quality

The percentage of the duration of the call that is using the HD2160 resolution (0-100).

Dictionary MSVideoPayload

MSVideoPayload contains information about video-based payload metrics. It is described in [[MS-QoE]] Section 2.2.1.15.

DOMString resolution

Report video resolution in pixels, in the string format of Width x Height without spaces, for example "640x480".

unsigned long videoBitRateAvg

Average bit rate, or bits per second, sent or received for a video stream, computed over the duration of the session. This includes raw video and transport bits.

unsigned long videoBitRateMax

Maximum bit rate, or bits per second, sent or received for a video stream, computed over the duration of the session.

float videoFrameRateAvg

Average frames per second sent or received for a video stream, computed over the duration of the session.

float videoPacketLossRate

The average fraction lost, as specified in [[!RFC3550]] Section 6.4.1, computed over the duration fo the session.

float durationSeconds

The received video aggregated total duration in seconds. Defined in [[MS-QoE]] on page 128.

Dictionary MSVideoSendPayload

MSVideoSendPayload contains information relating to video-based payload metrics. It is defined in [[MS-QoE]] Section Section 2.2.1.15.

float sendFrameRateAverage

Average frames per second sent for all video streams, computed over the duration of the session.

unsigned long sendBitRateMaximum

The maximum bandwidth actually sent for all video streams, computed over the duration of the session.

unsigned long sendBitRateAverage

The average bandwidth actually sent for all video streams, computed over the duration of the session.

unsigned long sendVideoStreamsMax

The maximum number of video streams, active during any one second interval, computed over the duration of the session.

unsigned long sendResolutionWidth

The maximum video image width received for all video streams, computed over the duration of the session.

unsigned long sendResolutionHeight

The maximum video image height sent for all video streams, computed over the duration of the session.

enum MSIceAddrType

MSIceAddrType describes how an ICE candidate was obtained.

os

A host candidate.

stun

A server-reflexive candidate.

turn

A relay candidate.

uPnP

A candidate obtained via uPnP. This candidate type is not supported in Microsoft Edge.

isa-proxy

A candidate obtained via an ISA proxy. This candidate type is not supported in Microsoft Edge.

peer-derived

A peer-reflexive candidate.

Dictionary MSNetworkInterfaceType

MSNetworkInterfaceType contains information on interface types disabled by browser privacy policy.

boolean interfaceTypeEthernet

An interface identified as "Ethernet" by the operating system.

boolean interfaceTypeWireless

An IEEE 802.11 interface.

boolean interfaceTypePPP

A PPP interface (dialup, PPPoE or VPN).

boolean interfaceTypeTunnel

A Tunnel interface (e.g. VPN or IPv6 tunnels).

boolean interfaceTypeWWAN

A wireless WWAN interface.

Dictionary MSTransportDiagnosticsStats

MSTransportDiagnosticsStats contains metrics relating to connectivity.

DOMString baseAddress

Local IP address of interface used for allocating relay candidates.

DOMString localAddress

Local interface IP address used for media flow at end of connectivity checks.

DOMString localSite

Field identifies the location of the user. If relay allocations are successful this field will hold the server reflexive address IP. (external NAT mapped address). If not one of the local interface IP address.

DOMString networkName

Network name that the user endpoint is connected to.

DOMString remoteAddress

IP address of remote endpoint to which media will be sent at end of connectivity checks.

DOMString remoteSite

Field identifies the location of the remote endpoint. If relay allocations are successful this field will hold the server reflexive address IP. (external NAT mapped address) If not one of the remote local interface IP address.

DOMString localMR

If local relay allocation is successful this field will hold the IP address of the media relay allocated candidate. If relay allocation has failed, this field will hold the address of the configured media relay server.

DOMString remoteMR

IP address of the TURN candidate gathered by the remote endpoint.

MSIceWarningFlags iceWarningFlags

Flags for diagnosing connectivity failures.

unsigned short portRangeMin

Lowest port that will be used for the media sessions.

unsigned short portRangeMax

Highest port that will be used for the media sessions.

unsigned short localMRTCPPort

Allocated TCP port on the media relay server.

unsigned short remoteMRTCPPort

Allocated TCP port on the media relay server of the peer endpoint.

unsigned long stunVer

Version of STUN selected for connectivity checks.

unsigned long numConsentReqSent

Number of ICE consent requests sent.

unsigned long numConsentReqReceived

Number of ICE consent requests received.

unsigned long numConsentRespSent

Number of ICE consent responses sent.

unsigned long numConsentRespReceived

Number of ICE consent responses received.

MSNetworkInterfaceType interfaces

Interface types available and used for connectivity checks.

MSNetworkInterfaceType baseInterface

Interface type used for allocating relay candidates.

RTCIceProtocol protocol

Protocol used for media flow.

MSNetworkInterfaceType localInterface

Local interface type selected for media flow at end of connectivity checks.

MSIceAddrType localAddrType

Candidate type used for media flow at end of connectivity checks.

MSIceAddrType remoteAddrType

Candidate type of remote endpoint selected by connectivity checks.

RTCIceRole iceRole

ICE role for connectivity checks.

boolean rtpRtcpMux

Whether RTP/RTCP mux is in use. 1=> enabled.

unsigned long allocationTimeInMs

The time elapsed in ICE candidate allocation, in ms.

DOMString msRtcEngineVersion

The version of the RTC Engine in use.

Dictionary MSAudioRecvPayload

MSAudioRecvPayload contains information relating to audio reception. It is defined in [[MS-QoE]] Section 2.2.1.14.

unsigned long samplingRate

Samples per second.

MSAudioRecvSignal signal

Metrics regarding signal level and noise.

float packetReorderRatio

Ratio of packets received that were out of sequence during the session.

long packetReorderDepthAvg

Average of the number of packets between when the current packet and the out-of-sequence packet was received.

long packetReorderDepthMax

Maximum of the number of packets between when the current packet and the out-of-sequence packet was received.

float burstLossLength1

Ratio of lost single lost packet over the total number of packets for the session.

float burstLossLength2

Ratio of two consecutive lost packets over the total number of packets for the session.

float burstLossLength3

Ratio of three consecutive lost packets over the total number of packets for the session.

float burstLossLength4

Ratio of four consecutive lost packets over the total number of packets for the session.

float burstLossLength5

Ratio of five consecutive lost packets over the total number of packets for the session.

float burstLossLength6

Ratio of six consecutive lost packets over the total number of packets for the session.

float burstLossLength7

Ratio of seven consecutive lost packets over the total number of packets for the session.

float burstLossLength8OrHigher

Ratio of eight or more consecutive lost packets over the total number of packets for the session.

float fecRecvDistance1

Percentage of session where packets with FEC distance of 1 were received.

float fecRecvDistance2

Percentage of session where packets with FEC distance of 2 were received.

float fecRecvDistance3

Percentage of session where packets with FEC distance of 3 were received.

float ratioConcealedSamplesAvg

Ratio of the number of audio frames with samples generated by packet loss concealment to the total number of audio frames. Described in [[MS-QoE]] Section 2.2.1.12.1.

float ratioStretchedSamplesAvg

Ratio of the number of audio frames with samples that have been stretched to compensate for jitter or loss to the total number of audio frames. Described in [[MS-QoE]] Section 2.2.1.12.1.

float ratioCompressedSamplesAvg

Ratio of the number of audio frames with samples that have been compressed to compensate for jitter or loss to the total number of audio frames. Described in [[MS-QoE]] Section 2.2.1.12.1.

Dictionary MSVideoRecvPayload

MSVideoRecvPayload contains information relating to incoming video. It is defined in [[MS-QoE]] Section 2.2.1.15.1.

float videoFrameLossRate

The average fraction of frames lost on the video receiver side, computer of the duration of the session.

DOMString recvCodecType

Codec name, as specified in [[MS-SDPEXT]] Section 3.1.5.3 or [[!RFC3551]] Section 6 concatenated by resource type. See [[MS-QoE]] Section 2.2.1.15.1.2.

unsigned long recvResolutionWidth

The maximum video image width received for all video streams, computed over the duration of the session.

unsigned long recvResolutionHeight

The maximum video image height received for all video streams, computed over the duration of the session.

MSVideoResolutionDistribution videoResolutions

Metrics representing the distribution of video resolutions.

float recvFrameRateAverage

Average frames per second received for all video streams, computed over the duration of the session.

unsigned long recvBitRateMaximum

The maximum bandwidth received for all video streams, computed over the duration of the session.

unsigned long recvBitRateAverage

The average bandwidth received for all video streams, computed over the duration of the session.

unsigned long recvVideoStreamsMax

The maximum number of video streams received during any one second interval, computed over the duration of the session.

unsigned long recvVideoStreamsMin

The minimum number of video streams received during any one second interval, computed over the duration of the session.

long recvVideoStreamsMode

The most common number ("mode") of video streams received during any one second interval, computed over the duration of the session.

float videoPostFECPLR

Reports packet loss rate after FEC has been applied for video. Aggregated across all video streams and codecs. Value between 0.00 and 1.00.

float lowBitRateCallPercent

Percentage of time of the call where bit rate is 70 kilobits per second or less.

float lowFrameRateCallPercent

Percentage of time of the call where frame rate is less than 7.5 frames per second.

unsigned long reorderBufferTotalPackets

unsigned long recvReorderBufferReorderedPackets

The number of reordered video packets.

unsigned long recvReorderBufferPacketsDroppedDueToBufferExhaustion

The number of video packets dropped due to buffer exhaustion.

unsigned long recvReorderBufferMaxSuccessfullyOrderedExtent

The maximum reorder extent in the case where video packets arrive late and FEC has already recovered this packet.

unsigned long recvReorderBufferMaxSuccessfullyOrderedLateTime

The maximum late time in the case where video packets arrive late and FEC has already recovered this packet.

unsigned long recvReorderBufferPacketsDroppedDueToTimeout

The number of video packets dropped due to time out as they arrive late.

float recvFpsHarmonicAverage

Calculated received FPS using harmonic average.

float recvNumResSwitches

How many times the receiver sees a resolution change.

Event summary

The following events fire on RTCDtlsTransport objects:

Event name Interface Fired when...
error Event The RTCDtlsTransport object has received a DTLS Alert.
dtlsstatechange RTCDtlsTransportStateChangedEvent The RTCDtlsTransportState changed.

The following event fires on RTCSrtpSdesTransport objects:

Event name Interface Fired when...
error Event The RTCSrtpSdesTransport object has encountered an error.

The following events fire on RTCIceTransport objects:

Event name Interface Fired when...
icestatechange RTCIceTransportStateChangedEvent The RTCIceTransportState changed.

The following events fire on RTCIceGatherer objects:

Event name Interface Fired when...
error Event The RTCIceGatherer object has experienced an ICE gathering failure (such as an authentication failure with TURN credentials).
icecandidate RTCIceGatherer A new RTCIceGatherCandidate is made available to the script.

The following events fire on RTCRtpSender objects:

Event name Interface Fired when...
error Event An error has been detected within the RTCRtpSender object. This is not used for programmatic exceptions.

The following event fires on RTCRtpReceiver objects:

Event name Interface Fired when...
error Event An error has been detected within the RTCRtpReceiver object, such as an issue with RTCRtpParameters that could not be detected until media arrival. This is not used for programmatic exceptions.

The following events fire on RTCDTMFSender objects:

Event name Interface Fired when...
tonechange Event The RTCDTMFSender object has either just begun playout of a tone (returned as the tone attribute) or just ended playout of a tone (returned as an empty value in the tone attribute).

Error codes

Below is a table of Edge ORTC API error codes and their meanings.

Error Code Mnemonic Meaning
0xC004E001L E_ORTC_INVALID_ARGUMENT Invalid argument
0xC004E002L E_ORTC_NO_INTERFACE Couldn't find matching interface
0xC004E003L E_ORTC_OUT_OF_MEMORY Out of memory
0xC004E004L E_ORTC_DEVICE_ENUMERATION Device enumeration failed
0xC004E005L E_ORTC_INVALID_STATE Invalid state
0xC004E006L E_ORTC_DEVICE_NOT_READY Device is not ready
0xC004E007L E_ORTC_CHANNEL_UNAVAILABLE Channel is not available
0xC004E008L E_ORTC_UNKNOWN_CODEC Unknown codec
0xC004E009L E_ORTC_UNKNOWN_MEDIA_KIND Unknown media kind
0xC004E00AL E_ORTC_DEVICE_INIT Device initialization failed
0xC004E00BL E_ORTC_CRYPTO Invalid crypto parameters
0xC004E00CL E_ORTC_NOT_IMPLEMENTED Not implemented
0xC004E00DL E_ORTC_RTP_PARAMETER Invalid RTP parameters
0xC004E00EL E_ORTC_ENDPOINT_ALLOCATION_FAIL Transport endpoint allocation failed
0xC004E00FL E_ORTC_DTLS_HANDSHAKE_FAILED DTLS handshake failed

WebRTC 1.0 Compatibility

It is a goal of the ORTC API to provide the functionality of the WebRTC 1.0 API [[WEBRTC10]], as well as to enable the WebRTC 1.0 API to be implemented on top of the ORTC API, utilizing a Javascript "shim" library. This section discusses WebRTC 1.0 compatibility issues.

RTP/RTCP multiplexing

As noted in [[!RTP-USAGE]] Section 4.5, support for RTP/RTCP multiplexing [[!RFC5761]] is mandatory-to-implement in WebRTC. Via the "a=rtcp-mux" line, WebRTC 1.0 implementations can negotiate RTP/RTCP multiplexing. In ORTC API, multiplexing of RTP and RTCP [[!RFC5761]] is enabled by setting RTCRtcpParameters.mux to true (the default) when calling receiver.receive() or sender.send().

Microsoft Edge only allows a single RTCTransport to be specified when constructing an RTCRtpSender or RTCRtpReceiver object. When an RTCDtlsTransport is used in the constructor, RTP/RTCP multiplexing is required.

Microsoft Edge supports both multiplexed and non-multiplexed RTP/RTCP with RTCSrtpSdesTransport objects. To not multiplex RTP and RTCP with an RTCSrtpSdesTransport, construct an associated RTCP RTCIceTransport prior to constructing the RTCSrtpSdesTransport. RTCRtcpParameters.mux is then set to false when receiver.receive() or sender.send() is called. To configure RTP/RTCP multiplexing when constructing an RTCSrtpSdesTransport, do not construct an associated RTCP RTCIceTransport or if one was constructed, call stop() on it. RTCRtcpParameters.mux is then set to true when receiver.receive() or sender.send() is called.

BUNDLE

As noted in [[!RTP-USAGE]] Section 4.4, audio/video multiplexing is mandatory-to-implement in WebRTC, as described in [[!RTP-MULTI-STREAM]]. Via the use of [[!BUNDLE]] it is possible for WebRTC 1.0 implementations to negotiate the multiplexing of audio and video on the same RTP session. The Microsoft Edge ORTC implementation enables bundling of audio and video [[!BUNDLE]] by constructing multiple RTCRtpReceiver and RTCRtpSender objects from the same RTCDtlsTransport or RTCSrtpSdesTransport object.

Voice Activity Detection

[[WEBRTC10]] Section 4.2.4 defines the RTCOfferOptions dictionary, which includes the voiceActivityDetection attribute, which determines whether Voice Activity Detection (VAD) is enabled within the Offer produced by createOffer(). The effect of setting voiceActivityDetection to true is to include the Comfort Noice (CN) codec defined in [[!RFC3389]] within the Offer.

Within ORTC API, equivalent behavior can be obtained by configuring the Comfort Noise (CN) codec within RTCRtpParameters. Relevant considerations are described in Section 8.3.2.3. Currently, the Microsoft Edge implementations of SILK and Opus do not support Discontinuous Operation (DTX).

H.264/AVC

[[RFC6184]] Section 8.1 defines the level-asymmetry-allowed SDP parameter supported by some WebRTC 1.0 API implementations. Within ORTC API, the profileLevelId capability is supported for both the RTCRtpSender and RTCRtpReceiver, and the profileLevelId setting is provided for the RTCRtpSender. Since in ORTC API sender and receiver profileLevelId capabilities are independent and there is no profileLevelId setting for an RTCRtpReceiver, ORTC API assumes that implementations support level asymmetry. Therefore a WebRTC 1.0 API shim library for ORTC API should provide a level-asymmetry-allowed value of 1.

Examples

Simple Peer-to-peer Example

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

   

myCapsToSendParams Example

RTCRtpParameters function myCapsToSendParams (RTCRtpCapabilities sendCaps, RTCRtpCapabilities remoteRecvCaps) {
// Function returning the sender RTCRtpParameters, based on the local sender and remote receiver capabilities.
// The goal is to enable a single stream audio and video call with minimum fuss. 
//
// Steps to be followed: 
// 1. Determine the RTP features that the receiver and sender have in common. 
// 2. Determine the codecs that the sender and receiver have in common.
// 3. Within each common codec, determine the common formats, header extensions and rtcpFeedback mechanisms.
// 4. Determine the payloadType to be used, based on the receiver preferredPayloadType. 
// 5. Set RTCRtcpParameters such as mux to their default values.  
// 6. Return RTCRtpParameters enablig the jointly supported features and codecs.
}

RTCRtpParameters function myCapsToRecvParams (RTCRtpCapabilities recvCaps, RTCRtpCapabilities remoteSendCaps) {
// Function returning the receiver RTCRtpParameters, based on the local receiver and remote sender capabilities.
return myCapsToSendParams(remoteSendCaps, recvCaps);
}

Acknowledgements

Microsoft acknowledges the W3C ORTC Community Group for creating the ORTC API. We would also like to acknowledge Phillipp Hancke, who provided extensive review comments.