This document defines a set of ECMAScript APIs in WebIDL to allow media to be sent and received from another browser or device implementing the appropriate set of real-time protocols. However, unlike the WebRTC 1.0 API, Object Real-Time Communications (ORTC) does not utilize Session Description Protocol (SDP) in the API, nor does it mandate support for the Offer/Answer state machine (though an application is free to choose SDP and Offer/Answer as an on-the-wire signaling mechanism). Instead, ORTC uses "sender", "receiver" and "transport" objects, which have "capabilities" describing what they are capable of doing, as well as "parameters" which define what they are configured to do. "Tracks" are encoded by senders and sent over transports, then decoded by receivers while "data channels" are sent over transports directly.

Overview

Object Real-Time Communications (ORTC) provides a powerful API for the development of WebRTC based applications. ORTC does not utilize Session Description Protocol (SDP) in the API, nor does it mandate support for the Offer/Answer state machine (though an application is free to choose SDP and Offer/Answer as an on-the-wire signaling mechanism). Instead, ORTC uses "sender", "receiver" and "transport" objects, which have "capabilities" describing what they are capable of doing, as well as "parameters" which define what they are configured to do. "Tracks" are encoded by senders and sent over transports, then decoded by receivers while "data channels" are sent over transports directly.

In a Javascript application utilizing the ORTC API, 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
Non-normative ORTC Big Picture Diagram

In the figure above, the RTCRtpSender (Section 5) encodes the track provided as input, which is transported over a RTCDtlsTransport (Section 4). An RTCDataChannel (Section 11) utilizes an RTCSctpTransport (Section 12) which can also be multiplexed over the RTCDtlsTransport. Sending of Dual Tone Multi Frequency (DTMF) tones is supported via the RTCDtmfSender (Section 10).

The RTCDtlsTransport utilizes an RTCIceTransport (Section 3) to select a communication path to reach the receiving peer's RTCIceTransport, which is in turn associated with an RTCDtlsTransport which de-multiplexes media to the RTCRtpReceiver (Section 6) and data to the RTCSctpTransport and RTCDataChannel. 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 one or more RTCIceTransport objects, enabling forking scenarios. The RTCIceTransportController (Section 7) manages freezing/unfreezing (defined in [[!RFC5245]]) and bandwidth estimation. The RTCRtpListener (Section 8) detects whether an RTP stream is received that cannot be delivered to any existing RTCRtpReceiver, providing an onunhandledrtp event handler that the application can use to correct the situation. The RTCQuicTransport (Section 13) utilizes an RTCIceTransport to select a communication path to reach the receiving peer's RTCIceTransport, which is in turn associated with an RTCQuicTransport. An RTCQuicTransport is associated with zero or more RTCQuicStream (Section 14) objects which read data from and write data to RTCQuicStream objects on the remote peer.

Remaining sections of the specification fill in details relating to RTP capabilities and parameters, operational statistics, media authentication via Certificates and Identity Providers (IdP) and compatibility with the WebRTC 1.0 API. RTP dictionaries are described in Section 9, the Statistics API is described in Section 15, the Identity API is described in Section 16, the Certificate API is described in Section 17, privacy and security considerations are described in Section 18, an event summary is provided in Section 19, WebRTC 1.0 compatibility issues are discussed in Section 20, and complete examples are provided in Section 21.

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.

Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL-1]], as this specification uses that specification and terminology.

Implementation of the following interfaces is mandatory: RTCIceGatherer (Section 2), RTCIceTransport (Section 3), RTCDtlsTransport (Section 4), RTCRtpSender (Section 5), RTCRtpReceiver (Section 6), RTCDtmfSender (Section 10), RTCDataChannel (Section 11), RTCSctpTransport (Section 12) and RTCCertificate (Section 17). Since the send and receive methods are mandatory-to-implement, the RTP dictionaries (Section 9) that these methods depend on are also mandatory-to-implement. Mandatory-to-implement statistics are described in Section 15.3.

Implementation of the following interfaces is optional: RTCIceTransportController (Section 7), RTCRtpListener (Section 8), RTCQuicTransport (Section 13), RTCQuicStream (Section 14) and RTCIdentity (Section 16).

Terminology

The EventHandler interface, representing a callback used for event handlers, and the ErrorEvent interface are defined in [[!HTML5]].

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

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

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

The term RTCStatsType is defined in [[!WEBRTC-STATS]].

When referring to exceptions, the terms throw and create are defined in [[!WEBIDL-1]].

The terms fulfilled, rejected, resolved, pending and settled used in the context of Promises are defined in [[!ECMASCRIPT-6.0]].

In this specification the term user agent refers to any implementation; the term browser specifically refers to browser implementations.

Scope

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 a Scalable Video Coding (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. This specification supports SVC codecs that can only utilize SRST transport (such as VP8 and VP9) as well as implementations of codecs (such as H.264/SVC or HEVC) that support SRST transport. Also, sending of simulcast is supported. SVC codecs supporting MRST transport (such as H.264/SVC and HEVC) can also be supported, along with reception of simulcast. However, these features should be considered experimental, since implementation experience is limited.

At the time of publication, there were two ORTC implementations supporting simulcast reception. Since neither implementation supported [[!RFC6051]], mechanisms needed to be provided to handle intermingling of received simulcast streams due to reordering. The ORTC Lib implementation deals with this by utilizing timing heuristics as well as "hidden" receivers for each received simulcast stream, with each "hidden" receiver producing a "hidden" track. The "hidden" tracks are then mixed internally to produce a single MediaStreamTrack RTCRtpReceiver.track.

RTCIceGatherer Interface

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. By enabling an endpoint to use a set of local candidates to construct multiple RTCIceTransport objects, the RTCIceGatherer enables support for scenarios such as parallel forking.

Overview

An RTCIceGatherer instance can be associated to multiple RTCIceTransport objects. The RTCIceGatherer does not prune local candidates until at least one RTCIceTransport object has become associated and all associated RTCIceTransport objects are in the completed or failed 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 the 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.

An RTCIceGatherer object in the closed state can be garbage-collected when it is no longer referenced.

To validate the options argument in the RTCIceGatherer constructor, implementations MUST run the following steps:

  1. Let options be the argument passed in the constructor.

  2. Let servers be the value of options.iceServers.

  3. Let validatedServers be an empty list.

  4. Run the following steps for each element in servers:

    1. Let server be the current list element.

    2. If server.urls is a string, let server.urls be a list consisting of just that string.

    3. For each url in server.urls run the following steps:

      1. Parse the url using the generic URI syntax defined in [[!RFC3986]] and obtain the scheme name. If the parsing based on the syntax defined in [[!RFC3986]] fails, throw a SyntaxError. If the scheme name is not implemented by the browser throw a NotSupportedError. If scheme name is turn or turns, and parsing the url using the syntax defined in [[!RFC7064]] fails, throw a SyntaxError. If scheme name is stun or stuns, and parsing the url using the syntax defined in [[!RFC7065]] fails, throw a SyntaxError.

      2. If scheme name is turn or turns, and either of server.username or server.credential are omitted, then throw an InvalidAccessError.

      3. If scheme name is turn or turns, and server.credentialType is "password", and server.credential is not a DOMString, then throw an InvalidAccessError and abort these steps.

      4. If scheme name is turn or turns, and server.credentialType is "oauth", and server.credential is not an RTCOAuthCredential, then throw an InvalidAccessError and abort these steps.

    4. Append server to validatedServers.

    Let validatedServers be the ICE servers list.

Interface Definition

[ Constructor (RTCIceGatherOptions options), Exposed=Window]
interface RTCIceGatherer : RTCStatsProvider {
    readonly        attribute RTCIceComponent     component;
    readonly        attribute RTCIceGathererState state;
    static sequence<RTCIceServer> getDefaultIceServers ();
    void                      close ();
    void                      gather (optional RTCIceGatherOptions options);
    RTCIceParameters          getLocalParameters ();
    sequence<RTCIceCandidate> getLocalCandidates ();
    RTCIceGatherer            createAssociatedGatherer ();
                    attribute EventHandler        onstatechange;
                    attribute EventHandler        onerror;
                    attribute EventHandler        onlocalcandidate;
};

Constructors

RTCIceGatherer
Parameter Type Nullable Optional Description
options RTCIceGatherOptions

Attributes

component of type RTCIceComponent, readonly

The component-id of the RTCIceGatherer object. In RTCIceGatherer objects returned by createAssociatedGatherer() the value of the component attribute is rtcp. In all other RTCIceGatherer objects, the value of the component attribute is rtp.

state of type RTCIceGathererState, readonly

The current state of the ICE gatherer.

onstatechange of type EventHandler

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

onerror of type EventHandler

This event handler, of event handler event type icecandidateerror, MUST be fired if an error occurs in the gathering of ICE candidates (such as if TURN credentials are invalid).

onlocalcandidate of type EventHandler

This event handler, of event handler event type icecandidate, uses the RTCIceGathererEvent 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.

Methods

getDefaultIceServers

Returns a list of ICE servers that are configured into the browser. A browser might be configured to use local or private STUN or TURN servers. This method allows an application to learn about these servers and optionally use them.

This list is likely to be persistent and is the same across origins. It thus increases the fingerprinting surface of the browser. In privacy-sensitive contexts, browsers can consider mitigations such as only providing this data to whitelisted origins (or not providing it at all.)

Since the use of this information is left to the discretion of application developers, configuring a user agent with these defaults does not per se increase a user's ability to limit the exposure of their IP addresses.

close

Prunes all local candidates, and closes the port. Associated RTCIceTransport objects transition to the disconnected state (unless they were in the failed state). Calling close() when state is closed has no effect.

No parameters.
Return type: void
gather

Gather ICE candidates. If options is omitted, utilize the value of options passed in the constructor. If state is closed, throw an InvalidStateError.

Parameter Type Nullable Optional Description
options RTCIceGatherOptions
Return type: void
getLocalParameters

getLocalParameters() obtains the ICE parameters of the RTCIceGatherer. If state is closed, throw an InvalidStateError.

No parameters.
Return type: RTCIceParameters
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. Prior to calling gather() an empty list will be returned. If state is closed, throw an InvalidStateError.

No parameters.
Return type: sequence<RTCIceCandidate>
createAssociatedGatherer

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

No parameters.
Return type: RTCIceGatherer

RTCIceParameters Dictionary

The RTCIceParameters dictionary includes the ICE username fragment and password and other ICE-related parameters.

dictionary RTCIceParameters {
             DOMString usernameFragment;
             DOMString password;
             boolean   iceLite;
};

Dictionary RTCIceParameters Members

usernameFragment of type DOMString

ICE username fragment.

password of type DOMString

ICE password.

iceLite of type boolean

If only ICE-lite is supported (true) or not (false or unset). Since [[!RTCWEB-TRANSPORT]] Section 3.4 requires browser support for full ICE, iceLite will only be true for a remote peer such as a gateway. getLocalParameters().iceLite MUST NOT be set.

RTCIceCandidate Dictionary

The RTCIceCandidate dictionary includes information relating to an ICE candidate.

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

The RTCIceGatherCandidate provides either an RTCIceCandidate or an RTCIceCandidateComplete indication that candidate gathering is complete.

        typedef (RTCIceCandidate or RTCIceCandidateComplete) RTCIceGatherCandidate;
dictionary RTCIceCandidate {
             required DOMString              foundation;
             required unsigned long          priority;
             required DOMString              ip;
             required RTCIceProtocol         protocol;
             required unsigned short         port;
             required RTCIceCandidateType    type;
             RTCIceTcpCandidateType tcpType;
             DOMString              relatedAddress;
             unsigned short         relatedPort;
};

Dictionary RTCIceCandidate Members

foundation of type DOMString, required

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

priority of type unsigned long, required

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

ip of type DOMString, required

The IP address of the candidate.

protocol of type RTCIceProtocol, required

The protocol of the candidate (udp/tcp).

port of type unsigned short, required

The port for the candidate.

type of type RTCIceCandidateType, required

The type of candidate.

tcpType of type RTCIceTcpCandidateType

The type of TCP candidate. For UDP candidates, this attribute is unset.

relatedAddress of type DOMString

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

relatedPort of type unsigned short

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

RTCIceProtocol Enum

The RTCIceProtocol includes the protocol of the ICE candidate.

enum RTCIceProtocol {
    "udp",
    "tcp"
};
Enumeration description
udp

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

tcp

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

RTCIceTcpCandidateType Enum

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.

enum RTCIceTcpCandidateType {
    "active",
    "passive",
    "so"
};
Enumeration description
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.

RTCIceCandidateType Enum

The RTCIceCandidateType includes the type of the ICE candidate as defined in [[!RFC5245]] section 15.1.

enum RTCIceCandidateType {
    "host",
    "srflx",
    "prflx",
    "relay"
};
Enumeration description
host

A host candidate, as defined in Section 4.1.1.1 of [[!RFC5245]].

srflx

A server reflexive candidate, as defined in Section 4.1.1.2 of [[!RFC5245]].

prflx

A peer reflexive candidate, as defined in Section 4.1.1.2 of [[!RFC5245]].

relay

A relay candidate, as defined in Section 7.1.3.2.1 of [[!RFC5245]].

RTCIceCandidateComplete Dictionary

RTCIceCandidateComplete is a dictionary signifying that all RTCIceCandidates are gathered.

dictionary RTCIceCandidateComplete {
             boolean complete = true;
};

Dictionary RTCIceCandidateComplete Members

complete of type boolean, defaulting to true

This attribute is always present and set to true, indicating that ICE candidate gathering is complete.

RTCIceGathererState Enum

RTCIceGathererState represents the current state of the ICE gatherer.

enum RTCIceGathererState {
    "new",
    "gathering",
    "complete",
    "closed"
};
Enumeration description
new

The object has been created but gather() has not been called.

gathering

gather() has been called, and the RTCIceGatherer is in the process of gathering candidates (which includes adding new candidates and removing invalidated candidates).

complete

The RTCIceGatherer has completed gathering. Events such as adding, updating or removing an interface, or adding, changing or removing a TURN server will cause the state to go back to gathering before re-entering complete once all candidate changes are finalized.

closed

The closed state can only be entered when the RTCIceGatherer has been closed intentionally by calling close(). This is a terminal state.

RTCIceGathererIceErrorEvent

The icecandidateerror event of the RTCIceGatherer object uses the RTCIceGathererIceErrorEvent interface.

        [ Constructor (DOMString type, RTCIceGathererIceErrorEventInit eventInitDict), Exposed=Window]
interface RTCIceGathererIceErrorEvent : Event {
    readonly        attribute RTCIceCandidate? hostCandidate;
    readonly        attribute DOMString        url;
    readonly        attribute unsigned short   errorCode;
    readonly        attribute USVString        statusText;
};

Constructors

RTCIceGathererIceErrorEvent
Parameter Type Nullable Optional Description
type DOMString
eventInitDict RTCIceGathererIceErrorEventInit

Attributes

hostCandidate of type RTCIceCandidate, readonly , nullable

The RTCIceCandidate used to communicate with the STUN or TURN server. On a multihomed system, multiple interfaces may be used to contact the server, and this attribute allows the application to figure out on which one the failure occurred. If the browser is in a privacy mode disallowing host candidates, this attribute will be null.

If use of multiple interfaces has been prohibited for privacy reasons, hostCandidate will be null.

url of type DOMString, readonly , nullable

The url attribute is the STUN or TURN URL identifying the server on which the failure ocurred.

errorCode of type unsigned short, readonly

The errorCode attribute is the numeric STUN error code returned by the STUN or TURN server [[STUN-PARAMETERS]].

If no host candidate can reach the server, errorCode will be set to a value of 701, as this does not conflict with the STUN error code range, and hostCandidate will be null. This error is only fired once per server URL while in the RTCIceGathererState of gathering.

statusText of type USVString, readonly

The STUN reason text returned by the STUN or TURN server [[STUN-PARAMETERS]].

If the server could not be reached, statusText will be set to an implementation-specific value providing details about the error.

The RTCIceGathererIceErrorEventInit dictionary provides information on ICE gathering errors.

        dictionary RTCIceGathererIceErrorEventInit : EventInit {
             RTCIceCandidate hostCandidate;
             DOMString       url;
             required unsigned short  errorCode;
             USVString       errorText;
};

Dictionary RTCIceGathererIceErrorEventInit Members

hostCandidate of type RTCIceCandidate

The RTCIceCandidate used to communicate with the STUN or TURN server.

url of type DOMString

The url attribute is the STUN or TURN URL identifying the server on which the failure ocurred.

errorCode of type unsigned short

The errorCode attribute is the numeric STUN error code returned by the STUN or TURN server [[STUN-PARAMETERS]].

errorText of type USVString

The errorText attribute is the STUN reason text returned by the STUN or TURN server [[STUN-PARAMETERS]].

RTCIceGathererEvent

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

Firing an RTCIceGathererEvent event named e with an RTCIceGatherCandidate candidate and URL url 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.

        [ Constructor (DOMString type, RTCIceGathererEventInit eventInitDict), Exposed=Window]
interface RTCIceGathererEvent : Event {
    readonly        attribute RTCIceGatherCandidate candidate;
    readonly        attribute DOMString?            url;
};

Constructors

RTCIceGathererEvent
Parameter Type Nullable Optional Description
type DOMString
eventInitDict RTCIceGathererEventInit

Attributes

candidate of type RTCIceGatherCandidate, readonly

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.

url of type DOMString, readonly , nullable
The URL of the server from which the candidate was obtained.

The RTCIceGathererEventInit dictionary provides information on the RTCIceGatherCandidate.

dictionary RTCIceGathererEventInit : EventInit {
             RTCIceGatherCandidate candidate;
             DOMString             url;
};

Dictionary RTCIceGathererEventInit Members

candidate of type RTCIceGatherCandidate

The ICE candidate that caused the event.

url of type DOMString
The URL of the server from which the candidate was obtained.

RTCIceGatherOptions Dictionary

RTCIceGatherOptions provides options relating to the gathering of ICE candidates.

dictionary RTCIceGatherOptions {
             RTCIceGatherPolicy     gatherPolicy;
             sequence<RTCIceServer> iceServers;
};

Dictionary RTCIceGatherOptions Members

gatherPolicy of type RTCIceGatherPolicy

The ICE gather policy.

iceServers of type sequence<RTCIceServer>

Additional ICE servers to be configured. Since implementations MAY provide default ICE servers, and applications can desire to restrict communications to the local LAN, iceServers need not be set.

RTCIceGatherPolicy Enum

RTCIceGatherPolicy denotes the policy relating to the gathering of ICE candidates.

enum RTCIceGatherPolicy {
    "all",
    "relay"
};
Enumeration description
all

The RTCIceGatherer MAY gather any type of candidate when this value is specified.

The implementation may still use its own candidate filtering policy in order to limit the IP addresses exposed to the application.
relay

The RTCIceGatherer MUST only gather media relay candidates such as candidates passing through a TURN server.

This can be used to prevent the remote endpoint from learning the user's IP addresses, which may be desired in certain use cases. For example, in a "call"-based application, the application may want to prevent an unknown caller from learning the callee's IP addresses until the callee has consented in some way.

RTCIceCredentialType Enum

RTCIceCredentialType represents the type of credential used by a TURN server.

enum RTCIceCredentialType {
    "password",
    "oauth"
};
Enumeration description
password

The credential is a long-term authentication password, as described in [[!RFC5389]], Section 10.2.

oauth

An OAuth 2.0 based authentication method, as described in [[!RFC7635]]. It uses the OAuth 2.0 Implicit Grant type, with PoP (Proof-of-Possession) Token type, as described in [[!RFC6749]] and [[!OAUTH-POP-KEY-DISTRIBUTION]].

The OAuth Client and the Auhorization Server roles are defined in [[!RFC6749]] Section 1.1.

If [[!RFC7635]] is used in ORTC then the OAuth Client is responsible for refreshing the credential information, and updating the RTCIceGatherer with fresh new credentials before the accessToken expires.

For OAuth Authentication, the RTCIceGatherer requires three pieces of credential information. The credential is composed of a kid, which the RTCIceServer username member is used for, and macKey and accessToken, which are placed in the RTCOAuthCredential dictionary. All of this information can be extracted from the OAuth response parameters, which are received from the Authorization Server. The relevant OAuth response parameters are the "kid", the "key", and the "access_token". These can be used to extract all the necessary credential infromation (the kid, macKey, and accessToken) that are required by the RTCIceGatherer for the Authentication.

The [[!OAUTH-POP-KEY-DISTRIBUTION]] defines alg parameter in Section 4.1 and 6. and describes that if the Authorization Server doesn't have prior knowledge of the capabilities of the client, then the OAuth Client needs to provide information about the RTCIceGatherer HMAC alg capabilities. This information helps the Authorization Server to generate the approriate HMAC key. The HMAC alg defines the input key length, and HMAC algorithm Familly (e.g. SHA), and HMAC algorithm type (e.g. symmetric/asymmetric).

The OAuth Client sends an OAuth Request to the Authorization Server with OAuth param alg and further OAuth related parameters, to get an OAuth Response with the access_token, key, kid, and further OAuth related parameters.

However, this specification uses a simplified alg approach. The length of the HMAC key (RTCOAuthCredential.macKey) MAY be any integer number of bytes greater than 20 (160 bits). This negates the need to query the HMAC Algorithm capabilities of the RTCIceGatherer, and still allows for hash agility as described by [[STUN-BIS]], Section 15.3.

According to [[!RFC7635]] Section 4.1, the HMAC key MUST be a symmetric key.

Currently the STUN/TURN protocols use only SHA-1 and SHA-2 family hash algorithms for Message Integrity Protection, as defined in [[!RFC5389]] Section 15.4, and [[!STUN-BIS]] Section 14.6.

When [[!RFC7635]] is used in ORTC, this specification adds the following additional considerations:

The OAuth Client SHOULD obtain the mac_key by requesting an alg value of HS256. This will result in a 256-bit HMAC key.

HS256 is defined in [[!RFC7518]] Section 3.1. It is recommended here because:

  • The OAuth respose key parameter is received in JWK format according to [[!OAUTH-POP-KEY-DISTRIBUTION]] Section 4.2. JWK's algorithms are normatively registered in the IANA "JSON Web Signature and Encryption Algorithms" registry.
  • STUN/TURN currently use SHA family HMAC algorithms only.
  • The key MUST be symmetric, according to [[!RFC7635]].
  • A 256-bit key is large enough to support all currently defined STUN message integrity attributes.

More details about OAuth PoP Client can be found in [[!OAUTH-POP-KEY-DISTRIBUTION]] Section 4.

More details about Access-Token can be found in [[!RFC7635]], Section 6.2.

RTCOAuthCredential Dictionary

The RTCOAuthCredential dictionary is used to describe the OAuth auth credential information which is used by the STUN/TURN client (inside the RTCIceGatherer) to authenticate against a STUN/TURN server, as described in [[!RFC7635]]. Note that the kid parameter is not located in this dictionary, but in RTCIceServer's username member.

dictionary RTCOAuthCredential {
    required DOMString        macKey;
    required DOMString        accessToken;
};

Dictionary RTCOAuthCredential Members

macKey of type DOMString, required

The "mac_key", as described in [[!RFC7635]], Section 6.2, in a base64-url encoded format. It is used in STUN message integrity hash calculation (as the password is used in password based authentication). Note that the OAuth response "key" parameter is a JSON Web Key (JWK) or a JWK encrypted with a JWE format. Also note that this is the only OAuth parameter whose value is not used directly, but must be extracted from the "k" parameter value from the JWK, which contains the needed base64-encoded "mac_key".

accessToken of type DOMString, required

The "access_token", as described in [[!RFC7635]], Section 6.2, in a base64-encoded format. This is an encrypted self-contained token that is opaque to the application. Authenticated encryption is used for message encryption and integrity protection. The access token contains a non-encrypted nonce value, which is used by the Authorization Server for unique mac_key generation. The second part of the token is protected by Authenticated Encryption. It contains the mac_key, a timestamp and a lifetime. The timestamp combined with lifetime provides expiry information; this information describes the time window during which the token credential is valid and accepted by the TURN server.

An example of an RTCOAuthCredential dictionary is:

{
    macKey: "WmtzanB3ZW9peFhtdm42NzUzNG0=",
    accessToken: "AAwg3kPHWPfvk9bDFL936wYvkoctMADzQ5VhNDgeMR3+ZlZ35byg972fW8QjpEl7bx91YLBPFsIhsxloWcXPhA=="
}

RTCIceServer Dictionary

The RTCIceServer dictionary is used to configure the STUN and/or TURN servers. 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.

dictionary RTCIceServer {
    required (DOMString or sequence<DOMString>) urls;
             DOMString                          username;
             (DOMString or RTCOAuthCredential)     credential;
             RTCIceCredentialType               credentialType = "password";
};

Dictionary RTCIceServer Members

urls of type (DOMString or sequence<DOMString>), required

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

username of type DOMString

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

credential of type (DOMString or RTCOAuthCredential)

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

If credentialType is "password", credential is a DOMString, and represents a long-term authentication password, as described in [[!RFC5389]], Section 10.2.

If credentialType is "oauth", credential is a RTCOAuthCredential, which contains the OAuth access token and MAC key.

credentialType of type RTCIceCredentialType, defaulting to "password"

If this RTCIceServer object represents a TURN Server, then this attribute specifies how credential should be used when that TURN server requests authorization.

An example array of RTCIceServer objects is:

[
{ urls: "stun:stun1.example.net" },
{ urls: ["turns:turn.example.org", "turn:turn.example.net"],
  username: "user",
  credential: "myPassword",
  credentialType: "password" },
     { urls: "turns:turn2.example.net",
       username: "22BIjxU93h/IgwEb",
       credential: {
                       macKey: "WmtzanB3ZW9peFhtdm42NzUzNG0=",
                       accessToken: "AAwg3kPHWPfvk9bDFL936wYvkoctMADzQ5VhNDgeMR3+ZlZ35byg972fW8QjpEl7bx91YLBPFsIhsxloWcXPhA=="
                     },
       credentialType: "oauth" },
     }
]

Example

      // Example to demonstrate use of RTCIceCandidateComplete
// Include some helper functions
import {trace, errorHandler, mySendLocalCandidate, myIceGathererStateChange,
  myIceTransportStateChange, myDtlsTransportStateChange} from 'helper';

// Create ICE gather options
var gatherOptions = {
  gatherPolicy: "relay",
  iceServers: [
    { urls: "stun:stun1.example.net" },
    { urls: "turn:turn.example.org", username: "user", credential: "myPassword",
      credentialType: "password" }
   ]
};
// Create IceGatherer object
var iceGatherer = new RTCIceGatherer(gatherOptions);

// Handle state changes
iceGatherer.onstatechange = function(event) {
  myIceGathererStateChange("iceGatherer", event.state);
};

// Prepare to signal local candidates
iceGatherer.onlocalcandidate = function(event) {
  mySendLocalCandidate(event.candidate);
};

// Start gathering
iceGatherer.gather();

// Set up response function
mySignaller.onResponse = function(responseSignaller, response) {
  // We may get N responses
  // ... deal with the N responses as shown in Example 5 of Section 3.11.
};

mySignaller.send({
  ice: iceGatherer.getLocalParameters()
});
                
      // Helper functions used in all the examples (helper.js)
export function trace(text) {
  // This function is used for logging.
  text = text.trimRight();
  if (window.performance) {
    var now = (window.performance.now() / 1000).toFixed(3);
    console.log(now + ": " + text);
  } else {
    console.log(text);
  }
}

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

export function mySendLocalCandidate(candidate, component, kind, parameters) {
  // Set default values
  kind = kind || "all";
  component = component || "rtp";
  parameters = parameters || null;

  // Signal the local candidate
  mySignaller.mySendLocalCandidate({
    candidate: candidate,
    component: component,
    kind: kind,
    parameters: parameters
  });
}

export function myIceGathererStateChange(name, state) {
  switch (state) {
    case "new":
      trace("IceGatherer: " + name + " Has been created");
      break;
    case "gathering":
      trace("IceGatherer: " + name + " Is gathering candidates");
      break;
    case "complete":
      trace("IceGatherer: " + name + " Has finished gathering (for now)");
      break;
    case "closed":
      trace("IceGatherer: " + name + " Is closed");
      break;
    default:
      trace("IceGatherer: " + name + " Invalid state");
  }
}

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

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

RTCIceTransport Interface

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

Overview

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

Operation

An RTCIceTransport instance is constructed (optionally) from an RTCIceGatherer. If gatherer.state is closed or gatherer.component is rtcp, throw an InvalidStateError.

An RTCIceTransport object in the closed state can be garbage-collected when it is no longer referenced.

Interface Definition

[ Constructor (optional RTCIceGatherer gatherer), Exposed=Window]
interface RTCIceTransport : RTCStatsProvider {
    readonly        attribute RTCIceGatherer?      iceGatherer;
    readonly        attribute RTCIceRole           role;
    readonly        attribute RTCIceComponent      component;
    readonly        attribute RTCIceTransportState state;
    sequence<RTCIceCandidate> getRemoteCandidates ();
    RTCIceCandidatePair?      getSelectedCandidatePair ();
    void                      start (RTCIceGatherer gatherer, RTCIceParameters remoteParameters, optional RTCIceRole role = "controlled");
    void                      stop ();
    RTCIceParameters?         getRemoteParameters ();
    RTCIceTransport           createAssociatedTransport ();
    void                      addRemoteCandidate (RTCIceGatherCandidate remoteCandidate);
    void                      setRemoteCandidates (sequence<RTCIceCandidate> remoteCandidates);
                    attribute EventHandler         onstatechange;
                    attribute EventHandler         oncandidatepairchange;
};

Constructors

RTCIceTransport
Parameter Type Nullable Optional Description
gatherer RTCIceGatherer

Attributes

iceGatherer of type RTCIceGatherer, readonly , nullable

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

role of type RTCIceRole, readonly

The current role of the ICE transport.

component of type RTCIceComponent, readonly

The component-id of the RTCIceTransport object. In RTCIceTransport objects returned by createAssociatedTransport(), the value of component is rtcp. In all other RTCIceTransport objects, the value of component is rtp.

state of type RTCIceTransportState, readonly

The current state of the ICE transport.

onstatechange of type EventHandler

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

oncandidatepairchange of type EventHandler

This event handler, of event handler type icecandidatepairchange, uses the RTCIceCandidatePairChangedEvent interface. It MUST be supported by all objects implementing the RTCIceTransport interface. It is called any time the selected RTCIceCandidatePair changes.

Methods

getRemoteCandidates

Retrieve the sequence of candidates associated with the remote RTCIceTransport. Only returns the candidates previously added using setRemoteCandidates() or addRemoteCandidate(). If there are no remote candidates, an empty list is returned.

No parameters.
Return type: sequence<RTCIceCandidate>
getSelectedCandidatePair

Retrieves the selected candidate pair on which packets are sent. If there is no selected pair yet, or consent [[!RFC7675]] is lost on the selected pair, NULL is returned.

No parameters.
Return type: RTCIceCandidatePair, nullable
start

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. Since start() enables candidate pairs to be formed, it also enables initiating connectivity checks.

When start() is called, the following steps MUST be run:

  1. If gatherer.component has a value different from component, throw an InvalidParameters.
  2. If state or gatherer.state is closed, throw an InvalidStateError.
  3. If remoteParameters.usernameFragment or remoteParameters.password is unset, throw an InvalidParameters.
  4. If start() is called again and role is changed, throw an InvalidParameters.
  5. If start() is called again with the same values of gatherer and remoteParameters, this has no effect.
  6. If start() is called for the first time and either gatherer was not passed in the constructor or the value of gatherer is unchanged, if there are remote candidates, set state to checking and start connectivity checks. If there are no remote candidates, state remains new.
  7. If start() is called for the first time and the value of gatherer passed as an argument is different from that passed in the constructor, flush local candidates. If there are remote candidates, set state to checking and start connectivity checks. If there are no remote candidates, state remains new.
  8. If start() is called again with the same value of gatherer but the value of remoteParameters has changed, local candidates are kept, remote candidates are flushed, candidate pairs are flushed and state transitions to new.
  9. If start() is called again with a new value of gatherer but the value of remoteParameters is unchanged, local candidates are flushed, candidate pairs are flushed, new candidate pairs are formed with existing remote candidates, and state transitions to checking.
  10. If start() is called again with new values of gatherer and remoteParameters, local candidates are flushed, remote candidates are flushed, candidate pairs are flushed and state transitions to new.
Parameter Type Nullable Optional Description
gatherer RTCIceGatherer
remoteParameters RTCIceParameters
role RTCIceRole = controlled
Return type: void
stop

Irreversibly stops the RTCIceTransport. When stop is called, the following steps MUST be run:

  1. Let iceTransport be the RTCIceTransport object on which the stop method is invoked.
  2. If iceTransport.state is closed, abort these steps.
  3. Set iceTransport.state to closed.
  4. Let controller be the RTCIceTransportController object that iceTransport has been added to.
  5. Remove iceTransport from controller.
  6. Fire a simple event statechange at iceTransport.
No parameters.
Return type: void
getRemoteParameters

getRemoteParameters() obtains the current ICE parameters of the remote RTCIceTransport.

No parameters.
Return type: RTCIceParameters, nullable
createAssociatedTransport

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

No parameters.
Return type: RTCIceTransport
addRemoteCandidate

Add a remote candidate associated with the remote RTCIceTransport. If state is closed, throw an InvalidStateError. When the remote RTCIceGatherer emits its final candidate, addRemoteCandidate() should be called with an RTCIceCandidateComplete dictionary as an argument, so that the local RTCIceTransport can know there are no more remote candidates expected, and can enter the completed state.

Parameter Type Nullable Optional Description
remoteCandidate RTCIceGatherCandidate
Return type: void
setRemoteCandidates

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

Parameter Type Nullable Optional Description
remoteCandidates sequence<RTCIceCandidate>
Return type: void

RTCIceComponent Enum

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

enum RTCIceComponent {
    "rtp",
    "rtcp"
};
Enumeration description
rtp

The RTP component ID, defined (as '1') in [[!RFC5245]] Section 4.1.1.1. Protocols multiplexed with RTP (e.g. SCTP data channel) share its component ID.

rtcp

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

RTCIceRole Enum

RTCIceRole contains the current role of the ICE transport.

enum RTCIceRole {
    "controlling",
    "controlled"
};
Enumeration description
controlling

controlling state

controlled

controlled state

RTCIceTransportState Enum

RTCIceTransportState represents the current state of the ICE transport.

enum RTCIceTransportState {
    "new",
    "checking",
    "connected",
    "completed",
    "disconnected",
    "failed",
    "closed"
};
Enumeration description
new

The RTCIceTransport object is waiting for remote candidates to be supplied. In this state the RTCIceTransport 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 consent checks [[!RFC7675]] have failed on all previously successful candidate pairs.

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. If consent checks [[!RFC7675]] fail on the connection in use, and there are no other successful candidate pairs available, then the state transitions to checking (if there are candidate pairs remaining to be checked) or disconnected (if there are no candidate pairs to check, but the peer is still gathering and/or waiting for additional remote candidates).

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. If consent checks [[!RFC7675]] subsequently fail on all successful candidate pairs, the state transitions to failed.

disconnected

Connectivity is currently lost for this RTCIceTransport. 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 repeatedly failed to receive a response. At the implementation's discretion, this state may be entered prior to consent failure, and therefore could resolve itself without action. Other candidate pairs may become available for testing as new candidates are trickled, and a temporary consent failure could resolve itself, therefore the failedstate has not been reached.

failed

A local and remote RTCIceCandidateComplete dictionary was added as the last candidate to the RTCIceTransport and all appropriate candidate pairs have either failed connectivity checks or have lost consent.

closed

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

Some example transitions might be:

The non-normative RTCIceTransportState transition diagram
Non-normative ICE transport state transition diagram

RTCIceCandidatePairChangedEvent

The icecandidatepairchange event of the RTCIceTransport object uses the RTCIceCandidatePairChangedEvent interface.

Firing an RTCIceCandidatePairChangedEvent event named e with an RTCIceCandidatePair pair 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 RTCIceCandidatePairChangedEvent interface with pair set to the selected RTCIceCandidatePair, MUST be created and dispatched at the given target.

        [ Constructor (DOMString type, RTCIceCandidatePairChangedEventInit eventInitDict), Exposed=Window]
interface RTCIceCandidatePairChangedEvent : Event {
    readonly        attribute RTCIceCandidatePair pair;
};

Constructors

RTCIceCandidatePairChangedEvent
Parameter Type Nullable Optional Description
type DOMString
eventInitDict RTCIceCandidatePairChangedEventInit

Attributes

pair of type RTCIceCandidatePair, readonly

The pair attribute is the selected RTCIceCandidatePair that caused the event.

The RTCIceCandidatePairChangedEventInit dictionary provides information on the newly selected RTCIceCandidatePair.

        dictionary RTCIceCandidatePairChangedEventInit : EventInit {
             RTCIceCandidatePair pair;
};

Dictionary RTCIceCandidatePairChangedEventInit Members

pair of type RTCIceCandidatePair

The pair attribute is the selected RTCIceCandidatePair that caused the event.

RTCIceCandidatePair Dictionary

The RTCIceCandidatePair contains the currently selected ICE candidate pair.

dictionary RTCIceCandidatePair {
             RTCIceCandidate local;
             RTCIceCandidate remote;
};

Dictionary RTCIceCandidatePair Members

local of type RTCIceCandidate

The local ICE candidate.

remote of type RTCIceCandidate

The remote ICE candidate.

Example

      // Example to demonstrate forking when RTP and RTCP are not multiplexed,
// so that both RTP and RTCP IceGatherer and IceTransport objects are needed.
// Include some helper functions
import {trace, errorHandler, mySendLocalCandidate, myIceGathererStateChange,
  myIceTransportStateChange, myDtlsTransportStateChange} from 'helper';

// Create ICE gather options
var gatherOptions = {
  gatherPolicy: "relay",
  iceServers: [
    { urls: "stun:stun1.example.net" },
    { urls: "turn:turn.example.org", username: "user", credential: "myPassword",
      credentialType: "password" }
   ]
};

// Create ICE gatherer objects
var iceRtpGatherer = new RTCIceGatherer(gatherOptions);
var iceRtcpGatherer = iceRtpGatherer.createAssociatedGatherer();

// Prepare to signal local candidates
iceRtpGatherer.onlocalcandidate = function(event) {
  mySendLocalCandidate(event.candidate, "rtp", "audio",
    iceRtpGatherer.getLocalParameters());
};

iceRtcpGatherer.onlocalcandidate = function(event) {
  mySendLocalCandidate(event.candidate, "rtcp", "audio",
    iceRtpGatherer.getLocalParameters());
};

// Start gathering
iceRtpGatherer.gather();
iceRtcpGatherer.gather();

// Initialize the ICE transport arrays
var iceRtpTransports = [];
var iceRtcpTransports = [];

// Set up response function
mySignaller.onResponse = function(responseSignaller, response) {
  // We may get N responses

  // Create the ICE RTP and RTCP transports
  var iceRtpTransport = new RTCIceTransport(iceRtpGatherer);
  var iceRtcpTransport = iceRtpTransport.createAssociatedTransport();

  // Start the RTP and RTCP ICE transports so that outgoing ICE connectivity checks can begin
  // The RTP and RTCP ICE parameters are the same, so only the RTP parameters are used
  iceRtpTransport.start(iceRtpGatherer, response.icertp, RTCIceRole.controlling);
  iceRtcpTransport.start(iceRtcpGatherer, response.icertp, RTCIceRole.controlling);

  iceRtpTransports.push(iceRtpTransport);
  iceRtcpTransports.push(iceRtcpTransport);

  // Prepare to add ICE candidates signalled by the remote peer
  responseSignaller.onRemoteCandidate = function(remote) {
    // Locate the ICE transport that the signaled candidate relates to by matching
   //  the userNameFragment.
    var transports;
    if (remote.component === "rtp") {
      transports = iceRtpTransports;
    } else {
      transports = iceRtcpTransports;
    }

    for (var j = 0; j < iceTransport.length; j++) {
      var transport = transports[j];
      if (transport.getRemoteParameters().userNameFragment === remote.parameters.userNameFragment)
        transport.addRemoteCandidate(remote.candidate);
      }
    }
  };
};

mySignaller.send({
  // The RTP and RTCP parameters are identical, so no need to send both
  icertp: iceRtpGatherer.getLocalParameters()
});
                

RTCDtlsTransport Interface

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

Overview

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

Operation

A RTCDtlsTransport instance is constructed using an RTCIceTransport and a sequence of RTCCertificate objects. An RTCDtlsTransport object in the closed or failed states can be garbage-collected when it is no longer referenced.

If an attempt is made to construct a RTCDtlsTransport instance from an RTCIceTransport in the closed state, throw an InvalidStateError. If certificates is non-empty, check that the expires attribute of each RTCCertificate object is in the future. If a certificate has expired, throw an InvalidParameter; otherwise, store the certificates.

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/or RTCP. This multiplexing, originally described in [[!RFC5764]] Section 5.1.2, is updated in [[!RFC7983]].

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(). To verify the remote fingerprint, compute the fingerprint value for the selected remote certificate using the signature digest algorithm, and compare it against remoteParameters.fingerprints. If the selected remote certificate RTCDtlsFingerprint.value matches remoteParameters.fingerprints[j].value and RTCDtlsFingerprint.algorithm matches remoteParameters.fingerprints[j].algorithm for any value of j, the remote fingerprint is verified. 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).

Interface Definition

        [ Constructor (RTCIceTransport transport, sequence<RTCCertificate> certificates), Exposed=Window]
interface RTCDtlsTransport : RTCStatsProvider  {
    readonly        attribute RTCIceTransport          transport;
    readonly        attribute RTCDtlsTransportState    state;
    sequence<RTCCertificate>     getCertificates ();
    RTCDtlsParameters     getLocalParameters ();
    RTCDtlsParameters?    getRemoteParameters ();
    sequence<ArrayBuffer> getRemoteCertificates ();
    void                  start (RTCDtlsParameters remoteParameters);
    void                  stop ();
                    attribute EventHandler             onstatechange;
                    attribute EventHandler             onerror;
};

Constructors

RTCDtlsTransport
Parameter Type Nullable Optional Description
transport RTCIceTransport
certificates sequence<RTCCertificate>

Attributes

transport of type RTCIceTransport, readonly

The associated RTCIceTransport instance.

state of type RTCDtlsTransportState, readonly

The current state of the DTLS transport.

onstatechange of type EventHandler

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

onerror of type EventHandler

This event handler, of event handler event type error, MUST be fired after a DTLS error. An implementation SHOULD provide more details on DTLS errors as follows:

  1. A fingerprint validation failure is indicated by setting error.name to "fingerprint-failure".
  2. Reception of a DTLS alert is indicated by setting error.name to "dtls-alert-received".
  3. Sending of a DTLS alert is indicated by setting error.name to "dtls-alert-sent".
  4. The DTLS alert value is provided by setting error.message (defined in [[!HTML5]] Section 6.1.3.6.2) to "DTLS Alert: ".

Methods

getCertificates

getCertificates() returns the certificates provided in the constructor.

No parameters.
Return type: sequence<RTCCertificate>
getLocalParameters

getLocalParameters() obtains the DTLS parameters of the local RTCDtlsTransport upon construction. If multiple certificates were provided in the constructor, then multiple fingerprints will be returned, one for each certificate. getLocalParameters().role always returns the default role of a newly constructed RTCDtlsTransport; for a browser this will be auto.

No parameters.
Return type: RTCDtlsParameters
getRemoteParameters

getRemoteParameters() obtains the remote DTLS parameters passed in the start() method. Prior to calling start(), null is returned.

No parameters.
Return type: RTCDtlsParameters, nullable
getRemoteCertificates

getRemoteCertificates() returns the certificate chain in use by the remote side, with each certificate encoded in binary Distinguished Encoding Rules (DER) [[!X690]]. getRemoteCertificates() returns an empty list prior to selection of the remote certificate, which is completed once state transitions to connected.

No parameters.
Return type: sequence<ArrayBuffer>
start

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.

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.

If start is called after a previous start call, or if state is closed, throw an InvalidStateError.

If all of the values of remoteParameters.fingerprints[j].algorithm are unsupported, where j goes from 0 to the number of fingerprints, throw a NotSupportedError.

Parameter Type Nullable Optional Description
remoteParameters RTCDtlsParameters
Return type: void
stop

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

No parameters.
Return type: void

RTCDtlsParameters Dictionary

The RTCDtlsParameters dictionary includes information relating to DTLS configuration.

dictionary RTCDtlsParameters {
             RTCDtlsRole                  role = "auto";
             sequence<RTCDtlsFingerprint> fingerprints;
};

Dictionary RTCDtlsParameters Members

role of type RTCDtlsRole, defaulting to "auto"

The DTLS role, with a default of auto.

fingerprints of type sequence<RTCDtlsFingerprint>

Sequence of fingerprints, one fingerprint for each certificate.

RTCDtlsFingerprint Dictionary

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

dictionary RTCDtlsFingerprint {
             DOMString algorithm;
             DOMString value;
};

Dictionary RTCDtlsFingerprint Members

algorithm of type DOMString

One of the the hash function algorithms defined in the 'Hash function Textual Names' registry, initially specified in [[!RFC4572]] Section 8. As noted in [[!JSEP]] Section 5.2.1, the digest algorithm used for the fingerprint matches that used in the certificate signature.

value of type DOMString

RTCDtlsRole Enum

RTCDtlsRole indicates the role of the DTLS transport.

enum RTCDtlsRole {
    "auto",
    "client",
    "server"
};
Enumeration description
auto

The DLTS role is determined based on the resolved ICE role: the ICE controlled role acts as the DTLS client and the ICE controlling role acts as the DTLS server.

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. For a browser implementing 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 a browser), 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.onstatechange EventHandler can be used to determine whether an RTCDtlsTransport transitions to the desired role as expected. When RTCDtlsTransport.transport.state transitions to connected, if RTCDtlsTransport.transport.role is controlled then the role of the RTCDtlsTransport is client. If RTCDtlsTransport.transport.role is controlling then the role of the RTCDtlsTransport is server.

RTCDtlsTransportState Enum

RTCDtlsTransportState indicates the state of the DTLS transport.

enum RTCDtlsTransportState {
    "new",
    "connecting",
    "connected",
    "closed",
    "failed"
};
Enumeration description
new

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

connecting

DTLS is in the process of negotiating a secure connection and verifying the remote fingerprint. Once a secure connection is negotiated (but prior to verification of the remote fingerprint, enabled by calling start()), incoming data can flow through (and media, once DTLS-SRTP key derivation is completed).

connected

DTLS has completed negotiation of a secure connection and verified the remote fingerprint. Outgoing data and media can now flow through.

closed

The DTLS connection has been closed intentionally via a call to stop() or receipt of a close_notify alert. Calling transport.stop() will also result in a transition to the closed state.

failed

The DTLS connection has been closed as the result of an error (such as receipt of an error alert or a failure to validate the remote fingerprint).

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 {trace, errorHandler, mySendLocalCandidate, myIceGathererStateChange,
  myIceTransportStateChange, myDtlsTransportStateChange} from 'helper';

function initiate(mySignaller) {
  // Prepare the ICE gatherer
  var gatherOptions = {
    gatherPolicy: "all",
    iceServers: [
      { urls: "stun:stun1.example.net" },
      { urls: "turn:turn.example.org", username: "user", credential: "myPassword",
        credentialType: "password" }
     ]
  };
  var iceGatherer = new RTCIceGatherer(gatherOptions);
  iceGatherer.onlocalcandidate = function(event) {
    mySignaller.mySendLocalCandidate(event.candidate);
  };

  // Start gathering
  iceGatherer.gather();

  // Initialize the ICE and DTLS transport arrays
  var iceTransports = [];
  var dtlsTransports = [];

  // Create the DTLS certificate and parameters
  var certs;
  var dtlsParameters = {};
  var keygenAlgorithm = { name: "ECDSA", namedCurve: "P-256" };
  RTCCertificate.generateCertificate(keygenAlgorithm).then(function(certificate){
    certs[0] = certificate;
    // Obtain the fingerprint of the created certificate
    dtlsParameters.fingerprints[0] = certificate.fingerprint;
  }, function(){
    trace('Certificate could not be created');
  });
  // Prepare to handle remote ICE candidates
  mySignaller.onRemoteCandidate = function(remote) {
    // Figure out which IceTransport a remote candidate relates to by matching
    // the userNameFragment/password
    var j = 0;
    for (j = 0; j < iceTransport.length; j++) {
      var transport = iceTransports[j];
      if (transport.getRemoteParameters().userNameFragment === remote.parameters.userNameFragment)
        transport.addRemoteCandidate(remote.candidate);
      }
    }  };
  // ... construct RtpSender/RtpReceiver objects as illustrated in Section 6.5 Example 9.

  mySignaller.mySendInitiate({
    ice: iceGatherer.getLocalParameters(),
    dtls: dtlsParameters,
    // ... marshall RtpSender/RtpReceiver capabilities as illustrated in Section 6.5 Example 9.
  }, function(remote) {
    // Create the ICE and DTLS transports
    var iceTransport = new RTCIceTransport(iceGatherer);
    iceTransport.start(iceGatherer, remote.ice, RTCIceRole.controlling);
    iceTransports.push(iceTransport);
    // Construct a RTCDtlsTransport object with the same certificate and fingerprint
    // as in the Offer so that the remote peer can verify it.
    var dtlsTransport = new RTCDtlsTransport(iceTransport, certs);
    dtlsTransport.start(remote.dtls);
    dtlsTransports.push(dtlsTransport);

    // ... configure RtpSender/RtpReceiver objects as illustrated in Section 6.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 {trace, errorHandler, mySendLocalCandidate, myIceGathererStateChange,
  myIceTransportStateChange, myDtlsTransportStateChange} from 'helper';

// Assume that remote info is signalled to us.
function accept(mySignaller, remote) {
  // Prepare the ICE gatherer
  var gatherOptions = {
    gatherPolicy: "all",
    iceServers: [
      { urls: "stun:stun1.example.net" },
      { urls: "turn:turn.example.org", username: "user", credential: "myPassword",
        credentialType: "password" }
     ]
  };
  var iceGatherer = new RTCIceGatherer(gatherOptions);
  iceGatherer.onlocalcandidate = function(event) {
    mySignaller.mySendLocalCandidate(event.candidate);
  };

  // Start gathering
  iceGatherer.gather();

  // Create the DTLS certificate
  var certs;
  var keygenAlgorithm = { name: "ECDSA", namedCurve: "P-256" };
  RTCCertificate.generateCertificate(keygenAlgorithm).then(function(certificate){
    certs[0] = certificate;
  }, function(){
    trace('Certificate could not be created');
  });

  // Create ICE and DTLS transports
  var ice = new RTCIceTransport(iceGatherer);
  var dtls = new RTCDtlsTransport(ice, certs);

  // Prepare to handle remote candidates
  mySignaller.onRemoteCandidate = function(remote) {
    ice.addRemoteCandidate(remote.candidate);
  };
  // ... create RtpSender/RtpReceiver objects as illustrated in Section 6.5 Example 9.

  mySignaller.mySendAccept({
    ice: iceGatherer.getLocalParameters(),
    dtls: dtls.getLocalParameters()
    // ... marshall RtpSender/RtpReceiver capabilities as illustrated in Section 6.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 6.5 Example 9.
}
                

RTCRtpSender Interface

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 or kind and associated to an RTCDtlsTransport. An RTCRtpSender object can be garbage-collected once stop() is called and it is no longer referenced.

Interface Definition

        [ Constructor ((MediaStreamTrack or DOMString) trackOrKind, optional RTCDtlsTransport transport, optional RTCDtlsTransport rtcpTransport), Exposed=Window]
interface RTCRtpSender : RTCStatsProvider {
    readonly        attribute MediaStreamTrack?  track;
    readonly        attribute RTCDtlsTransport?  transport;
    readonly        attribute RTCDtlsTransport? rtcpTransport;
    readonly        attribute DOMString kind;
    void                      setTransport (RTCDtlsTransport transport, optional RTCDtlsTransport rtcpTransport);
    Promise<void>             setTrack (MediaStreamTrack? track);  // deprecated
    Promise<void>             replaceTrack (MediaStreamTrack? track);
    static RTCRtpCapabilities getCapabilities (DOMString kind);
    Promise<void>             send (RTCRtpParameters parameters);
    void                      stop ();
                    attribute EventHandler      onssrcconflict;
};

Constructors

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

  1. Let the first argument be trackOrKind.
  2. If trackOrKind is a DOMString and is not a supported MediaStreamTrack kind, throw a TypeError and abort these steps.
  3. If trackOrKind is a MediaStreamTrack and trackOrKind.readyState is ended, throw an InvalidStateError and abort these steps.
  4. Let transport be the second argument.
  5. Let rtcpTransport be the third argument.
  6. If transport is unset, and rtcpTransport is set, throw an InvalidParameters and abort these steps.
  7. If transport is set and transport.state is closed, throw an InvalidStateError and abort these steps.
  8. If rtcpTransport is set and rtcpTransport.state is closed, throw an InvalidStateError and abort these steps.
  9. Construct an RTCRtpSender with transport (if provided) and rtcpTransport (if provided) and let sender be the result.
  10. Let sender have an [[\RtpSenderIsStopped]] internal slot, initialized to false.
  11. Let sender have a [[\RtpSenderKind]] internal slot.
  12. Let sender have a [[\RtpSenderTrack]] internal slot.
  13. If trackOrKind is a MediaStreamTrack initialize sender's [[\RtpSenderTrack]] slot to trackOrKind and sender's [[\RtpSenderKind]] slot to trackOrKind.kind.
  14. If trackOrKind is a DOMString initialize sender's [[\RtpSenderTrack]] internal slot to null and sender's [[\RtpSenderKind]] slot to trackOrKind.
RTCRtpSender
Parameter Type Nullable Optional Description
trackOrKind (MediaStreamTrack or DOMString)
transport RTCDtlsTransport
rtcpTransport RTCDtlsTransport

Attributes

track of type MediaStreamTrack, readonly , nullable

The associated MediaStreamTrack instance. If track is ended, or if track.muted is set to true, the RTCRtpSender sends silence (audio) or a black frame (video). If track is set to null then the RTCRtpSender does not send RTP.

transport of type RTCDtlsTransport, readonly , nullable

The RTCDtlsTransport instance over which RTCP is sent and received (if provided). When BUNDLE is used, many RTCRtpSender objects will share one rtcpTransport and will all send and receive RTCP over the same RTCDtlsTransport. When RTCP mux is used, rtcpTransport will be null, and both RTP and RTCP traffic will flow over the RTCDtlsTransport transport.

rtcpTransport of type RTCDtlsTransport, readonly , nullable

The associated RTCP RTCDtlsTransport instance if one was provided in the constructor. When RTCP mux is used, rtcpTransport will be null, and both RTP and RTCP traffic will flow over the RTCDtlsTransport transport.

kind of type DOMString, readonly

The value of kind or track.kind passed in the constructor.

onssrcconflict of type EventHandler

The onssrcconflict event handler, of event handler type RTCSsrcConflictEvent, is fired if an SSRC conflict is detected within the RTP session or an SSRC misconfiguration is detected after send() or receive() returns or when setTransport is called. In this situation, the RTCRtpSender automatically sends an RTCP BYE on the conflicted SSRC, if RTP packets were sent using that SSRC.

Methods

setTransport

setTransport() attempts to replace the the RTP RTCDtlsTransport transport (if set) and RTCP RTCDtlsTransport rtcpTransport (if used) with the transport(s) provided.

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's [[\RtpSenderIsStopped]] slot is true, throw an InvalidStateError and abort these steps.

  3. Let withTransport and withRtcpTransport be the arguments to this method.

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

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

  6. If withRtcpTransport is set and withRtcpTransport.transport.component is rtp, throw an InvalidParameters.

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

  8. If withRtcpTransport is set and withRtcpTransport.state is closed, throw an InvalidStateError.

  9. Set transport to withTransport and rtcpTransport to withRtcpTransport (if provided) and seamlessly send over the new transport(s).

Parameter Type Nullable Optional Description
transport RTCDtlsTransport
rtcpTransport RTCDtlsTransport
Return type: void
setTrack

setTrack Attempts to replace the track being sent with another track provided (or with a null track). The deprecated setTrack method operates identically to the replaceTrack method.

Parameter Type Nullable Optional Description
track MediaStreamTrack
Return type: Promise<void>
replaceTrack

Attempts to replace the track being sent with another track provided (or with a null track).

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

  1. Let p be a new promise.

  2. Let sender be the RTCRtpSender object on which replaceTrack() is invoked.

  3. If sender's [[\RtpSenderIsStopped]] slot is true, reject p with a newly created InvalidStateError.
  4. Let withTrack be the argument to this method.

  5. If withTrack is non-null and withTrack.kind differs from sender.kind, reject p with a newly created TypeError.

  6. Run the following steps:

    1. Set the track attribute to withTrack. If withTrack is null, the sender stops sending. Otherwise, have the sender seamlessly switch to transmitting withTrack in place of what it is sending.

    2. Resolve p with undefined.

Parameter Type Nullable Optional Description
track MediaStreamTrack
Return type: Promise<void>
getCapabilities, static

getCapabilities() obtains the sender capabilities, based on kind. Browsers MUST support kind values of "audio" and "video". If there are no capabilities corresponding to the value of kind, getCapabilities returns null. Capabilities that can apply to multiple values of kind (such as retransmission [[!RFC4588]], redundancy [[RFC2198]] and Forward Error Correction) have RTCRtpCapabilities.RTCRtpCodecCapability[i].kind set to the value of the kind argument.

Parameter Type Nullable Optional Description
kind DOMString
Return type: RTCRtpCapabilities
send

Attempts to set the parameters controlling the sending of media.

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

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

  2. Let p be a new promise.

  3. If sender's [[\RtpSenderIsStopped]] slot is true, reject p with a newly created InvalidStateError.

  4. If sender.transport is unset, reject p with a newly created TypeError.

  5. If rtcpTransport is unset and withParameters.rtcp.mux is set to false, reject p with a newly created TypeError.

  6. Let withParameters be the argument to this method.

  7. For each value of i from 0 to the number of codecs, check that each value of withParameters.codecs[i].payloadType is set. If any value is unset, reject p with a newly created TypeError.

  8. For each value of i from 0 to the number of codecs:

    1. Let codec be withParameters.codecs[i].

    2. Let clockRate be codec.clockRate.

    3. Let name be codec.name.

    4. If name or clockRate is unset, throw a TypeError and abort all of these steps.

    5. If name is not equal to "red", "rtx" or a forward error correction codec ("ulpfec" [[RFC5109]] or "flexfec" [[FLEXFEC]]), check whether name is equal to getCapabilities(track.kind).codecs[j].name and clockRate is equal to getCapabilities(track.kind).codecs[j].clockRate for any value of j from 0 to the number of codecs.

    6. If a match is found for a value of j, check that:

      1. codec.channels is less than or equal to getCapabilities(track.kind).codecs[j].channels. If not, reject p with a newly created NotSupportedError.

      2. Each of the values of codec.rtcpFeedback[k] is included in getCapabilities(track.kind).codecs[j].rtcpFeedback where k goes from 0 to the number of feedback mechanisms. If not, reject p with a newly created NotSupportedError.

      3. Each of the values of codec.parameters[k] is a valid value as indicated by getCapabilities(track.kind).codecs[j].parameters where k goes from 0 to the number of feedback mechanisms. If not, reject p with a newly created NotSupportedError.

    7. If a match is not found for any value of j, reject p with a newly created TypeError.

  9. For each value of i from 0 to the number of encodings:

    1. Let payloadType be withParameters.encodings[i].codecPayloadType.

    2. If payloadType is set, check whether payloadType is equal to withParameters.codecs[j].payloadType for values of j from 0 to the number of codecs. If a match is found for any value of j, check whether withParameters.codecs[j].name is equal to "red", "cn", "telephone-event", "rtx" or a forward error correction codec ("ulpfec" [[RFC5109]] or "flexfec" [[FLEXFEC]]). If so, reject p with a newly created InvalidParameters.

    3. If no match is found, reject p with a newly created InvalidParameters.

    4. Let ssrc be withParameters.encodings[i].ssrc.

    5. Let dep be withParameters.encodings[i].dependencyEncodingIds.

    6. If ssrc is set and dep is unset, check that ssrc is unique. If not, throw a NotSupportedError.

  10. Run the following steps:

    1. If send() is called for the first time, start sending. If send() was called previously, have the sender switch to sending using withParameters.

    2. Resolve p with undefined.

Parameter Type Nullable Optional Description
parameters RTCRtpParameters
Return type: Promise<void>
stop

The stop method irreversibly stops the RTCRtpSender. When stop called, the following steps MUST be run:

  1. Let sender be the RTCRtpSender on which stop is invoked.
  2. If sender's [[\RtpSenderIsStopped]] slot is true, abort these steps.
  3. Let parameters be the argument provided to sender.send(parameters) the last time it was invoked.

  4. Stop sending media with sender.

  5. Send an RTCP BYE for each SSRC in parameters.encodings[i].ssrc, parameters.encodings[i].fec.ssrc and parameters.encodings[i].rtx.ssrc where i goes from 0 to encodings.length-1.

  6. Set sender's [[\RtpSenderIsStopped]] slot to true.
No parameters.
Return type: void

RTCSsrcConflictEvent

The ssrcconflict event of the RTCRtpSender object uses the RTCSsrcConflictEvent interface.

Firing an RTCSsrcConflictEvent event named e with an ssrc 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 RTCSsrcConflictEvent interface with the ssrc attribute set to the conflicting SSRC MUST be created and dispatched at the given target.

        [ Constructor (DOMString type, RTCSsrcConflictEventInit eventInitDict), Exposed=Window]
interface RTCSsrcConflictEvent : Event {
    readonly        attribute unsigned long ssrc;
};

Constructors

RTCSsrcConflictEvent
Parameter Type Nullable Optional Description
type DOMString
eventInitDict RTCSsrcConflictEventInit

Attributes

ssrc of type unsigned long, readonly

The ssrc attribute represents the conflicting SSRC that caused the event.

The RTCSsrcConflictEventInit dictionary includes the ssrc attribute representing the conflicting SSRC that caused the event.

dictionary RTCSsrcConflictEventInit : EventInit {
             unsigned long ssrc;
};

Dictionary RTCSsrcConflictEventInit Members

ssrc of type unsigned long

The ssrc attribute represents the conflicting SSRC that caused the event.

RTCRtpReceiver Interface

The RTCRtpReceiver includes information relating to the RTP receiver.

Overview

An RTCRtpReceiver instance produces an associated receiving MediaStreamTrack and provides RTC related methods to it.

Operation

A RTCRtpReceiver instance is constructed from a value of kind and an RTCDtlsTransport object. If an attempt is made to construct an RTCRtpReceiver object with transport.state or rtcpTransport.state with a value of closed, throw an InvalidStateError. Upon construction, track is set, and the value of track.kind is determined based on the value of kind passed in the constructor.

An RTCRtpReceiver object can be garbage-collected once stop() is called and it is no longer referenced.

Interface Definition

        [ Constructor (DOMString kind, RTCDtlsTransport transport, optional RTCDtlsTransport rtcpTransport), Exposed=Window]
interface RTCRtpReceiver : RTCStatsProvider {
    readonly        attribute MediaStreamTrack  track;
    readonly        attribute RTCDtlsTransport  transport;
    readonly        attribute RTCDtlsTransport? rtcpTransport;
    void            setTransport (RTCDtlsTransport transport, optional RTCDtlsTransport rtcpTransport);
    static RTCRtpCapabilities     getCapabilities (DOMString kind);
    Promise<void>                      receive (RTCRtpParameters parameters);
    sequence<RTCRtpContributingSource> getContributingSources ();
    sequence<RTCRtpSynchronizationSource> getSynchronizationSources ();
    void                               stop ();
};

Constructors

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

  1. Let the first argument be kind.
  2. If kind is not a supported code>MediaStreamTrack kind, throw a TypeError and abort these steps.
  3. Let transport be the second argument.
  4. Let rtcpTransport be the third argument.
  5. If transport is unset, and rtcpTransport is set, throw an InvalidParameters and abort these steps.
  6. If transport is set and transport.state is closed, throw an InvalidStateError and abort these steps.
  7. If rtcpTransport is set and rtcpTransport.state is closed, throw an InvalidStateError and abort these steps.
  8. Construct an RTCRtpReceiver with transport and rtcpTransport (if provided) and let receiver be the result.
  9. Let receiver have an [[\RtpReceiverIsStopped]] internal slot, initialized to false.
  10. Let receiver have a [[\RtpReceiverKind]] internal slot, initialized to kind.
  11. Let receiver have a [[\RtpReceiverTrack]] internal slot, initialized to a newly created MediaStreamTrack of kind kind.
RTCRtpReceiver
Parameter Type Nullable Optional Description
kind DOMString
transport RTCDtlsTransport
rtcpTransport RTCDtlsTransport

Attributes

track of type MediaStreamTrack, readonly

The track attribute is the MediaStreamTrack instance that is associated with this RTCRtpReceiver object receiver. Upon construction, track is set. The value of track.kind is set to the value of kind passed in the constructor.

When one of the SSRCs in parameters.encodings[i].ssrc (where i goes from 0 to encodings.length-1) is removed from the source identifier table described in [[!RFC3550]] Section 8.2 (either due to BYE reception or timeout) the mute event is fired at track. If and when media packets are received again for receiver, the unmute event is fired at track.

Prior to verification of the remote DTLS fingerprint within the RTCDtlsTransport transport, and (if set) rtcpTransport, track MUST NOT emit media for rendering.
transport of type RTCDtlsTransport, readonly

The associated RTP RTCDtlsTransport instance.

rtcpTransport of type RTCDtlsTransport, readonly , nullable

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

Methods

setTransport

The setTransport() method attempts to replace the the RTP RTCDtlsTransport transport (and if used) RTCP RTCDtlsTransport rtcpTransport with the transport(s) provided.

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's [[\RtpReceiverIsStopped]] slot is true, throw an InvalidStateError.
  3. Let withTransport and withRtcpTransport be the arguments to this method.

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

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

  6. If withRtcpTransport is set and withRtcpTransport.transport.component is rtp, throw an InvalidParameters.

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

  8. If withRtcpTransport is set and withRtcpTransport.state is closed, throw an InvalidStateError.

  9. Replace transport with withTransport and rtcpTransport (if set) with withRtcpTransport and seamlessly receive over the new transport(s).

Parameter Type Nullable Optional Description
transport RTCDtlsTransport
rtcpTransport RTCDtlsTransport
Return type: void
getCapabilities, static

getCapabilities() obtains the receiver capabilities, based on kind. Browsers MUST support kind values of "audio" and "video". If there are no capabilities corresponding to the value of kind, getCapabilities returns null. Capabilities that can apply to multiple values of kind (such as retransmission [[!RFC4588]], redundancy [[RFC2198]] and Forward Error Correction) have RTCRtpCapabilities.RTCRtpCodecCapability[i].kind set to the value of the kind argument.

Parameter Type Nullable Optional Description
kind DOMString
Return type: RTCRtpCapabilities
receive

Attempts to set the parameters controlling the receiving of media.

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

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

  2. Let p be a new promise.

  3. If receiver's [[\RtpReceiverIsStopped]] slot is true, reject p with a newly created InvalidStateError.
  4. Let withParameters be the argument to this method.

  5. If withParameters is invalid due to SSRC misusage, ssrc_table, muxId_table or pt_table conflicts described in Section 8.3 or other reasons, reject p with InvalidParameters.

  6. If rtcpTransport is not set and withParameters.rtcp.mux is set to false, reject p with InvalidParameters.

  7. For each value of i from 0 to the number of codecs, check that each value of withParameters.codecs[i].payloadType is set. If any value is unset, reject p with InvalidParameters.

  8. For each value of i from 0 to the number of encodings, check whether withParameters.encodings[i].codecPayloadType corresponds to a value of withParameters.codecs[j].payloadType where j goes from 0 to the number of codecs. If there is no correspondence, or if withParameters.codecs[j].name is equal to "red", "cn", "telephone-event", "rtx" or a forward error correction codec ("ulpfec" [[RFC5109]] or "flexfec" [[FLEXFEC]]), reject p with InvalidParameters.

  9. For each value of i from 0 to the number of codecs, check that each value of withParameters.codecs[i].name not equal to "red", "rtx" or a forward error correction codec is included in getCapabilities(kind).codecs[j].name, where j goes from 0 to the number of codecs, and kind takes the value passed in the RTCRtpReceiver constructor. If no match is found for any value of i, reject p with InvalidParameters.

  10. Run the following steps:

    1. If receive() is called for the first time, start receiving. If receive() was called previously, have the receiver switch to receiving using withParameters.

    2. Resolve p with undefined.

Parameter Type Nullable Optional Description
parameters RTCRtpParameters
Return type: Promise<void>
getContributingSources

Returns an RTCRtpContributingSource for each unique CSRC identifier received by this RTCRtpReceiver. The browser MUST keep information from RTP packets received in the last 10 seconds. If no contributing sources are available, an empty list is returned.

No parameters.
Return type: sequence<RTCRtpContributingSource>
getSynchronizationSources

Returns an RTCRtpSynchronizationSource for each unique SSRC identifier received by this RTCRtpReceiver in the last 10 seconds.

No parameters.
Return type: sequence<RTCRtpSynchronizationSource>
stop

Stops the RTCRtpReceiver receiver. receiver.stop() is final like receiver.track.stop(). receiver.track.stop() does not affect track clones and also does not stop receiver so that Receiver Reports continue to be sent. Calling receiver.stop sets receiver's [[\RtpReceiverIsStopped]] slot to true but does not cause the "onended" event to fire for track.

No parameters.
Return type: void

RTCRtpSynchronizationSource Dictionary

The RTCRtpSynchronizationSource dictionary contains information about a given synchronization source (SSRC), including the most recent time a packet that the source contributed to was played out. The browser MUST keep information from RTP packets received in the previous 10 seconds.

dictionary RTCRtpSynchronizationSource {
             DOMHighResTimeStamp timestamp;
             unsigned long       source;
             byte                audioLevel;
             boolean            voiceActivityFlag;
};

Dictionary RTCRtpSynchronizationSource Members

timestamp of type DOMHighResTimeStamp

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

source of type unsigned long

The SSRC identifier of the synchronization source.

audioLevel of type byte

The audio level contained in the last RTP packet played from this source. audioLevel will be the level value defined in [[!RFC6464]], if the RFC 6464 header extension is present.

voiceActivityFlag of type boolean

Whether the last RTP packet received from this source contains voice activity (true) or not (false). Since the "V" bit is supported in [[!RFC6464]] but not [[!RFC6465]], the voiceActivityFlag attribute will only be set when receivers enable the client-mixer header extension (setting the vad attribute to true), and when RTP packets are received from senders enabling the client-mixer header extension (setting the vad attribute to true).

RTCRtpContributingSource Dictionary

The RTCRtpContributingSource dictionary contains information about a given contributing source (CSRC), including the most recent time a packet that the source contributed to was played out. The browser MUST keep information from RTP packets received in the previous 10 seconds.

When the first audio frame contained in an RTP packet is delivered to the RTCRtpReceiver's MediaStreamTrack for playout, the user agent MUST queue a task to update the relevant RTCRtpContributingSource and RTCRtpSynchronizationSource objects based on the contents of the packet. The RTCRtpSynchronizationSource dictionary corresponding to the SSRC identifier is updated each time, and the level value for the SSRC is updated based on the client-mixer header extension [[!RFC6464]] if present.

If the RTP packet contains CSRC identifiers, then the RTCRtpContributingSource dictionaries corresponding to those CSRC identifiers are also updated, and the level values for those CSRCs are updated based on the mixer-client header extension [[!RFC6464]] if present.

As stated in the conformance section, requirements phrased as algorithms may be implemented in any manner so long as the end result is equivalent. So, an implementation does not need to literally queue a task for every packet, as long as the end result is that within a single event loop task execution, all RTCRtpSynchronizationSource and RTCRtpContributingSource objects for a particular RTCRtpReceiver return information from a single point in the RTP stream.
dictionary RTCRtpContributingSource {
             DOMHighResTimeStamp timestamp;
             unsigned long       source;
             byte                audioLevel;
};

Dictionary RTCRtpContributingSource Members

timestamp of type DOMHighResTimeStamp

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

source of type unsigned long

The CSRC identifier of the contributing source.

audioLevel of type byte

The audio level contained in the last RTP packet played from this source. audioLevel will be the level value defined in [[!RFC6465]] if the RFC 6465 header extension is present, and otherwise null. RFC 6465 defines the level as a integral value from 0 to 127 representing the audio level in negative decibels relative to the loudest signal that the system could possibly encode. Thus, 0 represents the loudest signal the system could possibly encode, and 127 represents silence.

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("audio", transport);
  var videoReceiver = new RTCRtpReceiver("video", transport);

  // 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).then(function() {
      trace("Set audio sender parameters");
      }, function() {
        trace("Could not set audio sender parameters");
      }
    );
    videoSender.send(videoSendParams).then(function() {
      trace("Set video sender parameters");
      }, function() {
        trace("Could not set video sender parameters");
      }
    );
    audioReceiver.receive(audioRecvParams).then(function() {
      trace("Set audio receiver parameters");
      }, function() {
        trace("Could not set audio receiver parameters");
      }
    );
    videoReceiver.receive(videoRecvParams).then(function() {
      trace("Set video receiver parameters");
      }, function() {
        trace("Could not set video receiver parameters");
      }
    );
    // 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("audio", transport);
  var videoReceiver = new RTCRtpReceiver("video", transport);

  // 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 18.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).then(function() {
    trace("Set audio sender parameters");
    }, function() {
      trace("Could not set audio sender parameters");
    }
  );
  videoSender.send(videoSendParams).then(function() {
    trace("Set video sender parameters");
    }, function() {
      trace("Could not set video sender parameters");
    }
  );
  audioReceiver.receive(audioRecvParams).then(function() {
    trace("Set audio receiver parameters");
    }, function() {
      trace("Could not set audio receiver parameters");
    }
  );
  videoReceiver.receive(videoRecvParams).then(function() {
    trace("Set video receiver parameters");
    }, function() {
      trace("Could not set video receiver parameters");
    }
  );
  // Now we can render/play
  // audioReceiver.track and videoReceiver.track.
}
                

RTCIceTransportController Interface

The RTCIceTransportController object assists in the managing of ICE freezing and bandwidth estimation.

Overview

An RTCIceTransportController object provides methods to add and retrieve RTCIceTransport objects with a component of rtp (associated RTCIceTransport objects with a component of rtcp are included implicitly).

Operation

An RTCIceTransportController instance is automatically constructed.

Interface Definition

[Constructor(), Exposed=Window]
interface RTCIceTransportController {
    void                      addTransport (RTCIceTransport transport, optional unsigned long index);
    sequence<RTCIceTransport> getTransports ();
};

Methods

addTransport

Adds transport to the RTCIceTransportController object for the purposes of managing ICE freezing and sharing bandwidth estimation. Since addTransport manages ICE freezing, candidate pairs that are not in the frozen state maintain their state when addTransport(transport) is called. RTCIceTransport objects will be unfrozen according to their index. transport is inserted at index, or at the end if index is not specified. If index is greater than the current number of RTCIceTransports with a component of rtp, throw an InvalidParameters. If transport.state is closed, throw an InvalidStateError. If transport has already been added to another RTCIceTransportController object, or if transport.component is rtcp, throw an InvalidStateError.

Parameter Type Nullable Optional Description
transport RTCIceTransport
index unsigned long
Return type: void
getTransports

Returns the RTCIceTransport objects with a component of rtp. If addTransport() has not been called, an empty list is returned.

No parameters.
Return type: sequence<RTCIceTransport>

Examples

      // This is an example of how to utilize distinct ICE transports for Audio and Video
// as well as for RTP and RTCP. If both sides can multiplex audio/video
// and RTP/RTCP then the multiplexing will occur.
//
// Assume we have an audioTrack and a videoTrack to send.
//
// Include some helper functions
import {trace, errorHandler, mySendLocalCandidate, myIceGathererStateChange,
  myIceTransportStateChange, myDtlsTransportStateChange} from 'helper';
// Create the ICE gather options
var gatherOptions = {
  gatherPolicy: "all",
  iceServers: [
    { urls: "stun:stun1.example.net" },
    { urls: "turn:turn.example.org", username: "user", credential: "myPassword",
      credentialType: "password" }
   ]
};

// Create the RTP and RTCP ICE gatherers for audio and video
var audioRtpIceGatherer = new RTCIceGatherer(gatherOptions);
var audioRtcpIceGatherer = audioRtpIceGatherer.createAssociatedGatherer();
var videoRtpIceGatherer = new RTCIceGatherer(gatherOptions);
var videoRtcpIceGatherer = videoRtpIceGatherer.createAssociatedGatherer();

// Set up the ICE gatherer error handlers
audioRtpIceGatherer.onerror = errorHandler;
audioRtcpIceGatherer.onerror = errorHandler;
videoRtpIceGatherer.onerror = errorHandler;
videoRtcpIceGatherer.onerror = errorHandler;

// Create the RTP and RTCP ICE transports for audio and video
var audioRtpIceTransport = new RTCIceTransport(audioRtpIceGatherer);
var audioRtcpIceTransport = audioRtpIceTransport.createAssociatedTransport();
var videoRtpIceTransport = new RTCIceTransport(videoRtpIceGatherer);
var videoRtcpIceTransport = videoRtpIceTransport.createAssociatedTransport();

// Enable local ICE candidates to be signaled to the remote peer.
audioRtpIceGatherer.onlocalcandidate = function(event) {
  mySendLocalCandidate(event.candidate, "rtp", "audio");
};
audioRtcpIceGatherer.onlocalcandidate = function(event) {
  mySendLocalCandidate(event.candidate, "rtcp", "audio");
};
videoRtpIceGatherer.onlocalcandidate = function(event) {
  mySendLocalCandidate(event.candidate, "rtp", "video");
};
videoRtcpIceGatherer.onlocalcandidate = function(event) {
  mySendLocalCandidate(event.candidate, "rtcp", "video");
};

// Start gathering
audioRtpIceGatherer.gather();
audioRtcpIceGatherer.gather();
videoRtpIceGatherer.gather();
videoRtcpIceGatherer.gather();

// Set up the ICE state change event handlers
audioRtpIceTransport.onstatechange = function(event) {
  myIceTransportStateChange("audioRtpIceTransport", event.state);
};
audioRtcpIceTransport.onstatechange = function(event) {
  myIceTransportStateChange("audioRtcpIceTransport", event.state);
};
videoRtpIceTransport.onstatechange = function(event) {
  myIceTransportStateChange("videoRtpIceTransport", event.state);
};
videoRtcpIceTransport.onstatechange = function(event) {
  myIceTransportStateChange("videoRtcpIceTransport", event.state);
};

// Prepare to add ICE candidates signaled by the remote peer on any of the ICE transports
mySignaller.onRemoteCandidate = function(remote) {
  switch (remote.kind) {
    case "audio":
      if (remote.component === "rtp") {
        audioRtpIceTransport.addRemoteCandidate(remote.candidate);
      } else {
        audioRtcpIceTransport.addRemoteCandidate(remote.candidate);
      }
      break;
    case "video":
      if (remote.component === "rtp") {
        videoRtpIceTransport.addRemoteCandidate(remote.candidate);
      } else {
        videoRtcpIceTransport.addRemoteCandidate(remote.candidate);
      }
      break;
    default:
      trace("Invalid media type received: " + remote.kind);
  }
};
// Create the DTLS certificate
var certs;
var keygenAlgorithm = { name: "ECDSA", namedCurve: "P-256" };
RTCCertificate.generateCertificate(keygenAlgorithm).then(function(certificate){
  certs[0] = certificate;
}, function(){
  trace('Certificate could not be created');
});

// Create the DTLS transports (using the same certificate)
var audioRtpDtlsTransport = new RTCDtlsTransport(audioRtpIceTransport, certs);
var audioRtcpDtlsTransport = new RTCDtlsTransport(audioRtcpIceTransport, certs);
var videoRtpDtlsTransport = new RTCDtlsTransport(videoRtpIceTransport, certs);
var videoRtcpDtlsTransport = new RTCDtlsTransport(videoRtcpIceTransport, certs);

// Create the sender and receiver objects
var audioSender = new RTCRtpSender(audioTrack, audioRtpDtlsTransport, audioRtcpDtlsTransport);
var videoSender = new RTCRtpSender(videoTrack, videoRtpDtlsTransport, videoRtcpDtlsTransport);
var audioReceiver = new RTCRtpReceiver("audio", audioRtpDtlsTransport, audioRtcpDtlsTransport);
var videoReceiver = new RTCRtpReceiver("video", videoRtpDtlsTransport, videoRtcpDtlsTransport);

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

// Exchange ICE/DTLS parameters and Send/Receive capabilities

mySignaller.myOfferTracks({
  // Indicate that the initiator would prefer to multiplex both A/V and RTP/RTCP
  bundle: true,
  // Indicate that the initiator is willing to multiplex RTP/RTCP without A/V mux
  rtcpMux: true,
  // Offer the ICE parameters
  audioRtpIce: audioRtpIceGatherer.getLocalParameters(),
  audioRtcpIce: audioRtcpIceGatherer.getLocalParameters(),
  videoRtpIce: videoRtpIceGatherer.getLocalParameters(),
  videoRtcpIce: videoRtcpIceGatherer.getLocalParameters(),
  // Offer the DTLS parameters
  audioRtpDtls: audioRtpDtlsTransport.getLocalParameters(),
  audioRtcpDtls: audioRtcpDtlsTransport.getLocalParameters(),
  videoRtpDtls: videoRtpDtlsTransport.getLocalParameters(),
  videoRtcpDtls: videoRtcpDtlsTransport.getLocalParameters(),
  // Offer the receiver and sender audio and video capabilities.
  recvAudioCaps: recvAudioCaps,
  recvVideoCaps: recvVideoCaps,
  sendAudioCaps: sendAudioCaps,
  sendVideoCaps: sendVideoCaps
}, function(answer) {
  // The responder answers with its preferences, parameters and capabilities
  // Since we didn"t create transport arrays, we are assuming that there
  // is no forking (only one response)
  //
  // Derive the send and receive parameters, assuming that RTP/RTCP mux will be enabled.
  var audioSendParams = myCapsToSendParams(sendAudioCaps, answer.recvAudioCaps);
  var videoSendParams = myCapsToSendParams(sendVideoCaps, answer.recvVideoCaps);
  var audioRecvParams = myCapsToRecvParams(recvAudioCaps, answer.sendAudioCaps);
  var videoRecvParams = myCapsToRecvParams(recvVideoCaps, answer.sendVideoCaps);
  //
  // If the responder wishes to enable bundle, we will enable it
  if (answer.bundle) {
    // Since bundle implies RTP/RTCP multiplexing, we only need a single
    // ICE transport and DTLS transport. No need for the ICE transport controller.
    audioRtpIceTransport.start(audioRtpIceGatherer, answer.audioRtpIce, RTCIceRole.controlling);
    audioRtpDtlsTransport.start(remote.audioRtpDtls);
    //
    // Replace the transport on the Sender and Receiver objects
    //
    audioSender.setTransport(audioRtpDtlsTransport);
    videoSender.setTransport(audioRtpDtlsTransport);
    audioReceiver.setTransport(audioRtpDtlsTransport);
    videoReceiver.setTransport(audioRtpDtlsTransport);
    // If BUNDLE was requested, then also assume RTP/RTCP mux
    answer.rtcpMux = true;
  } else {
    var controller = new RTCIceTransportController();
    if (answer.rtcpMux) {
      // The peer doesn"t want BUNDLE, but it does want to multiplex RTP/RTCP
      // Now we need audio and video ICE transports
      // as well as an ICE Transport Controller object
      controller.addTransport(audioRtpIceTransport);
      controller.addTransport(videoRtpIceTransport);
      // Start the audio and video ICE transports
      audioRtpIceTransport.start(audioRtpIceGatherer, answer.audioRtpIce, RTCIceRole.controlling);
      videoRtpIceTransport.start(videoRtpIceGatherer, answer.videoRtpIce, RTCIceRole.controlling);
      // Start the audio and video DTLS transports
      audioRtpDtlsTransport.onerror = errorHandler;
      audioRtpDtlsTransport.start(answer.audioRtpDtls);
      videoRtpDtlsTransport.onerror = errorHandler;
      videoRtpDtlsTransport.start(answer.videoRtpDtls);
      // Replace the transport on the Sender and Receiver objects
      //
      audioSender.setTransport(audioRtpDtlsTransport);
      videoSender.setTransport(videoRtpDtlsTransport);
      audioReceiver.setTransport(audioRtpDtlsTransport);
      videoReceiver.setTransport(videoRtpDtlsTransport);
    } else {
      // We arrive here if the responder does not want BUNDLE
      // or RTP/RTCP multiplexing
      //
      // Now we need all the audio and video RTP and RTCP ICE transports
      // as well as an ICE Transport Controller object
      controller.addTransport(audioRtpIceTransport);
      controller.addTransport(videoRtpIceTransport);
      // Start the ICE transports
      audioRtpIceTransport.start(audioRtpIceGatherer, answer.audioRtpIce, RTCIceRole.controlling);
      audioRtcpIceTransport.start(audioRtcpIceGatherer, answer.audioRtcpIce,
        RTCIceRole.controlling);
      videoRtpIceTransport.start(videoRtpIceGatherer, answer.videoRtpIce, RTCIceRole.controlling);
      videoRtcpIceTransport.start(videoRtcpIceGatherer, answer.videoRtcpIce,
        RTCIceRole.controlling);
      // Start the DTLS transports that are needed
      audioRtpDtlsTransport.start(answer.audioRtpDtls);
      audioRtcpDtlsTransport.start(answer.audioRtcpDtls);
      videoRtpDtlsTransport.start(answer.videoRtpDtls);
      videoRtcpDtlsTransport.start(answer.videoRtcpDtls);
      // Disable RTP/RTCP multiplexing
      audioSendParams.rtcp.mux = false;
      videoSendParams.rtcp.mux = false;
      audioRecvParams.rtcp.mux = false;
      videoRecvParams.rtcp.mux = false;
    }
  }
  // Set the audio and video send and receive parameters.
  audioSender.send(audioSendParams).then(function() {
    trace("Set audio sender parameters");
    }, function() {
      trace("Could not set audio sender parameters");
    }
  );
  videoSender.send(videoSendParams).then(function() {
    trace("Set video sender parameters");
    }, function() {
      trace("Could not set video sender parameters");
    }
  );
  audioReceiver.receive(audioRecvParams).then(function() {
    trace("Set audio receiver parameters");
    }, function() {
      trace("Could not set audio receiver parameters");
    }
  );
  videoReceiver.receive(videoRecvParams).then(function() {
    trace("Set video receiver parameters");
    }, function() {
      trace("Could not set video receiver parameters");
    }
  );
// Now we can render/play audioReceiver.track and videoReceiver.track
                

RTCRtpListener Interface

The RTCRtpListener listens to RTP packets received from the RTCDtlsTransport, determining whether an incoming RTP stream is configured to be processed by an existing RTCRtpReceiver object. If no match is found, the unhandledrtp event is fired. This can be due to packets having an unknown SSRC, payload type or any other error that makes it impossible to attribute an RTP packet to a specific RTCRtpReceiver object. The event is not fired once for each arriving packet; multiple discarded packets for the same SSRC SHOULD result in a single event.

Note that application handling of the unhandledrtp event may not be sufficient to enable the unhandled RTP stream to be rendered. The amount of buffering to be provided for unhandled RTP streams is not mandated by this specification and is recommended to be strictly limited to protect against denial of service attacks. Therefore an application attempting to create additional RTCRtpReceiver objects to handle the incoming RTP stream may find that portions of the incoming RTP stream were lost due to insufficient buffers, and therefore could not be rendered.

Overview

An RTCRtpListener instance is associated to an RTCDtlsTransport.

Operation

An RTCRtpListener instance is constructed from an RTCDtlsTransport object.

RTP matching rules

In ORTC, RTP packets are delivered to RTCRtpReceiver objects by the RTCRtpListener. When the RTCRtpListener receives an RTP packet over an RTCDtlsTransport, it attempts to determine which RTCRtpReceiver object to deliver the packet to, based on the values of the SSRC and payload type fields in the RTP header, as well as the value of the MID RTP header extension, if present. If the RTCRtpReceiver object to deliver the RTP packet to cannot be determined, the unhandledrtp event is fired.

Table entries referencing the RTCRtpReceiver object receiver are added when receiver.receive(parameters) is called. When receiver.receive(parameters) is called again, changes are made to table entries. When receiver.stop is called, all entries referencing receiver are removed.

[[!BUNDLE]] Section 10.2 describes the algorithm used in WebRTC for routing of RTP streams received over a shared transport to an SDP m-line (representing an RTCRtpSender/RTCRtpReceiver pair). This is based on tables containing SSRC, PT and MID entries. When multiple RTCRtpReceiver or RTCRtpSender objects share a RTCDtlsTransport, this implies that they also share a single SSRC numbering space [[!RFC3550]]. The restrictions arising from this are described in [[!BUNDLE]] Sections 10.1 and 10.1.1.

ORTC routing rules

Since ORTC does not utilize SDP, this section provides a (non-normative) example of how the RTCRtpListener can maintain the tables described in [[!BUNDLE]] Section 10.2: the ssrc_table which maps SSRC values to RTCRtpReceiver objects, the muxId_table which maps values of the MID header extension to RTCRtpReceiver objects and the pt_table which maps payload type values to RTCRtpReceiver objects. When receiver.receive(parameters) is called, the tables are filled as follows:

muxId table:

  1. If parameters.muxId is set, muxId_table[parameters.muxId] is set to receiver.
  2. If muxId_table[muxId] is already set to a value other than receiver, then receiver.receive() will be rejected with InvalidParameters.

SSRC table:

  1. Set ssrc_table[parameters.encodings[i].ssrc] to receiver for each entry where parameters.encodings[i].ssrc is set, for values of i from 0 to encodings.length-1.
  2. Set ssrc_table[parameters.encodings[i].rtx.ssrc] to receiver for each entry where parameters.encodings[i].rtx.ssrc is set, for values of i from 0 to encodings.length-1.
  3. Set ssrc_table[parameters.encodings[i].fec.ssrc] to receiver for each entry where parameters.encodings[i].fec.ssrc is set, for values of i from 0 to encodings.length-1.
  4. If ssrc_table[ssrc] is already set to a value other than receiver, then receiver.receive() will be rejected with InvalidParameters.

payload type table:

  1. If parameters.encodings[i].ssrc is unset for all values of i from 0 to encodings.length-1, then add entries to pt_table by setting pt_table[parameters.codecs[j].payloadType] to receiver, for values of j from 0 to codecs.length-1.
  2. If pt_table[pt] is already set to a value other than receiver then receiver.receive() is rejected with InvalidParameters.

RTP packet handling

When an RTP packet arrives, the implementation determines the RTCRtpReceiver rtp_receiver to send it to as follows:

    If packet.muxId is set:
    1. If muxId_table[packet.muxId] is unset, fire the unhandledrtp event, and abort these steps.
    2. Check whether the value of packet.pt is equal to one of the values of parameters.codecs[j].payloadtype for the RTCRtpReceiver object rtp_receiver, where j varies from 0 to codecs.length-1. If packet.pt does not match, fire the unhandledrtp event and abort these steps.
    3. Set rtp_receiver to muxId_table[packet.muxId].
    4. Set ssrc_table[packet.ssrc] to rtp_receiver.
    5. Route the packet to rtp_receiver and abort these steps.
    Else if ssrc_table[packet.ssrc] is set:
    1. Check whether the value of packet.pt is equal to one of the values of parameters.codecs[j].payloadtype for the RTCRtpReceiver object rtp_receiver, where j varies from 0 to codecs.length-1. If packet.pt does not match, fire the unhandledrtp event and abort these steps.
    2. Set rtp_receiver to ssrc_table[packet.ssrc].
    3. Route the packet to rtp_receiver and abort these steps.
    Else if pt_table[packet.pt] is set:
    1. Set rtp_receiver to pt_table[packet.pt].
    2. Set ssrc_table[packet.ssrc] to rtp_receiver.
    3. Route the packet to rtp_receiver and abort these steps.
    If no matches are found in the ssrc_table, muxId_table or pt_table, fire the unhandledrtp event.

Interface Definition

[ Constructor (RTCDtlsTransport transport), Exposed=Window]
interface RTCRtpListener {
    readonly        attribute RTCDtlsTransport transport;
                    attribute EventHandler     onunhandledrtp;
};

Constructors

RTCRtpListener
Parameter Type Nullable Optional Description
transport RTCDtlsTransport

Attributes

transport of type RTCDtlsTransport, readonly

The RTP RTCDtlsTransport instance.

onunhandledrtp of type EventHandler

The event handler which handles the RTCRtpUnhandledEvent, which is fired when the RTCRtpListener detects an RTP stream that is not configured to be processed by an existing RTCRtpReceiver object.

RTCRtpUnhandledEvent

The unhandledrtp event of the RTCRtpListener object uses the RTCRtpUnhandledEvent interface.

Firing an RTCRtpUnhandledEvent event named e 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 RTCRtpUnhandledEvent interface MUST be created and dispatched at the given target.

        [ Constructor (DOMString type, RTCRtpUnhandledEventInit eventInitDict), Exposed=Window]
interface RTCRtpUnhandledEvent : Event {
    readonly        attribute DOMString     muxId;
    readonly        attribute DOMString     rid;
    readonly        attribute payloadtype   payloadType;
    readonly        attribute unsigned long ssrc;
};

Constructors

RTCRtpUnhandledEvent
Parameter Type Nullable Optional Description
type DOMString
eventInitDict RTCRtpUnhandledEventInit

Attributes

muxId of type DOMString, readonly

The value of the MID RTP header extension [[!BUNDLE]] in the RTP stream triggering the unhandledrtp event. If receive() has not been called, the MID header extension cannot be decoded, so that muxId will be unset.

rid of type DOMString, readonly

The value of the RID RTP header extension [[!RID]] in the RTP stream triggering the unhandledrtp event. If receive() has not been called, the RID header extension cannot be decoded, so that rid will be unset.

payloadType of type payloadtype, readonly

The Payload Type value in the RTP stream triggering the unhandledrtp event.

ssrc of type unsigned long, readonly

The SSRC in the RTP stream triggering the unhandledrtp event.

The RTCRtpUnhandledEventInit dictionary provides information on the RTP packet causing the RTCRtpUnhandledEvent.

dictionary RTCRtpUnhandledEventInit : EventInit {
             DOMString     muxId;
             DOMString     rid;
             payloadtype   payloadType;
             unsigned long ssrc;
};

Dictionary RTCRtpUnhandledEventInit Members

muxId of type DOMString

If present, the value of the MID RTP header extension [[!BUNDLE]] in the RTP stream triggering the unhandledrtp event.

rid of type DOMString

If present, the value of the RID RTP header extension [[!RID]] in the RTP stream triggering the unhandledrtp event.

payloadType of type payloadtype

The Payload Type value in the RTP stream triggering the unhandledrtp event.

ssrc of type unsigned long

The SSRC in the RTP stream triggering the unhandledrtp event.

Dictionaries related to Rtp

RTCRtpCapabilities Dictionary

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

dictionary RTCRtpCapabilities {
             sequence<RTCRtpCodecCapability> codecs;
             sequence<RTCRtpHeaderExtension> headerExtensions;
             sequence<DOMString>             fecMechanisms;
};

Dictionary RTCRtpCapabilities Members

codecs of type sequence<RTCRtpCodecCapability>

Supported codecs.

headerExtensions of type sequence<RTCRtpHeaderExtension>

Supported RTP header extensions.

fecMechanisms of type sequence<DOMString>

Supported Forward Error Correction (FEC) mechanisms and combinations. Supported values are "red" [[!RFC2198]], "red+ulpfec" [[RFC5109]] and "flexfec" [[FLEXFEC]]. Note that supported mechanisms also need to be included within RTCRtpCapabilities.codecs[]. [[FEC]] summarizes requirements relating to FEC mechanisms.

RTCRtcpFeedback Dictionary

RTCRtcpFeedback provides information on RTCP feedback messages.

dictionary RTCRtcpFeedback {
             DOMString type;
             DOMString parameter;
};

Dictionary RTCRtcpFeedback Members

type of type DOMString

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]] and "transport-cc" [[TRANSPORT-CC]].

parameter of type DOMString

For a type value 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 value of "ccm", valid values for parameter are the "Codec Control Messages" enumerated in [[!IANA-SDP-19]] ("fir", "tmmbr" (includes "tmmbn"), etc.).

RTCRtpCodecCapability Dictionary

The RTCRtpCodecCapability dictionary provides information on the capabilities of a codec. Exactly one RTCRtpCodecCapability will be present for each supported combination of parameters that requires a distinct value of preferredPayloadType. For example:

  1. Multiple "h264" codecs, each with their own distinct packetization-mode values.
  2. "cn" codecs, each with distinct clockRate values.
typedef object Dictionary;
Throughout this specification, the identifier Dictionary is used to refer to the object type.
typedef octet payloadtype;
Throughout this specification, the identifier payloadtype is used to refer to the octet type.
dictionary RTCRtpCodecCapability {
             DOMString                 name;
             DOMString                 mimeType;
             DOMString                 kind;
             unsigned long             clockRate;
             payloadtype               preferredPayloadType;
             unsigned long             maxptime;
             unsigned long             ptime;
             unsigned long             channels;
             sequence<RTCRtcpFeedback> rtcpFeedback;
             Dictionary                parameters;
             Dictionary                options;
             unsigned short            maxTemporalLayers = 0;
             unsigned short            maxSpatialLayers = 0;
             boolean                   svcMultiStreamSupport;
};

Dictionary RTCRtpCodecCapability Members

name of type DOMString

The MIME media subtype. Valid subtypes are listed in [[!IANA-RTP-2]].

mimeType of type DOMString

The codec MIME media type/subtype. Valid media types and subtypes are listed in [[IANA-RTP-2]].

kind of type DOMString

The media supported by the codec: "audio", "video", etc.

clockRate of type unsigned long

Codec clock rate expressed in Hertz. If unset, the codec is applicable to any clock rate.

preferredPayloadType of type payloadtype

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 preferredPayloadType MUST be unique.

maxptime of type unsigned long

The maximum packetization time supported by the RTCRtpReceiver.

ptime of type unsigned long

The preferred duration of media represented by a packet in milliseconds for the RTCRtpSender or RTCRtpReceiver.

channels of type unsigned long

The number of channels supported (e.g. two for stereo). For video, this attribute is unset.

rtcpFeedback of type sequence<RTCRtcpFeedback>

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

parameters of type Dictionary

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

options of type Dictionary

Codec-specific parameters that may be optionally signalled and are available as additional supported information or settings about the codec.

maxTemporalLayers of type unsigned short, defaulting to 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.

maxSpatialLayers of type unsigned short, defaulting to 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.

svcMultiStreamSupport of type boolean

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

Codec capability options

The capability options of commonly implemented codecs are provided below.

If a defined codec option is unset when returned from RTCRtpReceiver/Sender.getCapabilities(), then the engine does not allow adjusting the option. If set when returned from RTCRtpReceiver/Sender.getCapabilities() then the default value for the engine is given.

Opus

The following capability options are defined for Opus:

Property Name Values Receiver/Sender Notes
complexity unsigned long Sender Indicates the default value for the encoder's computational complexity. The supported range is 0-10 with 10 representing the highest complexity.
signal DOMString Sender Indicates the default value for the type of signal being encoded. Possible values are "auto", "music" and "voice".
application DOMString Sender Indicates the default value for the encoder's intended application. Possible values are "voip", "audio" and "lowdelay".
packetlossperc unsigned long Sender Indicates the default value for the encoder's expected packet loss percentage. Possible values are 0-100.
predictiondisabled boolean Sender Indicates the default value for whether prediction is disabled, making frames almost complete independent (if true) or not (if false).

Codec capability parameters

The capability parameters for commonly implemented codecs are provided below.

If a defined codec capability parameter is unset when returned from RTCRtpReceiver/Sender.getCapabilities(), then the engine does not allow adjusting the parameter. If set when returned from RTCRtpReceiver/Sender.getCapabilities() then the default value for the engine is given.

Opus

The following optional capability parameters are defined for "opus", as noted in [[!RFC7587]] Section 6.1:

Property Name Values Receiver/Sender Notes
maxplaybackrate unsigned long Receiver A hint about the maximum output sampling rate that the receiver is capable of rendering in Hz.
sprop-maxcapturerate unsigned long Sender A hint about the maximum input sampling rate that the sender is likely to produce.
maxaveragebitrate unsigned long Receiver Specifies the maximum average receive bitrate of a session in bits per second (bits/s).
cbr boolean Receiver Specifies if the decoder prefers the use of constant bitrate (if true) or variable bitrate (if false).
useinbandfec boolean Receiver Specifies if the decoder has the capability to take advantage of Opus in-band fec (if true) or not (if false).
usedtx boolean Receiver Specifies if the decoder prefers the use of DTX (if true) or not (if false).

VP8

The following receiver capability parameters are defined for "vp8", as noted in [[RFC7741]] 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.

H.264

The following capability parameters are defined for "h264", as noted in [[RFC6184]] Section 8.1, and [[!RFC7742]] Section 6.2.

Property Name Values Receiver/Sender Notes
profile-level-id DOMString Receiver/Sender This parameter is encoded as a string representation of 6 upper case hexadecimal digits, representing the profile-level-id parameter described in [[RFC6184]] Section 8.1. It represents the maximum capability of the decoder (for an RTCRtpReceiver) or the encoder (for an RTCRtpSender). It MUST be supported, as noted in [[!RFC7742]] Section 6.2.
packetization-mode unsigned short Receiver/Sender An unsigned short, ranging from 0 to 2, indicating a supported packetization-mode value. As noted in [[!RFC7742]] Section 6.2, support for a value of 1 is mandatory.
max-mbps, max-smbps, max-fs, max-cpb, max-dpb, max-br unsigned long long Receiver As noted in [[!RFC7742]] Section 6.2, these optional parameters allow the implementation to specify that the decoder can support certain features of H.264 at higher rates and values than those signalled with profile-level-id.

RTX

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

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 RTCRtpCapabilities.codecs[] for each media codec that can be retransmitted, each with their own apt parameter. This makes it possible to support "capabilities exchange" signaling as well enabling implementations to indicate which media codecs support retransmission.
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.

RED

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

Ulpfec

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

Flexfec

The following capability parameters are defined for "flexfec", as noted in [[FLEXFEC]] Section 5.1.1:

Property Name Values Receiver/Sender Notes
repair-window unsigned long long Sender The default time that spans the source packets and the corresponding repair packets, in microseconds.
L unsigned long Sender The default number of columns of the source block that are protected by this FEC block.
D unsigned long Sender The default number of rows of the source block that are protected by this FEC block.
ToP unsigned short Sender The default type of protection for the sender: 0 for 1-D interleaved FEC protection, 1 for 1-D non-interleaved FEC protection, and 2 for 2-D parity FEC protection. The value of 3 is reserved for future use.

RTCRtpParameters Dictionary

RTCRtpParameters contains the RTP stack settings.

dictionary RTCRtpParameters {
             DOMString                                 muxId = "";
    required sequence<RTCRtpCodecParameters>           codecs;
             sequence<RTCRtpHeaderExtensionParameters> headerExtensions;
             sequence<RTCRtpEncodingParameters>        encodings;
             RTCRtcpParameters                         rtcp;
             RTCDegradationPreference                  degradationPreference;
};

Dictionary RTCRtpParameters Members

muxId of type DOMString, defaulting to ""

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. Since muxId is included in RTCRtpParameters but not in RTCRtpEncodingParameters, if it is desired to send simulcast streams with different muxId values for each stream, then multiple RTCRtpSender objects are needed.

codecs of type sequence<RTCRtpCodecParameters>, required

The codecs to send or receive (could include "red" [[RFC2198]], "rtx" [[!RFC4588]] and "cn" [[RFC3389]]). codecs MUST be set for an RTCRtpParameters object to be a valid argument passed to send() or receive().

headerExtensions of type sequence<RTCRtpHeaderExtensionParameters>

Configured header extensions. If unset, no header extensions are configured.

encodings of type sequence<RTCRtpEncodingParameters>

The "encodings" or "layers" to be used for things like simulcast, Scalable Video Coding, RTX, FEC, etc. A sender MAY send fewer layers than what is specified in encodings[], but MUST NOT send more. When unset in a call to send(), the browser behaves as though a single encodings[0] entry was provided, with encodings[0].ssrc set to a browser-determined value, encodings[0].active set to true, encodings[0].codecPayloadType set to codecs[j].payloadType where j is the index of the first codec that is not "cn", "telephone-event", "red", "rtx" or a forward error correction codec ("ulpfec" [[RFC5109]] or "flexfec" [[FLEXFEC]]), and all the other parameters.encodings[0] attributes (e.g. fec, rtx, priority, maxBitrate, resolutionScale, etc.) unset. When unset in a call to receive(), the behavior is described in Section 8.3.

rtcp of type RTCRtcpParameters

Parameters to configure RTCP. If unset, the default values described in Section 9.6.1 are assumed.

degradationPreference of type RTCDegradationPreference

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. If unset, "balanced" is assumed.

RTCDegradationPreference Enum

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

enum RTCDegradationPreference {
    "maintain-framerate",
    "maintain-resolution",
    "balanced"
};
Enumeration description
maintain-framerate

Degrade resolution in order to maintain framerate.

maintain-resolution

Degrade framerate in order to maintain resolution.

balanced

Degrade a balance of framerate and resolution.

RTCRtcpParameters Dictionary

RTCRtcpParameters provides information on RTCP settings.

dictionary RTCRtcpParameters {
             unsigned long ssrc;
             DOMString     cname;
             boolean       reducedSize = false;
             boolean       mux = true;
};

Dictionary RTCRtcpParameters Members

ssrc of type unsigned long

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). It can only be set for an RTCRtpReceiver. Other than for debugging, or situations where receive() is called before send() on the same RTCDtlsTransport it is best to leave it unset, in which case ssrc is chosen by the browser, though 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]]. Where send(parameters) is called before receive() on the same RTCDtlsTransport, the browser can choose one of the SSRCs allocated to an RTCRtpSender of the same kind. Where receive() is called first, a random SSRC value can be chosen.

cname of type DOMString

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 the CNAME only for an RTCRtpReceiver; if unset, the CNAME is chosen by the browser.

reducedSize of type boolean, defaulting to false

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

mux of type boolean, defaulting to true

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

RTCRtpCodecParameters Dictionary

RTCRtpCodecParameters provides information on codec settings.

dictionary RTCRtpCodecParameters {
    required DOMString                 name;
             DOMString                 mimeType;
    required payloadtype               payloadType;
             unsigned long             clockRate;
             unsigned long             maxptime;
             unsigned long             ptime;
             unsigned long             channels;
             sequence<RTCRtcpFeedback> rtcpFeedback;
             Dictionary                parameters;
};

Dictionary RTCRtpCodecParameters Members

name of type DOMString, required

The codec MIME subtype. Valid subtypes are listed in [[!IANA-RTP-2]].

mimeType of type DOMString

The codec MIME media type/subtype. Valid media types and subtypes are listed in [[IANA-RTP-2]].

payloadType of type payloadtype, required

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

clockRate of type unsigned long

Codec clock rate expressed in Hertz. If unset, the implementation default is assumed.

maxptime of type unsigned long

The maximum packetization time set on the RTCRtpSender. Not specified if unset. If ptime is also set, maxptime is ignored.

ptime of type unsigned long

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

channels of type unsigned long

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

rtcpFeedback of type sequence<RTCRtcpFeedback>

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

parameters of type Dictionary

Codec-specific parameters available for signaling.

Codec parameters

The parameters of common codecs are described below.

Opus

The following settings are defined for "opus":

Property Name Values Receiver/Sender Notes
maxplaybackrate unsigned long Sender The maximum output sampling rate of the encoder in Hz.
sprop-maxcapturerate unsigned long Receiver The maximum input sampling rate produced by the sender.
cbr boolean Sender Specifies if the encoder is configured to generate constant bitrate (if true) or variable bitrate (if false).
useinbandfec boolean Sender Specifies if the encoder is configured to generate Opus in-band fec (if true) or not (if false).
usedtx boolean Sender Specifies if the encoder is configured to use DTX (if true) or not (if false).
complexity unsigned long Sender Configures the encoder's computational complexity. The supported range is 0-10 with 10 representing the highest complexity.
signal DOMString Sender Configures the type of signal being encoded. Possible values are "auto", "music" and "voice".
application DOMString Sender Configures the encoder's intended application. Possible values are "voip", "audio" and "lowdelay".
packetlossperc unsigned long Sender Configures the encoder's expected packet loss percentage. Possible values are 0-100.
predictiondisabled boolean Sender Configures whether prediction is disabled, making frames almost complete independent (if true) or not (if false).

VP8

The following settings are defined 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.

H.264

The following settings are defined for "h264":

Property Name Values Receiver/Sender Notes
profile-level-id DOMString Sender This parameter, encoded as a string of 6 upper case hexadecimal digits, indicates the configuration of the stream to be sent, as described in [[RFC6184]] Section 8.2.2. It MUST be supported, as noted in [[!RFC7742]] Section 6.2.
packetization-mode unsigned short Sender An unsigned short ranging from 0 to 2, indicating the packetization-mode value to be used by the sender. This setting MUST be supported, as noted in [[!RFC7742]] Section 6.2. A value of 1 is assumed if packetization-mode is not set.
max-mbps, max-smbps, max-fs, max-cpb, max-dpb, max-br unsigned long long Sender These optional settings allow the sender to restrict its output to the maximum values indicated by the receiver.

RTX

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

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.
rtx-time unsigned long Receiver As defined in [[!RFC4588]], the 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.

RED

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, each of which MUST be unique. If payloadTypes is unset, this means that any codec other than "red" or "rtx" can be encapsulsated in RED.

Ulpfec

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

Flexfec

The following settings are defined for "flexfec", as noted in [[FLEXFEC]] Section 5.1.1:

Property Name Values Receiver/Sender Notes
repair-window unsigned long long Receiver The time that spans the source packets and the corresponding repair packets, in microseconds.
L unsigned long Sender The number of columns of the source block that are protected by this FEC block.
D unsigned long Sender The number of rows of the source block that are protected by this FEC block.
ToP unsigned short Sender The type of protection applied by the sender: 0 for 1-D interleaved FEC protection, 1 for 1-D non-interleaved FEC protection, and 2 for 2-D parity FEC protection. The value of 3 is reserved for future use.

RTCRtpEncodingParameters Dictionary

RTCRtpEncodingParameters provides information relating to an encoding. Note that all encoding parameters (such as maxBitrate, maxFramerate and resolutionScale) are applied prior to codec-specific constraints.

dictionary RTCRtpEncodingParameters {
             unsigned long       ssrc;
             payloadtype         codecPayloadType;
             RTCRtpFecParameters fec;
             RTCRtpRtxParameters rtx;
             RTCPriorityType     priority;
             unsigned long       maxBitrate;
             double              resolutionScale;
             double              framerateScale;
             double              maxFramerate;
             boolean             active = true;
             DOMString           encodingId;
             sequence<DOMString> dependencyEncodingIds;
};

Dictionary RTCRtpEncodingParameters Members

ssrc of type unsigned long

The SSRC for this layering/encoding. Multiple RTCRtpEncodingParameters objects can share the same ssrc value (useful, for example, to indicate that different RTX payload types associated to different codecs are carried over the same stream). If ssrc is unset in a RTCRtpEncodingParameters object passed to the receive() method, the next unhandled SSRC will match, and an RTCRtpUnhandledEvent will not be fired. If ssrc is unset in a RTCRtpEncodingParameters object passed to the send() method, the browser will choose, and the chosen value is not reflected in RTCRtpEncodingParameters.ssrc. If the browser chooses the ssrc, it may change it due to a collision without firing an RTCSsrcConflictEvent. If ssrc is set in an RTCRtpEncodingParameters object passed to the send() method and an SSRC conflict is detected within the RTP session, then an RTCSsrcConflictEvent is fired (see Section 5.4).

codecPayloadType of type payloadtype

For per-encoding codec specifications, give the codec payload type here. If unset, the browser will choose the first codec in parameters.codecs[] of the appropriate kind.

fec of type RTCRtpFecParameters

Specifies the FEC mechanism if set.

rtx of type RTCRtpRtxParameters

Specifies the RTX [[!RFC4588]] parameters if set.

priority of type RTCPriorityType

Indicates the priority of this encoding. It is specified in [[RTCWEB-TRANSPORT]], Section 4. For scalable video coding, this parameter is only relevant for the base layer. This parameter is ignored in an RTCRtpReceiver object.

maxBitrate of type unsigned long

Ramp up resolution/quality/framerate until this bitrate, if set; if unset, there is no maximum bitrate. maxBitrate is computed the same way as the Transport Independent Application Specific Maximum (TIAS) bandwidth defined in [[RFC3890]] Section 6.2.2, which is the maximum bandwidth needed without counting IP or other transport layers like TCP or UDP. Summed when using dependent layers. This attribute is ignored in scalable video coding, or for an RTCRtpReceiver.

resolutionScale of type double

If sender.track.kind is "video", the encoder will scale down the resolution of sender.track in each dimension before sending. For example, if the value is 2.0, the video will be scaled down by a factor of at least 2 in each dimension, resulting in sending a video no greater than one quarter size. If the value is 1.0 or unset, the sender will attempt to encode with the resolution of track. For scalable video coding, resolutionScale refers to the aggregate scale down of this layer when combined with all dependent layers.

If resolutionScale is less than 1.0, reject the promise with RangeError when send() or receive() is called. If sender.track.kind is "audio", the value is ignored. This attribute is ignored for an RTCRtpReceiver.

framerateScale of type double

Inverse of the input framerate fraction to be encoded. Example: 1.0 = full framerate, 2.0 = one half of the full framerate. For scalable video coding, framerateScale refers to the inverse of the aggregate fraction of input framerate achieved by this layer when combined with all dependent layers. This attribute is ignored for an RTCRtpReceiver.

maxFramerate of type double

The maximum framerate to use for this encoding, in frames per second. This attribute is not used for scalable video coding. If framerateScale is set, then maxFramerate is ignored. This attribute is ignored for an RTCRtpReceiver.

active of type boolean, defaulting to 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.

encodingId of type DOMString

An identifier for the encoding object. This identifier should be unique within the scope of the localized sequence of RTCRtpEncodingParameters for any given RTCRtpParameters object. Values MUST be composed only of alphanumeric characters (a-z, A-Z, 0-9) up to a maximum of 16 characters. An RTCRtpSender places the value of encodingId into the RID header extension [[!RID]], and an RTCRtpReceiver determines the encodingId that an RTP packet belongs to based on the value of the RID header extension. For a codec (such as VP8) using SRST transport which requires a compliant decoder to be able to decode anything that an encoder can send, it is not required that the encodingId and dependencyEncodingIds be set in order to enable a receiver to decode scalable video coding, and if set, they are ignored by the receiver.

dependencyEncodingIds of type sequence<DOMString>

The encodingIds on which this layer depends. Within this specification encodingIds are permitted only within the same RTCRtpEncodingParameters sequence. In the future if MST were to be supported, then if searching within an encodings[] sequence did not produce a match, then a global search would be carried out. In order to send scalable video coding (SVC), both the encodingId and dependencyEncodingIds are required.

Usage of the attributes is defined in the table below:

Attribute Type Receiver/Sender
ssrc unsigned long Receiver/Sender
codecPayloadType payloadType Receiver/Sender
fec RTCRtpFecParameters Receiver/Sender
rtx RTCRtpRtxParameters Receiver/Sender
priority RTCPriorityType Sender
maxBitrate unsigned long Sender
resolutionScale double Sender
framerateScale double Sender
maxFramerate double Sender
active boolean Receiver/Sender
encodingId DOMString Receiver/Sender
dependencyEncodingIds sequence<DOMString> Receiver/Sender

Examples

Basic Example

          // Send a thumbnail along with regular size, prioritizing the thumbnail (ssrc: 2)
var encodings = [{ ssrc: 1, priority: 1.0 }];
var encodings = [{ ssrc: 2, priority: 10.0 }];

// Sign Language (prefer  framerate)
var encodings = [{ degradationPreference: "maintain-framerate" }];

// Screencast (prefer resolution)
var encodings = [{ degradationPreference: "maintain-resolution" }];

// Remote Desktop (High framerate, must not downscale)
var encodings = [{ degradationPreference: "maintain-framerate" }];

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

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

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

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

Temporal Scalability

          // Example of 3-layer temporal scalability encoding
var encodings = [{
  // Base framerate is one quarter of the input framerate
  encodingId: "0",
  framerateScale: 4.0
}, {
  // Temporal enhancement (half the input framerate when combined with the base layer)
  encodingId: "1",
  dependencyEncodingIds: ["0"],
  framerateScale: 2.0
}, {
  // Another temporal enhancement layer (full input framerate when all layers combined)
  encodingId: "2",
  dependencyEncodingIds: ["0", "1"],
  framerateScale: 1.0
}];

// Example of 3-layer temporal scalability with all but the base layer disabled
var encodings = [{
  encodingId: "0",
  framerateScale: 4.0
}, {
  encodingId: "1",
  dependencyEncodingIds: ["0"],
  framerateScale: 2.0,
  active: false
}, {
  encodingId: "2",
  dependencyEncodingIds: ["0", "1"],
  framerateScale: 1.0,
  active: false
}];

Below is a representation of a 3-layer temporal scalability encoding. In the diagram, I0 is the base layer I-frame, and P0 represents base-layer P-frames. P1 represents the first temporal enhancement layer, and P2 represents the second temporal enhancement layer.

3-layer temporal scalability encoding
3-layer temporal scalability encoding

Spatial Simulcast

          // Example of 3-layer spatial simulcast
var encodings = [{
  // Simulcast layer at one quarter scale
  encodingId: "0",
  resolutionScale: 4.0
}, {
  // Simulcast layer at one half scale
  encodingId: "1",
  resolutionScale: 2.0
}, {
  // Simulcast layer at full scale
  encodingId: "2",
  resolutionScale: 1.0
}];

// Example of 3-layer spatial simulcast with all but the lowest resolution layer disabled
var encodings = [{
  encodingId: "0",
  resolutionScale: 4.0
}, {
  encodingId: "1",
  resolutionScale: 2.0,
  active: false
}, {
  encodingId: "2",
  resolutionScale: 1.0,
  active: false
}];

// Example of 2-layer spatial simulcast combined with 2-layer temporal scalability
var encodings = [{
  // Low resolution base layer (half the input framerate, half the input resolution)
  encodingId: "0",
  resolutionScale: 2.0,
  framerateScale: 2.0
}, {
  // High resolution Base layer (half the input framerate, full input resolution)
  encodingId: "E0",
  resolutionScale: 1.0,
  framerateScale: 2.0
}, {
  // Temporal enhancement to the low resolution base layer (full input framerate, half resolution)
  encodingId: "1",
  dependencyEncodingIds: ["0"],
  resolutionScale: 2.0,
  framerateScale: 1.0
}, {
  // Temporal enhancement to the high resolution base layer (full input framerate and resolution)
  encodingId: "E1",
  dependencyEncodingIds: ["E0"],
  resolutionScale: 1.0,
  framerateScale: 1.0
}];
                    

Below is a representation of 2-layer temporal scalability combined with 2-layer spatial simulcast. Solid arrows represent temporal prediction. In the diagram, I0 is the base-layer I-frame, and P0 represents base-layer P-frames. EI0 is an enhanced resolution base-layer I-frame, and EP0 represents P-frames within the enhanced resolution base layer. P1 represents the first temporal enhancement layer, and EP1 represents a temporal enhancement to the enhanced resolution simulcast base-layer.

2-layer spatial simulcast and temporal scalability encoding
2-layer spatial simulcast and temporal scalability encoding

Spatial Scalability

          // Example of 3-layer spatial scalability encoding
var encodings = [{
  // Base layer with one quarter input resolution
  encodingId: "0",
  resolutionScale: 4.0
}, {
  // Spatial enhancement layer yielding half resolution when combined with the base layer
  encodingId: "1",
  dependencyEncodingIds: ["0"],
  resolutionScale: 2.0
}, {
  // Additional spatial enhancement layer yielding full resolution when combined with all layers
  encodingId: "2",
  dependencyEncodingIds: ["0", "1"],
  resolutionScale: 1.0
}]

// Example of 3-layer spatial scalability with all but the base layer disabled
var encodings = [{
  encodingId: "0",
  resolutionScale: 4.0
}, {
  encodingId: "1",
  dependencyEncodingIds: ["0"],
  resolutionScale: 2.0,
  active: false
}, {
  encodingId: "2",
  dependencyEncodingIds: ["0", "1"],
  resolutionScale: 1.0,
  active: false
}];

// Example of 2-layer spatial scalability combined with 2-layer temporal scalability
var encodings = [{
  // Base layer (half input framerate, half resolution)
  encodingId: "0",
  resolutionScale: 2.0,
  framerateScale: 2.0
}, {
  // Temporal enhancement to the base layer (full input framerate, half resolution)
  encodingId: "1",
  dependencyEncodingIds: ["0"],
  resolutionScale: 2.0,
  framerateScale: 1.0
}, {
  // Spatial enhancement to the base layer (half input framerate, full resolution)
  encodingId: "E0",
  dependencyEncodingIds: ["0"],
  resolutionScale: 1.0,
  framerateScale: 2.0
}, {
  // Temporal enhancement to the spatial enhancement layer (full input framerate, full resolution)
  encodingId: "E1",
  dependencyEncodingIds: ["E0", "1"],
  resolutionScale: 1.0,
  framerateScale: 1.0
}];
                    

Below is a representation of 2-layer temporal scalability combined with 2-layer spatial scalability. Solid arrows represent temporal prediction and dashed arrows represent inter-layer prediction. In the diagram, I0 is the base-layer I-frame, and EI0 is an intra spatial enhancement. P0 represents base-layer P-frames, and P1 represents the first temporal enhancement layer. EP0 represents a resolution enhancement to the base-layer P frames, and EP1 represents a resolution enhancement to the second temporal layer P-frames.

2-layer spatial and temporal scalability encoding
2-layer spatial and temporal scalability encoding

RTCPriorityType Enum

RTCPriorityType can be used to indicate the relative priority of various flows. This allows applications to indicate to the browser whether a particular media flow is high, medium, low or of very low importance to the application. WebRTC uses the priority and Quality of Service (QoS) framework described in [[RTCWEB-TRANSPORT]] and [[!TSVWG-RTCWEB-QOS]] to provide priority and DSCP marketing for packets that will help provide QoS in some networking environments. Applications that use this API should be aware that often better overall user experience is obtained by lowering the priority of things that are not as important rather than raising the the priority of the things that are.

The priority API is marked as a feature at risk, since there is no clear commitment from implementers.

enum RTCPriorityType {
    "very-low",
    "low",
    "medium",
    "high"
};
Enumeration description
very-low

See [[RTCWEB-TRANSPORT]], Section 4.

low

See [[RTCWEB-TRANSPORT]], Section 4.

medium

See [[RTCWEB-TRANSPORT]], Section 4.

high

See [[RTCWEB-TRANSPORT]], Section 4.

RTCRtpFecParameters Dictionary

The RTCRtpFecParameters dictionary contains information relating to Forward Error Correction (FEC) settings.

dictionary RTCRtpFecParameters {
             unsigned long ssrc;
             DOMString     mechanism;
};

Dictionary RTCRtpFecParameters Members

ssrc of type unsigned long

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

mechanism of type DOMString

The Forward Error Correction (FEC) mechanism to use: "red", "red+ulpfec" or "flexfec".

RTCRtpRtxParameters Dictionary

The RTCRtpRtxParameters dictionary contains information relating to retransmission (RTX) settings.

dictionary RTCRtpRtxParameters {
             unsigned long ssrc;
};

Dictionary RTCRtpRtxParameters Members

ssrc of type unsigned long

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

RTX/RED/FEC

Below is an example of how to configure an RTCRtpReceiver to receive video encoded in VP8 or VP9, along with retransmission and forward error correction. In the example, forward error correction is encapsulated in RED, and it is possible to retransmit RED packets. The configuration enables VP8 or VP9 to be received either with or without RED encapsulation. The configuration of an RTCRtpSender would be more prescriptive, at a given time indicating a single encoding: that VP8 or VP9 video should be sent encapsulated within RED or without RED encapsulation.

// Example of RTX and RED + ulpfec
//
// SDP from createOffer() in WebRTC 1.0
//
//   m=video 62125 UDP/TLS/RTP/SAVPF 100 101 116 117 96
//   a=sendonly
//   a=rtpmap:100 VP8/90000
//   a=rtpmap:101 VP9/90000
//   a=rtpmap:116 red/90000
//   a=rtpmap:117 ulpfec/90000
//   a=rtpmap:96 rtx/90000
//   a=fmtp:96 apt=100
//   a=rtpmap:97 rtx/90000
//   a=fmtp:97 apt=101
//   a=rtpmap:98 rtx/90000
//   a=fmtp:98 apt=116
//   a=ssrc-group:FID 2224031971 3254585230
//   a=ssrc:2224031971 cname:oC/i06PA+Lda+t1P
//   a=ssrc:3254585230 cname:oC/i06PA+Lda+t1P
//
//   Define RTCRtpCodecParameters
//
var codecs = [
//   Define VP9 codec parameters
  {
    name: "vp9",
    payloadType: 101,
    clockRate: 90000
  },
//   Define VP8 codec parameters
  {
    name: "vp8",
    payloadType: 100,
    clockRate: 90000
  },
//   Define retransmission of VP9
  {
    name: "rtx",
    payloadType: 97,
    clockrate: 90000,
    parameters: {
      apt: 101
    }
  },
//   Define retransmission of VP8
  {
    name: "rtx",
    payloadType: 96,
    clockrate: 90000,
    parameters: {
      apt: 100
    }
  },
//   Define RED codec parameters
  {
    name: "red",
    payloadType: 116,
    clockRate: 90000,
    parameters: {
      payloadTypes: []
    }
  },
//   Define ulpfec codec parameters
  {
    name: "ulpfec",
    payloadType: 117,
    clockRate: 90000
  },
//   Define RTX codec parameters
  {
    name: "rtx",
    payloadType: 98,
    clockrate: 90000,
    parameters: {
      apt: 116
    }
  }
];
//
//   Define rtx parameters
var rtxParams = {
  ssrc: 3254585230
};
//   Define FEC parameters for "red+ulpfec"
var redulpfec = {
  ssrc: 3254585230,
  mechanism: "red+ulpfec"
};
//   Define RTCRtpEncodingParameters
//
var encodings = [
//   Define VP8 encoding parameters (without RED)
  {
    ssrc: 2224031971,
    codecPayloadType: 100,
    rtx: rtxParams
  },
//   Define VP8 encoding parameters with RED
  {
    ssrc:  2224031971,
    codecPayloadType: 100,
    fec: redulpfec,
    rtx: rtxParams
  },
//   Define VP9 encoding parameters (without RED)
  {
    ssrc:  2224031971,
    codecPayloadType: 101,
    rtx: rtxParams
  },
//   Define VP9 encoding parameters with RED
  {
    ssrc:  2224031971,
    codecPayloadType: 101,
    fec: redulplfec,
    rtx: rtxParams
  }
];
                    

RTCRtpHeaderExtension Dictionary

The RTCRtpHeaderExtension dictionary provides information relating to supported header extensions.

dictionary RTCRtpHeaderExtension {
             DOMString      kind;
             DOMString      uri;
             unsigned short preferredId;
             boolean        preferredEncrypt = false;
};

Dictionary RTCRtpHeaderExtension Members

kind of type DOMString

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

uri of type DOMString

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

preferredId of type unsigned short

The preferred ID value that goes in the packet.

preferredEncrypt of type boolean, defaulting to false

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

RTCRtpHeaderExtensionParameters Dictionary

The RTCRtpHeaderExtensionParameters dictionary enables a header extension to be configured for use within an RTCRtpSender or RTCRtpReceiver. In order to provide the equivalent of the "direction" parameter defined in [[!RFC5285]] Section 5, an application can do the following:

  1. sendonly: Include the header extension only when calling send(parameters).
  2. recvonly: Include the header extension only when calling receive(parameters).
  3. sendrecv: Include the header extension when calling send(parameters) and receive(parameters).
  4. inactive: Don't include the header extension when calling either send(parameters) or receive(parameters).
dictionary RTCRtpHeaderExtensionParameters {
    required DOMString      uri;
    required unsigned short id;
             boolean        encrypt = false;
             Dictionary     parameters;
};

Dictionary RTCRtpHeaderExtensionParameters Members

uri of type DOMString, required

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

id of type unsigned short, required

The value that goes in the packet.

encrypt of type boolean, defaulting to false

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

parameters of type Dictionary

Configuration parameters for the header extension. An example is the "vad" extension attribute in the client-to-mixer header extension, described in [[!RFC6464]] Section 4.

At the time of publication there were no implementations of the parameters dictionary. Most header extensions do not require configuration parameters, and the ORTC Lib implementation assumes that the "V" bit from [[!RFC6464]] is always enabled so that a vad parameter is unnecessary.

RTP header extensions

Registered RTP header extensions are listed in [[!IANA-RTP-10]]. Header extensions mentioned in [[!RTP-USAGE]] and [[!RID]] include:

Header Extension Reference Attributes Notes
Transmission Time Offset [[RFC5450]] None This extension indicates the transmission time offset.
Rapid Synchronization [[RFC6051]] None This extension enables carriage of an NTP-format timestamp, as defined in [[!RFC6051]] Section 3.3.
Client-to-Mixer Audio Level [[!RFC6464]] boolean vad This extension indicates the audio level of the audio sample carried in an RTP packet. For an RTCRtpSender, the vad attribute indicates whether the V bit is in use (true) or not (false). For an RTCRtpReceiver, the vad attribute indicates whether the V bit is provided to the application (true) in RTCRtpContributingSource.voiceActivityFlag or is unset (false).
Mixer-to-Client Audio Level [[RFC6465]] None This extension indicates the audio level of individual conference participants.
Absolute Send Time [[ABS-SEND-TIME]] None This extension indicates the absolute send time.
CVO [[!TS26.114]] Section 7.4.5 None The Coordination of Video Orientation (CVO) extension indicates whether the receiver needs to change the orientation in which it renders the stream.
MID [[!BUNDLE]] None This extension defines a track identifier which can be used to identify the track corresponding to an RTP stream.
RID [[!RID]] None This extension defines an identifier used to carry the encodingId.

RTCDtmfSender Interface

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 sender. If sender.track.kind is not "audio", throw an InvalidParameters.

Interface Definition

[ Constructor (RTCRtpSender sender), Exposed=Window]
interface RTCDtmfSender {
    readonly        attribute boolean      canInsertDTMF;
    readonly        attribute RTCRtpSender sender;
    readonly        attribute DOMString    toneBuffer;
    void insertDTMF (DOMString tones, optional unsigned long duration = 100, optional unsigned long interToneGap = 70);
                    attribute EventHandler ontonechange;
};

Constructors

RTCDtmfSender
Parameter Type Nullable Optional Description
sender RTCRtpSender

Attributes

canInsertDTMF of type boolean, readonly

Whether the RTCDtmfSender is capable of sending DTMF.

sender of type RTCRtpSender, readonly

The RTCRtpSender instance

toneBuffer of type DOMString, readonly

The toneBuffer attribute returns a list of the tones remaining to be played out. For the syntax, content, and interpretation of this list, see insertDTMF.

ontonechange of type EventHandler

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

Methods

insertDTMF

The insertDTMF() method is used to send DTMF tones. The tones parameter is treated as a series of characters. The characters 0 through 9, A through D, #, and * generate the associated DTMF tones. The characters a to d MUST be normalized to uppercase on entry and are equivalent to A to D. As noted in [[!RFC7874]] Section 3, support for the characters 0 through 9, A through D, #, and * are required. The character ',' MUST be supported, and indicates a delay of 2 seconds before processing the next character in the tones parameter. All other characters (and only those 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 in ms. The user agent clamps it to at least 30 ms and at most 6000 ms. The default value is 70 ms.

Implementations 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. let sender be the RTCRtpSender used to send DTMF.
  2. If sender's [[\RtpSenderIsStopped]] slot is true, throw an InvalidStateError and abort these steps.
  3. If sender.send has not been called, throw an InvalidStateError and abort these steps.
  4. Let parameters be the argument provided to sender.send the last time it was called.
  5. If parameters.codecs[j] is not equal to "telephone-event" for any value of j, throw an InvalidStateError and abort these steps.
  6. Let tones be the method's first argument.
  7. If tones contains any unrecognized characters, throw an InvalidCharacterError and abort these steps.
  8. Set the object's toneBuffer attribute to tones.
  9. If the value of the duration parameter is less than 40, set it to 40. If, on the other hand, the value is greater than 6000, set it to 6000.
  10. If the value of the interToneGap parameter is less than 30, set it to 30. If, on the other hand, the value is greater than 6000, set it to 6000.
  11. If toneBuffer is an empty string, abort these steps.
  12. 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 sender's [[\RtpSenderIsStopped]] slot is true, abort these steps.
    2. If toneBuffer is an empty string, fire an event named tonechange with an empty string at the RTCDtmfSender object and abort these steps.
    3. Remove the first character from toneBuffer and let that character be tone.
    4. If tone is "," delay sending tones for 2000 ms on the associated RTP media stream, and queue a task to be executed in 2000 ms from now that runs the steps labelled Playout task.
    5. If tone is not "," start playout of tone for duration ms on the associated RTP media stream, using the appropriate codec, then queue a task to be executed in duration + interToneGap ms from now that runs the steps labelled Playout task.
    6. Fire an event named tonechange with a string consisting of tone at the RTCDtmfSender object.

Since insertDTMF replaces the tone buffer, in order to add to the DTMF tones being played, it is necessary to call insertDTMF with a string containing both the remaining tones (stored in toneBuffer) and the new tones appended together.

Calling insertDTMF with an empty tones parameter can be used to cancel all tones queued to play after the currently playing tone.

Parameter Type Nullable Optional Description
tones DOMString
duration unsigned long = 100
interToneGap unsigned long = 70
Return type: void

RTCDTMFToneChangeEvent

The tonechange event uses the RTCDTMFToneChangeEvent interface.

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

        [ Constructor (DOMString type, RTCDTMFToneChangeEventInit eventInitDict), Exposed=Window]
interface RTCDTMFToneChangeEvent : Event {
    readonly        attribute DOMString tone;
};

Constructors

RTCDTMFToneChangeEvent
Parameter Type Nullable Optional Description
type DOMString
eventInitDict RTCDTMFToneChangeEventInit

Attributes

tone of type DOMString, readonly

The tone attribute contains the character for the tone (including ",") that has just begun playout (see insertDTMF ). If the value is the empty string, it indicates that the toneBuffer is an empty string and that the previous tones have completed playback.

The RTCDTMFToneChangeEventInit dictionary provides information on the DTMF tone causing a tonechange event.

dictionary RTCDTMFToneChangeEventInit : EventInit {
             required DOMString tone;
};

Dictionary RTCDTMFToneChangeEventInit Members

tone of type DOMString, defaulting to ""

The tone attribute contains the character for the tone (including ",") that has just begun playout (see insertDTMF ). If the value is the empty string, it indicates that the toneBuffer is an empty string and that the previous tones have completed playback.

RTCDTMFSender Interface

Overview

An RTCDTMFSender instance allows sending DTMF tones to/from the remote peer in a manner identical to that of the RTCDtmfSender interface.

Operation

An RTCDTMFSender object is constructed from an RTCRtpSender sender, as with RTCDtmfSender. If sender.track.kind is not "audio", throw an InvalidParameters.

Interface Definition

The RTCDTMFSender interface is identical to the RTCDtmfSender interface aside from spelling.

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 "123" and abort after sending "2".

var sender = new RTCDtmfSender(sendObject);
if (sender.canInsertDTMF) {
  sender.ontonechange = function (e) {
      if (e.tone == "2")
          // empty the buffer to not play any tone after "2"
          sender.insertDTMF("");
  };
  sender.insertDTMF("123");
} 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);
if (sender.canInsertDTMF) {
  var duration = 500;
  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, duration, "");
  };
  sender.insertDTMF(sender.toneBuffer + "1234");
} else
    trace("DTMF function not available");

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);
if (sender.canInsertDTMF) {
  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");
  };
} else
    trace("DTMF function not available");    

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

var sender = new RTCDtmfSender(sendObject);
if (sender.canInsertDTMF) {
  sender.ontonechange = function (e) {
      if (e.tone == "1")
          sender.insertDTMF(sender.toneBuffer + "2", 2000);
  };
  sender.insertDTMF(sender.toneBuffer + "1", 1000);
} else
    trace("DTMF function not available");

RTCDataChannel Interface

Overview

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

Operation

An RTCDataChannel object is constructed from a RTCDataTransport object (providing the transport for the data channel) and an RTCDataChannelParameters object. An RTCDataChannel object can be garbage-collected once readyState is closed and it is no longer referenced.

When the constructor is invoked, the following steps MUST be run:

  1. Let transport be the first argument.
  2. If transport.state is closed, throw an InvalidStateError.
  3. Let parameters be the second argument.
  4. If parameters.label is longer than 65535 bytes, throw a TypeError.
  5. If parameters.protocol is longer than 65535 bytes, throw a TypeError.
  6. If parameters.negotiated is true and parameters.id is null, throw a TypeError.
  7. If both parameters.maxPacketLifetime and parameters.maxRetransmits are set (not null), throw a TypeError.
  8. If parameters.id is being used by an existing RTCDataChannel, throw an OperationError.
  9. If parameters.id is equal to 65535, which is greater than the maximum allowed ID of 65534, throw a TypeError.

Interface Definition

The RTCDataChannel interface represents a bi-directional data channel between two peers. Each RTCDataChannel has an associated underlying data transport that is used to transport actual data to the other peer. The transport properties of the underlying data transport, such as in order delivery settings and reliability mode, are configured by the peer as the channel is created. The properties of a channel cannot change after the channel has been created.

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

There are two ways to establish a connection with RTCDataChannel. The first way is to construct an RTCDataChannel at one of the peers with the RTCDataChannelParameters.negotiated attribute unset or set to its default value false. This will announce the new channel in-band and trigger an ondatachannel event with the corresponding RTCDataChannel object at the other peer.

The second way is to let the application negotiate the RTCDataChannel. To do this, create an RTCDataChannel object with the RTCDataChannelParameters.negotiated dictionary member set to true, and signal out-of-band (e.g. via a web server) to the other side that it should create a corresponding RTCDataChannel with the RTCDataChannelParameters.negotiated dictionary member set to true and the same id. This will connect the two separately created RTCDataChannel objects. The second way makes it possible to create channels with asymmetric properties and to create channels in a declarative way by specifying matching ids.

        [ Constructor (RTCDataTransport transport, RTCDataChannelParameters parameters), Exposed=Window]
interface RTCDataChannel : EventTarget {
    readonly        attribute RTCDataTransport    transport;
    readonly        attribute RTCDataChannelState readyState;
    readonly        attribute unsigned long       bufferedAmount;
                    attribute unsigned long       bufferedAmountLowThreshold;
                    attribute DOMString           binaryType;
    RTCDataChannelParameters getParameters ();
    void                     close ();
                    attribute EventHandler        onopen;
                    attribute EventHandler        onbufferedamountlow;
                    attribute EventHandler        onerror;
                    attribute EventHandler        onclose;
                    attribute EventHandler        onmessage;
    void                     send (USVString data);
    void                     send (Blob data);
    void                     send (ArrayBuffer data);
    void                     send (ArrayBufferView data);
};

Constructors

RTCDataChannel
Parameter Type Nullable Optional Description
transport RTCDataTransport
parameters RTCDataChannelParameters

Attributes

transport of type RTCDataTransport, readonly

The readonly attribute referring to the related transport object.

readyState of type RTCDataChannelState, readonly

The readyState attribute represents the state of the RTCDataChannel object. It MUST return the value to which the user agent last set it (as defined by the processing model algorithms).

bufferedAmount of type unsigned long, readonly

The bufferedAmount attribute MUST return the number of bytes of application data (UTF-8 text and binary data) that have been queued using send() but that, as of the last time the event loop started executing a task, had not yet been transmitted to the network. This includes any text sent during the execution of the current task, regardless of whether the user agent is able to transmit text asynchronously with script execution. This does not include framing overhead incurred by the protocol, or buffering done by the operating system or network hardware. If the channel is closed, this attribute's value will only increase with each call to the send() method (the attribute does not reset to zero once the channel closes).

bufferedAmountLowThreshold of type unsigned long

The bufferedAmountLowThreshold attribute sets the threshold at which the bufferedAmount is considered to be low. When the bufferedAmount decreases from above this threshold to equal or below it, the bufferedamountlow event fires. The bufferedAmountLowThreshold is initially zero on each new RTCDataChannel, but the application may change its value at any time.

binaryType of type DOMString

The binaryType attribute MUST, on getting, return the value to which it was last set. On setting, the user agent MUST set the IDL attribute to the new value. When an RTCDataChannel object is constructed, the binaryType attribute MUST be initialized to the string 'blob'. This attribute controls how binary data is exposed to scripts. See the [[WEBSOCKETS-API]] for more information.

onopen of type EventHandler

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

onbufferedamountlow of type EventHandler

The event type of this event handler is bufferedamountlow.

onerror of type EventHandler

This event handler, of event handler type error, MUST be supported by all objects implementing the RTCDataChannel interface. One reason an error event can be fired is if the value of parameters passed in the constructor is subsequently determined to be invalid. This can happen if parameters.negotiated is set to false and then a call to RTCDtlsTransport.start() causes the DTLS role to be set to a value inconsistent with the value of parameters.id, as noted in [[!DATA-PROT]] Section 4.

onclose of type EventHandler

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

onmessage of type EventHandler

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

Event Argument Description
Object data The received remote data.

Methods

getParameters

Returns the parameters applying to this data channel.

No parameters.
close

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

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

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

3. Set channel's readyState attribute to closing.

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

No parameters.
Return type: void
send

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

Parameter Type Nullable Optional Description
data USVString
Return type: void
send

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

Parameter Type Nullable Optional Description
data Blob
Return type: void
send

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

Parameter Type Nullable Optional Description
data ArrayBuffer
Return type: void
send

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

Parameter Type Nullable Optional Description
data ArrayBufferView
Return type: void

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

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

  2. If channel's readyState attribute is not open, throw an InvalidStateError.

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

    • string object:

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

    • Blob object:

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

    • ArrayBuffer object:

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

    • ArrayBufferView object:

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

  4. If the size of data exceeds the value of maxMessageSize on channel's associated RTCSctpTransport, throw a TypeError.

  5. Queue data for transmission on channel's underlying data transport. If queuing data is not possible because not enough buffer space is available, throw an OperationError.

    The actual transmission of data occurs in parallel. If sending data leads to an SCTP-level error, the application will be notified asynchronously through onerror.

RTCDataTransport Interface

interface RTCDataTransport : RTCStatsProvider {
};

RTCDataChannelState Enum

The RTCDataChannelState provides information on the state of the data channel.

enum RTCDataChannelState {
    "connecting",
    "open",
    "closing",
    "closed"
};
Enumeration description
connecting

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

open

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

closing

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

closed

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

RTCDataChannelParameters Dictionary

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

dictionary RTCDataChannelParameters {
             USVString      label = "";
             boolean        ordered = true;
             unsigned long  maxPacketLifetime;
             unsigned long  maxRetransmits;
             USVString      protocol = "";
             boolean        negotiated = false;
             unsigned short id;
};

Dictionary RTCDataChannelParameters Members

label of type USVString, defaulting to ""

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

ordered of type boolean, defaulting to true

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

maxPacketLifetime of type unsigned long

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

maxRetransmits of type unsigned long

The maxRetransmits attribute returns the maximum number of retransmissions that are attempted in unreliable mode. The attribute MUST be initialized to null by default and MUST return the value to which it was set when the RTCDataChannel was constructed.

protocol of type USVString, defaulting to ""

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

negotiated of type boolean, defaulting to false

The negotiated attribute returns true if this RTCDataChannel was negotiated by the application, or false otherwise. The attribute MUST be initialized to false by default and MUST return the value to which it was set when the RTCDataChannel was constructed. If set to true, the application developer MUST signal to the remote peer to construct an RTCDataChannel object with the same id for the data channel to be open. As noted in [[!DATA-PROT]], DATA_CHANNEL_OPEN is not sent to the remote peer nor is DATA_CHANNEL_ACK expected in return. If set to false, the remote party will receive an ondatachannel event with a system constructed RTCDataChannel object.

id of type unsigned short

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

RTCSctpTransport Interface

The RTCSctpTransport includes information relating to Stream Control Transmission Protocol (SCTP) transport.

Overview

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

Operation

An RTCSctpTransport is constructed from an RTCDtlsTransport object, and optionally a port number (with a default of 5000, or the next unused port). If a port already in use is provided in the constructor, throw an InvalidParameters. An RTCSctpTransport object can be garbage-collected once stop() is called and it is no longer referenced.

Interface Definition

        [ Constructor (RTCDtlsTransport transport, optional unsigned short port), Exposed=Window]
interface RTCSctpTransport : RTCDataTransport {
    readonly        attribute RTCDtlsTransport      transport;
    readonly        attribute RTCSctpTransportState state;
    readonly        attribute unsigned short        port;
    static RTCSctpCapabilities getCapabilities ();
    void                       start (RTCSctpCapabilities remoteCaps, optional unsigned short remotePort);
    void                       stop ();
                    attribute EventHandler          ondatachannel;
                    attribute EventHandler          onstatechange;
};

Constructors

RTCSctpTransport
Parameter Type Nullable Optional Description
transport RTCDtlsTransport
port unsigned short

Attributes

transport of type RTCDtlsTransport, readonly

The RTCDtlsTransport instance the RTCSctpTransport object is sending over.

state of type RTCSctpTransportState, readonly

The current state of the SCTP transport.

port of type unsigned short, readonly

The local SCTP port number used by the data channel.

ondatachannel of type EventHandler

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

onstatechange of type EventHandler

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

Methods

getCapabilities, static

getCapabilities() retrieves the RTCSctpCapabilities of the RTCSctpTransport.

No parameters.
Return type: RTCSctpCapabilities
start

Starts the RTCSctpTransport instance and causes an SCTP INIT request to be issued over the RTCDtlsTransport from the local RTCSctpTransport to the remote RTCSctpTransport (causing the RTCSctpTransportState to transition to to connecting), where the remote RTCSctpTransport responds with an SCTP INIT-ACK. Since both local and remote parties must mutually create an RTCSctpTransport, SCTP SO (Simultaneous Open) is used to establish a connection over SCTP. If RTCSctpTransportState is not new throw an InvalidStateError. If remotePort is not provided, a default value of port is assumed. If the remote port is in use, throw an InvalidParameters.

Parameter Type Nullable Optional Description
remoteCaps RTCSctpCapabilities
remotePort unsigned short
Return type: void
stop

Stops the RTCSctpTransport instance.

No parameters.
Return type: void

RTCSctpTransportState Enum

RTCSctpTransportState indicates the state of the SCTP transport.

enum RTCSctpTransportState {
    "new",
    "connecting",
    "connected",
    "closed"
};
Enumeration description
new

The RTCSctpTransport object has been constructed but the start method has not been called so the RTCSctpTransport has not started negotiating yet.

connecting

The start method has been called and the RTCSctpTransport is in the process of negotiating an association.

connected

The RTCSctpTransport has completed negotiation of an association.

closed

The SCTP association has been closed intentionally via a call to stop or receipt of a SHUTDOWN or ABORT chunk.

RTCSctpCapabilities Dictionary

The RTCSctpCapabilities dictionary provides information about the capabilities of the RTCSctpTransport.

dictionary RTCSctpCapabilities {
             unsigned long maxMessageSize;
};

Dictionary RTCSctpCapabilities Members

maxMessageSize of type unsigned long

The maximum size of data that can be passed to RTCDataChannel's send() method.

RTCDataChannelEvent

The datachannel event uses the RTCDataChannelEvent interface.

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

        [ Constructor (DOMString type, RTCDataChannelEventInit eventInitDict), Exposed=Window]
interface RTCDataChannelEvent : Event {
    readonly        attribute RTCDataChannel channel;
};

Constructors

RTCDataChannelEvent
Parameter Type Nullable Optional Description
type DOMString
eventInitDict RTCDataChannelEventInit

Attributes

channel of type RTCDataChannel, readonly

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

The RTCDataChannelEventInit dictionary includes information on the configuration of the data channel.

dictionary RTCDataChannelEventInit : EventInit {
             RTCDataChannel channel;
};

Dictionary RTCDataChannelEventInit Members

channel of type RTCDataChannel

The RTCDataChannel object associated with the event.

Example

// Include some helper functions
import {trace, errorHandler, mySendLocalCandidate, myIceGathererStateChange,
  myIceTransportStateChange, myDtlsTransportStateChange} from 'helper';

function initiate(mySignaller) {
  // Prepare the ICE gatherer
  var gatherOptions = {
    gatherPolicy: "all",
    iceServers: [
      { urls: "stun:stun1.example.net" },
      { urls: "turn:turn.example.org", username: "user", credential: "myPassword",
        credentialType: "password" }
     ]
  };
  var iceGatherer = new RTCIceGatherer(gatherOptions);
  // Handle state changes
  iceGatherer.onstatechange = function(event) {
    myIceGathererStateChange("iceGatherer", event.state);
  };
  // Handle errors
  iceGatherer.onerror = errorHandler;
  // Prepare to signal local candidates
  iceGatherer.onlocalcandidate = function(event) {
    mySignaller.mySendLocalCandidate(event.candidate);
  };

  // Start gathering
  iceGatherer.gather();
  // Create ICE transport
  var ice = new RTCIceTransport(iceGatherer);
  // Prepare to handle remote ICE candidates
  mySignaller.onRemoteCandidate = function(remote) {
    ice.addRemoteCandidate(remote.candidate);
  };

  // Create the DTLS certificate
  var certs;
  var keygenAlgorithm = { name: "ECDSA", namedCurve: "P-256" };
  RTCCertificate.generateCertificate(keygenAlgorithm).then(function(certificate){
    certs[0] = certificate;
  }, function(){
    trace('Certificate could not be created');
  });

  // Create DTLS and SCTP transport
  var dtls = new RTCDtlsTransport(ice, certs);
  var sctp = new RTCSctpTransport(dtls);

  // Construct RTCDataChannelParameters dictionary
  var parameters = {
    label: "channel1",
    ordered: true,
    protocol: "ship",
    negotiated: false
  };

  mySignaller.sendInitiate({
    ice: iceGatherer.getLocalParameters(),
    dtls: dtls.getLocalParameters(),
    sctpCapabilities: RTCSctpTransport.getCapabilities(),
    port: sctp.port,
    // ... marshall RtpSender/RtpReceiver capabilities as illustrated in Section 6.5 Example 9.
  }, function(remote) {
    // Start the ICE, DTLS and SCTP transports
    ice.start(iceGatherer, remote.ice, RTCIceRole.controlling);
    dtls.start(remote.dtls);
    sctp.start(remote.sctpCapabilities, remote.port);
    // Create the data channel object
    var channel = new RTCDataChannel(sctp, parameters);
    channel.send("foo");
    // ... configure RtpSender/RtpReceiver objects as illustrated in Section 6.5 Example 9.
  });
}
// This is an example of how to answer
// Include some helper functions
import {trace, errorHandler, mySendLocalCandidate, myIceGathererStateChange,
  myIceTransportStateChange, myDtlsTransportStateChange} from 'helper';

function accept(mySignaller, remote) {
  var gatherOptions = {
    gatherPolicy: "all",
    iceServers: [
      { urls: "stun:stun1.example.net" },
      { urls: "turn:turn.example.org", username: "user", credential: "myPassword",
        credentialType: "password" }
     ]
  };
  var iceGatherer = new RTCIceGatherer(gatherOptions);
  // Handle state changes
  iceGatherer.onstatechange = function(event) {
    myIceGathererStateChange("iceGatherer", event.state);
  };
  // Handle errors
  iceGatherer.onerror = errorHandler;
  // Prepare to signal local candidates
  iceGatherer.onlocalcandidate = function(event) {
    mySignaller.mySendLocalCandidate(event.candidate);
  };

   // Start gathering
  iceGatherer.gather();
  // Create ICE transport
  var ice = new RTCIceTransport(iceGatherer);
  // Prepare to handle remote ICE candidates
  mySignaller.onRemoteCandidate = function(remote) {
    ice.addRemoteCandidate(remote.candidate);
  };

   // Create the DTLS certificate
  var certs;
  var keygenAlgorithm = { name: "ECDSA", namedCurve: "P-256" };
  RTCCertificate.generateCertificate(keygenAlgorithm).then(function(certificate){
    certs[0] = certificate;
  }, function(){
    trace('Certificate could not be created');
  });

  // Create DTLS and SCTP transport
  var dtls = new RTCDtlsTransport(ice, certs);
  var sctp = new RTCSctpTransport(dtls);

  mySignaller.sendAccept({
    ice: iceGatherer.getLocalParameters(),
    dtls: dtls.getLocalParameters(),
    sctpCapabilities: RTCSctpTransport.getCapabilities(),
    port: sctp.port,
    // ... marshall RtpSender/RtpReceiver capabilities as illustrated in Section 6.5 Example 9.
  });

   // Start the ICE, DTLS and SCTP transports
  ice.start(iceGatherer, remote.ice, RTCIceRole.controlled);
  dtls.start(remote.dtls);
  // Start the SctpTransport
  sctp.start(remote.sctpCapabilities, remote.port);

  // ... configure RtpSender/RtpReceiver objects as illustrated in Section 6.5 Example 9.

  // Assume in-band signalling. We could also have sent
  // RTCDataChannelParameters in signalling and constructed
  // the data channel with negotiated: true.

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

RTCQuicTransport Interface

The RTCQuicTransport includes information relating to QUIC transport.

Overview

An RTCQuicTransport instance is associated to one or more RTCQuicStream instances.

Operation

The QUIC protocol is described in [[!QUIC-TRANSPORT]]. A RTCQuicTransport instance is constructed using an RTCIceTransport and a sequence of RTCCertificate objects. An RTCQuicTransport object in the closed or failed states can be garbage-collected when it is no longer referenced.

If an attempt is made to construct a RTCQuicTransport instance from an RTCIceTransport in the closed state, throw an InvalidStateError. If certificates is non-empty, check that the expires attribute of each RTCCertificate object is in the future. If a certificate has expired, throw an InvalidParameter; otherwise, store the certificates.

A newly constructed RTCQuicTransport MUST listen and respond to incoming QUIC 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(). To verify the remote fingerprint, compute the fingerprint value for the selected remote certificate using the signature digest algorithm, and compare it against remoteParameters.fingerprints. If the selected remote certificate RTCDtlsFingerprint.value matches remoteParameters.fingerprints[j].value and RTCDtlsFingerprint.algorithm matches remoteParameters.fingerprints[j].algorithm for any value of j, the remote fingerprint is verified. After the QUIC 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).

Interface Definition

        [ Constructor (RTCceTransport transport, sequence<RTCCertificate> certificates), Exposed=Window]
interface RTCQuicTransport : RTCStatsProvider {
    readonly        attribute RTCIceTransport          transport;
    readonly        attribute RTCQuicTransportState    state;
    RTCQuicParameters     getLocalParameters ();
    RTCQuicParameters?    getRemoteParameters ();
    sequence<RTCCertificate> getCertificates ();
    sequence<ArrayBuffer> getRemoteCertificates ();
    void                  start (RTCQuicParameters remoteParameters);
    void                  stop ();
    RTCQuicStream         createStream ();
                    attribute EventHandler             onstatechange;
                    attribute EventHandler             onerror;
                    attribute EventHandler             onstream;
};

Constructors

RTCQuicTransport
Parameter Type Nullable Optional Description
transport RTCIceTransport
certificates sequence<RTCCertificate>

Attributes

transport of type RTCIceTransport, readonly

The associated RTCIceTransport instance.

state of type RTCQuicTransportState, readonly

The current state of the QUIC transport.

onstatechange of type EventHandler

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

onerror of type EventHandler

This event handler, of event handler event type error, MUST be fired on reception of a QUIC error; an implementation SHOULD include QUIC error information in error.message (defined in [[!HTML5]] Section 6.1.3.6.2).

onstream of type EventHandler

This event handler, of event handler event type quicstream, MUST be fired on when a remote RTCQuicStream is created.

Methods

getLocalParameters

getLocalParameters() obtains the QUIC parameters of the local RTCQuicTransport upon construction. If multiple certificates were provided in the constructor, then multiple fingerprints will be returned, one for each certificate. getLocalParameters().role always returns the default role of a newly constructed RTCQuicTransport; for a browser this will be auto.

No parameters.
Return type: RTCQuicParameters
getRemoteParameters

getRemoteParameters() obtains the remote QUIC parameters passed in the start() method. Prior to calling start(), null is returned.

No parameters.
Return type: RTCQuicParameters, nullable
getCertificates

getCertificates() returns the certificates provided in the constructor.

No parameters.
Return type: sequence<RTCCertificate>
getRemoteCertificates

getRemoteCertificates() returns the certificate chain in use by the remote side, with each certificate encoded in binary Distinguished Encoding Rules (DER) [[!X690]]. getRemoteCertificates() returns an empty list prior to selection of the remote certificate, which is completed once RTCQuicTransportState transitions to connected.

No parameters.
Return type: sequence<ArrayBuffer>
start

Start QUIC transport negotiation with the parameters of the remote QUIC transport, including verification of the remote fingerprint. Only a single QUIC transport can be multiplexed over an ICE transport. Therefore if a RTCQuicTransport object quicTransportB is constructed with an RTCIceTransport object iceTransport previously used to construct another RTCQuicTransport object quicTransportA, then if quicTransportB.start() is called prior to having called quicTransportA.stop(), then throw an InvalidStateError.

If start is called after a previous start call, or if state is closed, throw an InvalidStateError.

If all of the values of remoteParameters.fingerprints[j].algorithm are unsupported, where j goes from 0 to the number of fingerprints, throw a NotSupportedError.

Parameter Type Nullable Optional Description
remoteParameters RTCQuicParameters
Return type: void
stop

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

No parameters.
Return type: void
createStream

Creates an RTCQuicStream object. Since [[QUIC-TRANSPORT]] only defines reliable QUIC streams, createStream only supports creation of reliable streams.

When createStream is called, the user agent MUST run the following steps:

  1. Let transport be the RTCQuicTransport on which createStream is invoked.
  2. If transport.state is closed throw an InvalidStateError.
  3. Let parameters be the first argument.
  4. Let stream be a newly created RTCQuicStream object.

  5. Let stream have a [[\QuicStreamState]] internal slot initialized to idle.

  6. Return stream and continue the following steps in the background.

  7. Create stream's associated underlying data transport.

No parameters.
Return type: RTCQuicStream

RTCQuicParameters Dictionary

The RTCQuicParameters dictionary includes information relating to QUIC configuration.

dictionary RTCQuicParameters {
             RTCQuicRole                  role = "auto";
             sequence<RTCDtlsFingerprint> fingerprints;
};

Dictionary RTCQuicParameters Members

role of type RTCQuicRole, defaulting to "auto"

The QUIC role, with a default of auto.

fingerprints of type sequence<RTCDtlsFingerprint>

Sequence of fingerprints, one fingerprint for each certificate.

RTCQuicStreamEvent

The quicstream event uses the RTCQuicStreamEvent interface.

Firing a quicstream event named e with a RTCQuicStream stream 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 RTCQuicStreamEvent interface with the stream attribute set to stream, MUST be created and dispatched at the given target.

        [ Constructor (DOMString type, RTCQuicStreamEventInit eventInitDict), Exposed=Window]
interface RTCQuicStreamEvent : Event {
    readonly        attribute RTCQuicStream stream;
};

Constructors

RTCQuicStreamEvent
Parameter Type Nullable Optional Description
type DOMString
eventInitDict RTCQuicStreamEventInit

Attributes

stream of type RTCQuicStream, readonly

The stream attribute represents the RTCQuicStream object associated with the event.

The RTCQuicStreamEventInit dictionary includes information on the configuration of the QUIC stream.

dictionary RTCQuicStreamEventInit : EventInit {
             RTCQuicStream stream;
};

Dictionary RTCQuicStreamEventInit Members

stream of type RTCQuicStream

The RTCQuicStream object associated with the event.

RTCQuicRole Enum

RTCQuicRole indicates the role of the QUIC transport.

enum RTCQuicRole {
    "auto",
    "client",
    "server"
};
Enumeration description
auto

The QUIC role is determined based on the resolved ICE role: the ICE controlled role acts as the QUIC client and the ICE controlling role acts as the QUIC server.

client

The QUIC client role.

server

The QUIC server role.

QUIC role determination

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

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

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

RTCQuicTransportState Enum

RTCQuicTransportState indicates the state of the QUIC transport.

enum RTCQuicTransportState {
    "new",
    "connecting",
    "connected",
    "closed",
    "failed"
};
Enumeration description
new

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

connecting

QUIC is in the process of negotiating a secure connection and verifying the remote fingerprint. Once a secure connection is negotiated (but prior to verification of the remote fingerprint, enabled by calling start()), incoming data can flow through.

connected

QUIC has completed negotiation of a secure connection and verified the remote fingerprint. Outgoing data and media can now flow through.

closed

The QUIC connection has been closed intentionally via a call to stop() or receipt of a close_notify alert. Calling transport.stop() will also result in a transition to the closed state.

failed

The QUIC connection has been closed as the result of an error (such as receipt of an error alert or a failure to validate the remote fingerprint).

Example

// Include some helper functions
import {trace, errorHandler, mySendLocalCandidate, myIceGathererStateChange,
  myIceTransportStateChange, myDtlsTransportStateChange} from 'helper';

function initiate(mySignaller) {
  // Prepare the ICE gatherer
  var gatherOptions = {
    gatherPolicy: "all",
    iceServers: [
      { urls: "stun:stun1.example.net" },
      { urls: "turn:turn.example.org", username: "user", credential: "myPassword",
        credentialType: "password" }
     ]
  };
  var iceGatherer = new RTCIceGatherer(gatherOptions);
  // Handle state changes
  iceGatherer.onstatechange = function(event) {
    myIceGathererStateChange("iceGatherer", event.state);
  };
  // Handle errors
  iceGatherer.onerror = errorHandler;
  // Prepare to signal local candidates
  iceGatherer.onlocalcandidate = function(event) {
    mySignaller.mySendLocalCandidate(event.candidate);
  };

  // Start gathering
  iceGatherer.gather();
  // Create ICE transport
  var ice = new RTCIceTransport(iceGatherer);
  // Prepare to handle remote ICE candidates
  mySignaller.onRemoteCandidate = function(remote) {
    ice.addRemoteCandidate(remote.candidate);
  };

  // Create the DTLS certificate
  var certs;
  var keygenAlgorithm = { name: "ECDSA", namedCurve: "P-256" };
  RTCCertificate.generateCertificate(keygenAlgorithm).then(function(certificate){
    certs[0] = certificate;
  }, function(){
    trace('Certificate could not be created');
  });

  // Create DTLS and QUIC transport
  var dtls = new RTCDtlsTransport(ice, certs);
  var quic = new RTCQuicTransport(ice, certs);

  mySignaller.sendInitiate({
    ice: iceGatherer.getLocalParameters(),
    dtls: dtls.getLocalParameters(),
    quic: quic.getLocalParameters(),
    // ... marshall RtpSender/RtpReceiver capabilities as illustrated in Section 6.5 Example 9.
  }, function(remote) {
    // Start the ICE, DTLS and QUIC transports
    ice.start(iceGatherer, remote.ice, RTCIceRole.controlling);
    dtls.start(remote.dtls);
    quic.start(remote.quic);
    // ... configure RtpSender/RtpReceiver objects as illustrated in Section 6.5 Example 9.
  });
}
// This is an example of how to answer
// Include some helper functions
import {trace, errorHandler, mySendLocalCandidate, myIceGathererStateChange,
  myIceTransportStateChange, myDtlsTransportStateChange} from 'helper';

function accept(mySignaller, remote) {
  var gatherOptions = {
    gatherPolicy: "all",
    iceServers: [
      { urls: "stun:stun1.example.net" },
      { urls: "turn:turn.example.org", username: "user", credential: "myPassword",
        credentialType: "password" }
     ]
  };
  var iceGatherer = new RTCIceGatherer(gatherOptions);
  // Handle state changes
  iceGatherer.onstatechange = function(event) {
    myIceGathererStateChange("iceGatherer", event.state);
  };
  // Handle errors
  iceGatherer.onerror = errorHandler;
  // Prepare to signal local candidates
  iceGatherer.onlocalcandidate = function(event) {
    mySignaller.mySendLocalCandidate(event.candidate);
  };

   // Start gathering
  iceGatherer.gather();
  // Create ICE transport
  var ice = new RTCIceTransport(iceGatherer);
  // Prepare to handle remote ICE candidates
  mySignaller.onRemoteCandidate = function(remote) {
    ice.addRemoteCandidate(remote.candidate);
  };

   // Create the DTLS certificate
  var certs;
  var keygenAlgorithm = { name: "ECDSA", namedCurve: "P-256" };
  RTCCertificate.generateCertificate(keygenAlgorithm).then(function(certificate){
    certs[0] = certificate;
  }, function(){
    trace('Certificate could not be created');
  });

  // Create DTLS and SCTP transport
  var dtls = new RTCDtlsTransport(ice, certs);
  var quic = new RTCQuicTransport(ice, certs);

  mySignaller.sendAccept({
    ice: iceGatherer.getLocalParameters(),
    dtls: dtls.getLocalParameters(),
    quic: quic.getLocalParameters(),
    // ... marshall RtpSender/RtpReceiver capabilities as illustrated in Section 6.5 Example 9.
  });

   // Start the ICE, DTLS and SCTP transports
  ice.start(iceGatherer, remote.ice, RTCIceRole.controlled);
  dtls.start(remote.dtls);
  // Start the QuicTransport
  quic.start(remote.quic);

  // ... configure RtpSender/RtpReceiver objects as illustrated in Section 6.5 Example 9.

}
                

RTCQuicStream Interface

The RTCQuicStream includes information relating to a QUIC stream.

Overview

An RTCQuicStream instance is associated to an RTCQuicTransport instance.

Operation

An RTCQuicStream instance is constructed using the RTCQuicTransport.createStream method.

Statistics API

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

The RTCStatsProvider interface enables the retrieval of statistics.

interface RTCStatsProvider {
    Promise<RTCStatsReport> getStats ();
};

Methods

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.

No parameters.
Return type: Promise<RTCStatsReport>

RTCStatsReport Interface

The getStats() method delivers a successful result in the form of a RTCStatsReport object. An RTCStatsReport 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).

[Exposed=Window]
interface RTCStatsReport {
    readonly maplike<DOMString, object>;
};

This interface has "entries", "forEach", "get", "has", "keys", "values", @@iterator methods and a "size" getter brought by readonly maplike.

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

Methods

RTCStats

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.

Parameter Type Nullable Optional Description
id DOMString
Return type: getter

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 an RTCStats dictionary.

dictionary RTCStats {
             DOMHighResTimeStamp timestamp;
             RTCStatsType        type;
             DOMString           id;
};

Dictionary RTCStats Members

timestamp of type DOMHighResTimeStamp

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

type of type RTCStatsType

The type of this object.

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

id of type DOMString

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 Enum

For ORTC, RTCStatsType is equal to one of the values defined in [[!WEBRTC-STATS]] Section 6.1:

"inbound-rtp"

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

"outbound-rtp"

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

"data-channel"

Statistics relating to each RTCDataChannel id. It is accessed via the RTCDataChannelStats defined in [[!WEBRTC-STATS]] Section 7.8.

"track"

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

"transport"

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

"candidate-pair"

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

"local-candidate"

ICE local candidate statistics, related to RTCIceGatherer objects. It is accessed via the RTCIceCandidateStats for the local candidate, defined in [[!WEBRTC-STATS]] Section 7.10.

"remote-candidate"

ICE remote candidate statistics, related to RTCIceTransport objects. It is accessed via the RTCIceCandidateStats for the remote candidate, defined in [[!WEBRTC-STATS]] Section 7.10.

"certificate"

Information about a certificate used by an RTCDtlsTransport object. It is accessed via the RTCCertificateStats defined in [[!WEBRTC-STATS]] Sections 7.12.

Mandatory To Implement Stats

The stats listed in [[!WEBRTC-STATS]] are intended to cover a wide range of use cases. Not all of them have to be implemented by every ORTC implementation.

An implementation MUST support generating statistics of the following types when the corresponding objects exist, with the attributes that are listed when they are valid for that object:

An implementation MAY support generating any other statistic defined in [[!WEBRTC-STATS]], and MAY generate statistics that are not documented.

RTCP matching rules

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

RTCP packets arriving on a RTCDtlsTransport are decrypted and the algorithm described in [[!BUNDLE]] Section 10.2 is used to route the RTCP packets to the appropriate RTCRtpSender and RTCRtpReceiver objects. The 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 so that 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.

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

Identity

The Identity API is marked as a feature at risk, since there is no clear commitment from ORTC implementers.

Overview

An RTCIdentity instance enables authentication of an RTCDtlsTransport using a web-based Identity Provider (IdP). The initiator acts as the Authenticating Party (AP) and obtains an identity assertion from the IdP which is then conveyed in signaling. The responder acts as the Relying Party (RP) and verifies the assertion.

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

Operation

An RTCIdentity instance is constructed from an RTCDtlsTransport object.

Identity Provider Selection

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

getIdentityAssertion sets the identity provider to be used for a given RTCIdentity object, and initiates the process of obtaining an identity assertion. For purposes of generating assertions, the IdP shall be chosen as follows:

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

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

Instantiating an IdP Proxy

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

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

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

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

Requesting Identity Assertions

The identity assertion request process involves the following steps:

  1. The RTCIdentity instantiates an IdP proxy as described in Identity Provider Selection section and waits for the IdP to signal that it is ready.
  2. The IdP sends a "SIGN" message to the IdP proxy. This message includes the material the RTCIdentity object desires to be bound to the user's identity.
  3. If the user has been authenticated by the IdP, and the IdP is willing to generate an identity assertion, the IdP generates an identity assertion. This step depends entirely on the IdP. The methods by which an IdP authenticates users or generates assertions is not specified, though this could involve interacting with the IdP server or other servers.
  4. The IdP proxy sends a response containing the identity assertion to the RTCIdentity object over the message channel.
  5. The RTCIdentity object MAY store the identity assertion.

The format and contents of the messages that are exchanged are described in detail in [[!RTCWEB-SECURITY-ARCH]].

The IdP proxy can return an "ERROR" response. If an error is encountered, the getIdentityAssertion Promise MUST be rejected.

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

User Login Procedure

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

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

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

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

Verifying Identity Assertions

Identity assertion validation happens when setIdentityAssertion is invoked. The process runs asynchronously.

The identity assertion validation process involves the following steps:

  1. The RTCIdentity instantiates an IdP proxy as described in Identity Provider Selection section and waits for the IdP to signal that it is ready.
  2. The IdP sends a "VERIFY" message to the IdP proxy. This message includes the assertion which is to be verified.
  3. The IdP proxy verifies the identity assertion (depending on the authentication protocol this could involve interacting with the IDP server).
  4. Once the assertion is verified, the IdP proxy sends a response containing the verified assertion results to the RTCIdentity object over the message channel.
  5. The RTCIdentity object validates that the fingerprint provided by the IdP in the validation response matches the certificate fingerprint that is, or will be, used for communications. This is done by waiting for the DTLS connection to be established and checking that the certificate fingerprint on the connection matches the one provided by the IdP.
  6. The RTCIdentity validates that the domain portion of the identity matches the domain of the IdP as described in [[!RTCWEB-SECURITY-ARCH]].
  7. The RTCIdentity stores the assertion in the peerIdentity, and returns an RTCIdentityAssertion object when the Promise from setIdentityAssertion is fulfilled. The assertion information to be displayed MUST contain the domain name of the IdP as provided in the assertion.
  8. The browser MAY display identity information to a user in browser UI. Any user identity information that is displayed in this fashion MUST use a mechanism that cannot be spoofed by content.

The IdP might fail to validate the identity assertion by providing an "ERROR" response to the validation request. Validation can also fail due to the additional checks performed by the browser. In both cases, the process terminates and no identity information is exposed to the application or the user.

The browser MUST cause the Promise of setIdentityAssertion to be rejected if validation of an identity assertion fails for any reason.

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

The format and contents of the messages that are exchanged are described in detail in [[!RTCWEB-SECURITY-ARCH]].

As defined in [[!WEBRTC10]] Section 10.4, the peerIdentity parameter to getUserMedia() enables media to be sent to a specifically identified peer, without the contents of mediastreams being accessible to applications. If a MediaStreamTrack with a peerIdentity constraint applied is attached to an RTCRtpSender, media is not sent unless the attached RTCDtlsTransport has validated the same peerIdentity as the MediaStreamTrack 's constraint.

RTCIdentity Interface

The Identity API is described below.

[ Constructor (RTCDtlsTransport transport)]
interface RTCIdentity {
    readonly        attribute RTCIdentityAssertion? peerIdentity;
    readonly        attribute RTCDtlsTransport      transport;
    Promise<DOMString> getIdentityAssertion (DOMString provider, optional DOMString protocol = "default", optional DOMString username);
    Promise<RTCIdentityAssertion> setIdentityAssertion (DOMString assertion);
};

Constructors

RTCIdentity
Parameter Type Nullable Optional Description
transport RTCDtlsTransport

Attributes

peerIdentity of type RTCIdentityAssertion, readonly , nullable

peerIdentity contains the peer identity assertion information if an identity assertion was provided and verified. Once this value is set to a non-null value, it cannot change.

transport of type RTCDtlsTransport, readonly

The RTCDtlsTransport to be authenticated.

Methods

getIdentityAssertion

getIdentityAssertion sets the identity provider to be used for a given RTCIdentity object, and initiates the process of obtaining an identity assertion.

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

  1. If transport.state is closed, throw an InvalidStateError and abort these steps.

  2. Set the current identity provider values to the triplet (provider, protocol, username).

  3. If any identity provider value has changed, discard any stored identity assertion.

  4. Request an identity assertion from the IdP.

  5. If the IdP proxy provides an assertion over the message channel, the Promise is fulfilled, and the assertion is returned (equivalent to onidentityresult in the WebRTC 1.0 API). If the IdP proxy returns an "ERROR" response, the Promise is rejected, and an RTCIdentityError object is returned, (equivalent to onidpassertionerror in the WebRTC 1.0 API).

Parameter Type Nullable Optional Description
provider DOMString
protocol DOMString = "default"
username DOMString
Return type: Promise<DOMString>
setIdentityAssertion

setIdentityAssertion validates the identity assertion. If the Promise is fulfilled, an RTCIdentityAssertion is returned. If the Promise is rejected, an RTCIdentityError object is returned, (equivalent to onidpvalidationerror in the WebRTC 1.0 API).

Parameter Type Nullable Optional Description
assertion DOMString
Return type: Promise<RTCIdentityAssertion>

RTCIdentityError Dictionary

The RTCIdentityError dictionary provides information relating to error responses.

dictionary RTCIdentityError {
             DOMString  idp;
             DOMString? loginUrl;
             DOMString  protocol;
};

Dictionary RTCIdentityError Members

idp of type DOMString

The domain name of the identity provider that is providing the error response.

loginUrl of type DOMString, nullable

An IdP that is unable to generate an identity assertion due to a lack of sufficient user authentication information can provide a URL to a page where the user can complete authentication. If the IdP provides this URL, this attribute includes the value provided by the IdP.

protocol of type DOMString

The IdP protocol that is in use.

RTCIdentityAssertion Dictionary

The RTCIdentityAssertion dictionary provides information about an identity assertion.

dictionary RTCIdentityAssertion {
             DOMString idp;
             DOMString name;
};

Dictionary RTCIdentityAssertion Members

idp of type DOMString

A domain name representing the identity provider.

name of type DOMString

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

Example

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

This example shows how to configure the identity provider and protocol, and consume identity assertions.

        // Set ICE gather options and construct the RTCIceGatherer object, assuming that
// we are using RTP/RTCP mux and A/V mux so that only one RTCIceTransport is needed.
// Include some helper functions
import {trace, errorHandler, mySendLocalCandidate, myIceGathererStateChange,
  myIceTransportStateChange, myDtlsTransportStateChange} from 'helper';
var gatherOptions = {
  gatherPolicy: "all",
  iceServers: [
    { urls: "stun:stun1.example.net" },
    { urls: "turn:turn.example.org", username: "user", credential: "myPassword",
      credentialType: "password" }
   ]
};
var iceGatherer = new RTCIceGatherer(gatherOptions);
iceGatherer.onlocalcandidate = function(event) {
  mySendLocalCandidate(event.candidate);
};
// Start gathering
iceGatherer.gather();
// Construct the ICE transport
var ice = new RTCIceTransport(iceGatherer);
// Create the DTLS certificate
var certs;
var keygenAlgorithm = { name: "ECDSA", namedCurve: "P-256" };
RTCCertificate.generateCertificate(keygenAlgorithm).then(function(certificate){
  certs[0] = certificate;
}, function(){
  trace('Certificate could not be created');
});

// Create the RTCDtlsTransport object.
var dtls = new RTCDtlsTransport(ice, certs);
var identity = new RTCIdentity(dtls);
identity
  .getIdentityAssertion("example.com", "default", "alice@example.com")
  .then(signalAssertion(assertion), function(e) {
    trace("Could not obtain an Identity Assertion. idp: " + e.idp + " Protocol: "
      + e.protocol + " loginUrl: " + e.loginUrl);
  });

function signalAssertion(assertion) {
  mySignalInitiate({
    myAssertion: assertion,
    ice: iceGatherer.getLocalParameters(),
    dtls: dtls.getLocalParameters()
  }, function(response) {
    ice.start(iceGatherer, response.ice, RTCIceRole.controlling);
    // Call dtls.start() before setIdentityAssertion so the peer assertion can be validated.
    dtls.start(response.dtls);
    identity.setIdentityAssertion(response.myAssertion).then(function(peerAssertion) {
      trace("Peer identity assertion validated. idp: " + peerAssertion.idp + " name: "
        + peerAssertion.name);
    }, function(e) {
      trace("Could not validate peer assertion. idp: " + e.idp + " Protocol: " + e.protocol);
    });
  });
}
                    

Certificate Management

Overview

The RTCCertificate interface enables the certificates used by an RTCDtlsTransport to be provided in the constructor. This makes it possible to support forking, where the offerer will create multiple RTCDtlsTransport objects using the same local certificate and fingerprint.

RTCCertificate Interface

The RTCCertificate interface is described below.

[Exposed=Window]
        interface RTCCertificate {
    readonly        attribute DOMTimeStamp       expires;
    readonly        attribute RTCDtlsFingerprint fingerprint;
    AlgorithmIdentifier            getAlgorithm ();
    static Promise<RTCCertificate> generateCertificate (AlgorithmIdentifier keygenAlgorithm);
};

Attributes

expires of type DOMTimeStamp, readonly

The expires attribute indicates the date and time in milliseconds relative to 1970-01-01T00:00:00Z after which the certificate will be considered invalid by the browser. After this time, attempts to construct an RTCDtlsTransport object using this certificate will fail.

Note that this value might not be reflected in a notAfter parameter in the certificate itself.

fingerprint of type RTCDtlsFingerprint, readonly

The fingerprint of the certificate. As noted in [[!JSEP]] Section 5.2.1, the digest algorithm used for the fingerprint matches that used in the certificate signature.

Methods

getAlgorithm

Returns the value of keygenAlgorithm passed in the call to generateCertificate().

getAlgorithm is marked as a feature at risk, since there is no clear commitment from implementers.

No parameters.
Return type: AlgorithmIdentifier
generateCertificate, static

The generateCertificate method causes the user agent to create and store an X.509 certificate [[!X509V3]] and corresponding private key. A handle to information is provided in the form of the RTCCertificate interface. The returned RTCCertificate can be used to control the certificate that is offered in the DTLS session established by RTCDtlsTransport.

The keygenAlgorithm argument is used to control how the private key associated with the certificate is generated. The keygenAlgorithm argument uses the WebCrypto [[!WebCryptoAPI]] AlgorithmIdentifier type. The keygenAlgorithm value MUST be a valid argument to window.crypto.subtle.generateKey; that is, the value MUST produce a non-error result when normalized according to the WebCrypto algorithm normalization process [[!WebCryptoAPI]] with an operation name of generateKey and a [[supportedAlgorithms]] value specific to production of certificates for RTCDtlsTransport. If the algorithm normalization process produces an error, the call to generateCertificate() MUST be rejected with that error.

Signatures produced by the generated key are used to authenticate the DTLS connection. The identified algorithm (as identified by the name of the normalized AlgorithmIdentifier) MUST be an asymmetric algorithm that can be used to produce a signature.

The certificate produced by this process also contains a signature. The validity of this signature is only relevant for compatibility reasons. Only the public key and the resulting certificate fingerprint are used by RTCDtlsTransport, but it is more likely that a certificate will be accepted if the certificate is well formed. The browser selects the algorithm used to sign the certificate; a browser SHOULD select SHA-256 [[!FIPS-180-4]] if a hash algorithm is needed.

The resulting certificate MUST NOT include information that can be linked to a user or user agent. Randomized values for distinguished name and serial number SHOULD be used.

An optional expires attribute MAY be added to the keygenAlgorithm parameter. If this contains a DOMTimeStamp value, it indicates the maximum time that the RTCCertificate is valid for relative to the current time. A user agent sets the expires attribute of the returned RTCCertificate to the current time plus the value of the expires attribute. However, a user agent MAY choose to limit the period over which an RTCCertificate is valid.

A user agent MUST reject a call to generateCertificate() with a DOMError of type "NotSupportedError" if the keygenAlgorithm parameter identifies an algorithm that the user agent cannot or will not use to generate a certificate for RTCDtlsTransport.

The following values MUST be supported by a user agent: { name: "RSASSA-PKCS1-v1_5", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" }, and { name: "ECDSA", namedCurve: "P-256" }.

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

Parameter Type Nullable Optional Description
keygenAlgorithm AlgorithmIdentifier
Return type: Promise<RTCCertificate>

Privacy and Security Considerations

This section is non-normative; it specifies no new behaviour, but instead summarizes information already present in other parts of the specification. The overall security considerations of the APIs and protocols used in ORTC are described in [[RTCWEB-SECURITY-ARCH]].

Impact on same origin policy

The ORTC API enables real-time communication between browsers and other devices, including other browsers.

This means that data and media can be shared between applications running in different browsers, or between an application running in the same browser and something that is not a browser. This is an extension to the Web model which has had barriers against sending data between entities with different origins.

The ORTC specification provides no user prompts or chrome indicators for communication; it assumes that once the Web page has been allowed to access media, it is free to share that media with other entities as it chooses. Peer-to-peer exchanges of data via datachannels can therefore occur without any user explicit consent or involvement. Similarly, a server-mediated exchange (e.g. via Web Sockets) could occur without user involvement.

The peerIdentity mechanism loads and executes JavaScript code from a third-party server acting as an identity provider. That code is executed in a separate JavaScript realm and does not affect the protections afforded by the same origin policy.

Revealing IP addresses

Even without ORTC, the Web server providing a Web application will know the public IP address to which the application is delivered. Setting up communications exposes additional information about the browser’s network context to the web application, and may include the set of (possibly private) IP addresses available to the browser for WebRTC use. Some of this information has to be passed to the corresponding party to enable the establishment of a communication session.

Revealing IP addresses can leak location and means of connection; this can be sensitive. Depending on the network environment, it can also increase the fingerprinting surface and create persistent cross-origin state that cannot easily be cleared by the user.

A connection will always reveal the IP addresses proposed for communication to the corresponding party. The application can limit this exposure by choosing not to use certain addresses using the settings exposed by the RTCIceGatherPolicy dictionary, and by using relays (for instance TURN servers) rather than direct connections between participants. One will normally assume that the IP address of TURN servers is not sensitive information. These choices can for instance be made by the application based on whether the user has indicated consent to start a media connection with the other party.

Mitigating the exposure of IP addresses to the application itself requires limiting the IP addresses that can be used, which will impact the ability to communicate on the most direct path between endpoints. Browsers are encouraged to provide appropriate controls for deciding which IP addresses are made available to applications, based on the security posture desired by the user. The choice of which addresses to expose is controlled by local policy (see [[RTCWEB-IP-HANDLING]] for details).

Impact on local network

Since the browser is an active platform executing in a trusted network environment (inside the firewall), it is important to limit the damage that the browser can do to other elements on the local network, and it is important to protect data from interception, manipulation and modification by untrusted participants.

Mitigations include:

These measures are specified in the relevant IETF documents.

Confidentiality of Communications

The fact that communication is taking place cannot be hidden from adversaries that can observe the network, so this has to be regarded as public information.

A mechanism, peerIdentity, is provided that gives Javascript the option of requesting media that the same javascript cannot access, but can only be sent to certain other entities.

Persistent information

As described above, the list of IP addresses exposed by the ORTC API can be used as a persistent cross-origin state.

Beyond IP addresses, the ORTC API exposes information about the underlying media system via the RTCRtpSender.getCapabilities and RTCRtpReceiver.getCapabilities methods, including detailed and ordered information about the codecs that the system is able to produce and consume. That information is in most cases persistent across time and origins, and increases the fingerprint surface of a given device.

When establishing DTLS connections, the ORTC API can generate certificates that can be persisted by the application (e.g. in IndexedDB). These certificates are not shared across origins, and get cleared when persistent storage is cleared for the origin.

Event summary

The following events fire on RTCDtlsTransport objects:

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

The following events fire on RTCQuicTransport objects:

Event name Interface Fired when...
error ErrorEvent The RTCQuicTransport object has encountered an error.
statechange Event The RTCQuicTransportState changed.
quicstream RTCQuicStreamEvent A new RTCQuicStream is dispatched to the script in response to the remote peer creating a QUIC stream.

The following events fire on RTCIceTransport objects:

Event name Interface Fired when...
statechange Event The RTCIceTransportState changed.
icecandidatepairchange RTCIceCandidatePairChangedEvent The selected RTCIceCandidatePair changed.

The following events fire on RTCIceGatherer objects:

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

The following events fire on RTCRtpSender objects:

Event name Interface Fired when...
ssrcconflict RTCSsrcConflictEvent An SSRC conflict has been detected within the RTP session.

The following events fire on RTCRtpListener objects:

Event name Interface Fired when...
unhandledrtp RTCRtpUnhandledEvent The RTCRtpListener object has received an RTP packet that it cannot deliver to an RTCRtpReceiver object.

The following events fire on RTCDTMFSender and 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).

The following events fire on RTCDataChannel objects:

Event name Interface Fired when...
open Event The RTCDataChannel object's underlying data transport has been established (or re-established).
message MessageEvent [[!webmessaging]] A message was successfully received.
bufferedamountlow Event The RTCDataChannel object's bufferedAmount decreases from above its bufferedAmountLowThreshold to less than or equal to its bufferedAmountLowThreshold.
error ErrorEvent An error has been detected within the RTCDataChannel object. This is not used for programmatic exceptions.
close Event The RTCDataChannel object's underlying data transport has been closed.

The following events fire on RTCSctpTransport objects:

Event name Interface Fired when...
datachannel RTCDataChannelEvent A new RTCDataChannel is dispatched to the script in response to the other peer creating a channel.
statechange Event The RTCSctpTransportState changed.

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 that have been encountered by ORTC API implementers.

replaceTrack/setTrack

WebRTC 1.0 supports the replaceTrack method, whereas ORTC originally supported the setTrack method. In order to provide backward compatibility, this specification has added replaceTrack as an alias for setTrack.

RTCDTMFSender/RTCDtmfSender

WebRTC 1.0 supports the RTCDTMFSender interface, whereas ORTC originally supported the RTCDtmfSender interface. In order to provide backward compatibility, this specification has added support for the RTCDTMFSender interface.

In WebRTC 1.0 the RTCDTMFSender is an extension of RTCRtpSender whereas in ORTC it is created with an RTCRtpSender. The WebRTC 1.0 behaviour can be emulated by providing a getter for RTCRtpSender.dtmf attribute.

BUNDLE

Via the use of [[!BUNDLE]] it is possible for WebRTC 1.0 implementations to multiplex audio and video on the same RTP session. Within ORTC API, equivalent behavior can be obtained by constructing multiple RTCRtpReceiver and RTCRtpSender objects from the same RTCDtlsTransport object. As noted in [[!RTP-USAGE]] Section 4.4, support for audio/video multiplexing is required, as described in [[!RTP-MULTI-STREAM]].

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 for use within RTCRtpParameters, and/or configuring a codec with built-in support for Discontinuous Operation (DTX), such as Opus. As noted in [[!RFC7874]] Section 3, support for CN is required.

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 profile-level-id capability is supported for both the RTCRtpSender and RTCRtpReceiver, and the profile-level-id setting is provided for the RTCRtpSender. Since in ORTC API sender and receiver profile-level-id capabilities are independent and there is no profile-level-id 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.

Identity and non-multiplexed RTP/RTCP

Where RTP and RTCP are not multiplexed, distinct RTCIceTransport, RTCDtlsTransport and RTCIdentity objects can be constructed for RTP and RTCP. While it is possible for getIdentityAssertion() to be called with different values of provider, protocol and username for the RTP and RTCP RTCIdentity objects, application developers desiring backward compatibility with WebRTC 1.0 are strongly discouraged from doing so, since this is likely to result in an error.

Also, where RTP and RTCP are not multiplexed, it is possible that the assertions for both the RTP and RTCP will be validated, but that the identities will not be equivalent. Applications requiring backward compatibility with WebRTC 1.0 are advised to consider this an error. However, if backward compatibility with WebRTC 1.0 is not required the application can consider an alternative, such as ignoring the RTCP identity assertion.

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

The editor wishes to thank Erik Lagerway (Chair of the ORTC CG and Co-chair of the WEBRTC WG) for his support. Substantial text in this specification was provided by many people including Peter Thatcher, Martin Thomson, Iñaki Baz Castillo, Jose Luis Millan, Christoph Dorn, Roman Shpount, Emil Ivov, Shijun Sun and Jason Ausborn. Special thanks to Peter Thatcher for his design contributions relating to many of the objects in the current specification, and to Philipp Hancke, Jxck and Iñaki Baz Castillo for their detailed review.

Change Log

This section will be removed before publication.

Changes since 01 May 2017

  1. Added checks in the send method, as noted in: Issue 564
  2. Added a compliance section, as noted in: Issue 586
  3. Changed type of maxFramerate to double, as noted in: Issue 687
  4. Changed codec parameter names from camelCase to SDP-style names, as noted in: Issue 689
  5. Clarified operation of RTCDtlsTransport.getLocalParameters, as noted in: Issue 690
  6. Reference WebIDL definition of ArrayBuffer, as noted in: Issue 692
  7. Define getCertificates() method and remove certificates attribute, as noted in: Issue 696
  8. Clarify sender settings for "flexfec", as noted in: Issue 698
  9. Added a Privacy and Security section, as noted in: Issue 705
  10. Marked getAlgorithm as a "feature at risk", as noted in: Issue 707
  11. Marked the QoS/Priority API as a "feature at risk", as noted in: Issue 708
  12. Added validation steps in the RTCDataChannel constructor, as noted in: Issue 717
  13. Updated contributing and synchronization sources for compatibility with WebRTC 1.0, as noted in: Issue 718
  14. Updated DTMF support for compatibility with WebRTC 1.0, as noted in: Issue 719
  15. Synchronized with WebRTC 1.0 changes to ICE, as noted in: Issue 720
  16. Clarified key shortening behavior with use of OAuth credentials, as noted in: Issue 721
  17. Enabled setTrack/replaceTrack argument to be null, as noted in: Issue 722
  18. Synchronized with WebRTC 1.0 changes to RTCRtpParameters, as noted in: Issue 723
  19. Added support for DTLS error reporting, as noted in: Issue 724
  20. Fixed race conditions in the DTMF examples, as noted in: Issue 732
  21. Changed numChannels to channels, as noted in: Issue 738
  22. Clarified behavior of getCapabilities, as noted in: Issue 740
  23. Removed the nohost gathering policy, as noted in: Issue 742
  24. Added support for the getDefaultIceServers method, as noted in: Issue 743
  25. Synchronized RTCStatsType values with WebRTC 1.0, as noted in: Issue 745
  26. Added validation steps in the RTCIceGatherer constructor, as noted in: Issue 748
  27. Clarified handling of unsupported fingerprint algorithms, as noted in: Issue 752
  28. Added [Exposed] to interfaces, as noted in: Issue 766
  29. Clarified operation of the RTCRtpSender and RTCRtpReceiver constructor, as noted in: Issue 778

Changes since 02 December 2016

  1. Updated the RTP matching rules (Section 8.3) to address issues Issue 368 and Issue 547.
  2. Clarified handling of H.264 packetizationMode in RTCRtpCodecCapability, as noted in: Issue 567
  3. Provided updated guidance on use of multiple encodings as noted in: Issue 568
  4. Added support for replaceTrack, as noted in: Issue 614
  5. Updated Oauth token auth support, as noted in: Issue 618
  6. Enabled setting of the RTCSctpTransport remote port, as noted in: Issue 625
  7. Changed the maxMessageSize attribute type to unsigned long, as noted in: Issue 626
  8. Clarified handling of RTX in RTCRtpCapabilities.codecs, as noted in: Issue 627
  9. Clarified RTCSctpTransportState definitions, as noted in: Issue 635
  10. Changed RTCIceComponent values to lower case, as noted in: Issue 636
  11. Described the firing of the mute and unmute events, as noted in: Issue 639
  12. Added optional H.264 codec settings, as noted in: Issue 641
  13. Updated Section 13.3 to refer to RTCP packet routing specification, as noted in: Issue 643
  14. Updated Examples 21 and 22 to reflect updated RTCSctpTransport API, as noted in: Issue 648
  15. Provided details on the operation of RTCIceTransport.stop, as noted in: Issue 651
  16. Clarified the purpose of RTCRtpCodecCapabilities.fecMechanisms, as noted in: Issue 655
  17. Allowed an RTCRtpSender to be constructed with a MediaStreamTrack or kind, as noted in: Issue 656
  18. Clarified when multiple RTCRtpCodecCapability entries are provided for the same codec, as noted in: Issue 662
  19. Marked Identity as a "feature at risk", as noted in: Issue 668
  20. Updated Statistics API to track changes to WebRTC Statistics specification, as noted in: Issue 672
  21. Allow construction of an RTCRtpSender without an RTP DtlsTransport, as noted in: Issue 679
  22. Clarify syntax of fingerprint, as noted in: Issue 683

Changes since 20 August 2016

  1. Clarified operation of resolutionScale, as noted in: Issue 362
  2. Clarified meaning of the disconnected state, as noted in: Issue 565
  3. Changed profileLevelId to a DOMString, as noted in: Issue 587
  4. Enabled setTrack() to replace a track that is "ended", as noted in: Issue 589
  5. Clarified operation of setTransport(), as noted in: Issue 591
  6. Clarified behavior of RTCRtpReceiver.stop(), as noted in: Issue 596
  7. Clarified behavior of RTCRtpSender.track.stop(), as noted in: Issue 597
  8. Aligned ORTC with WebRTC 1.0 DTMF API, as noted in: Issue 604
  9. Clarified state transitions of the RTCIceGatherer, as noted in: Issue 606
  10. Clarified behavior of RTCIceTransport.start(), as noted in: Issue 607
  11. Clarified required attributes of an RTCIceCandidate, as noted in: Issue 608
  12. Enable setTrack(null), as noted in: Issue 615
  13. Clarified meaning of sender.track set to null, as noted in: Issue 616

Changes since 04 May 2016

  1. Clarified support for simulcast reception and MRST SVC codecs, as noted in: Issue 175
  2. Clarified handling of media prior to remote fingerprint verification, as noted in: Issue 200
  3. Simplified text relating to event handlers, as noted in: Issue 309
  4. Clarified meaning of RTCRtpCodecCapability.options, as noted in: Issue 412
  5. Clarified exceptions and error conditions in the RTCDtmfSender, as noted in: Issue 446
  6. Provided rtcp.ssrc advice for implementations, as noted in: Issue 462
  7. Clarified effect of RTCRtpReceiver.track.stop(), as noted in: Issue 498
  8. Summarized header extension parameters implementation experience, as noted in: Issue 502
  9. Updated text relating to consent failures, as noted in: Issue 517
  10. Clarified muxId usage, as noted in: Issue 528
  11. Clarified meaning of name, as noted in: Issue 529
  12. Updated ICE transition diagram, as noted in: Issue 535
  13. Clarified "rtx" entries in RTCRtpCodecCapability and RTCRtpCodecParameters, as noted in: Issue 539
  14. Updated text relating to "server could not be reached", as noted in: Issue 542
  15. Corrected codec name usage, as noted in: Issue 544 and Issue 548
  16. Clarified that codecPayloadType can be unset, as noted in: Issue 545
  17. Converted figures to SVG format with figure/caption markup, as noted in: Issue 572

Changes since 01 March 2016

  1. Added the gather() method, as noted in: Issue 165
  2. Removed "public" from RTCIceGatherPolicy, as noted in: Issue 224
  3. Removed the minQuality attribute, as noted in: Issue 351
  4. Made send() and receive() asynchronous, as noted in: Issue 399, Issue 463, Issue 468 and Issue 469
  5. Provided additional information on ICE candidate errors, as noted in: Issue 402
  6. Added state attribute to RTCSctpTransport, as noted in: Issue 403
  7. Provided an example of RTX/RED/FEC configuration, as noted in: Issue 404
  8. Clarified payloadType uniqueness, as noted in: Issue 405
  9. Updated the list of header extensions, as noted in: Issue 409
  10. Added "goog-remb" to the list of feedback mechanisms, as noted in: Issue 410
  11. Added kind argument to the RTCRtpReceiver constructor, as noted in: Issue 411
  12. Clarified send() restrictions on kind, as noted in: Issue 414
  13. Added getAlgorithm() method, as noted in: Issue 427
  14. Changed RTCDataChannel protocol and label to USVString, as noted in: Issue 429
  15. Clarified nullable attributes and methods returning empty lists, as noted in: Issue 433
  16. Clarified support for the "direction" parameter, as noted in: Issue 442
  17. Clarified the apt capability of the "red" codec, as noted in: Issue 444
  18. Clarified usage of RTCRtpEncodingParameters attributes, as noted in: Issue 445
  19. Clarified firing of onssrcconflict event, as noted in: Issue 448
  20. Clarified that CNAME is only set on an RTCRtpSender, as noted in: Issue 450
  21. Updated references, as noted in: Issue 457
  22. Described behavior of send() and receive() with unset RTCRtpEncodingParameters, as noted in: Issue 461
  23. Corrected dictionary initialization in the examples, noted in: Issue 464 and Issue 465
  24. Corrected use of enums in the examples, noted in: Issue 466
  25. Clarified handling of identity constraints, as noted in: Issue 467 and Issue 468
  26. Clarified use of RTCRtpEncodingParameters, as noted in: Issue 470
  27. Changed hostCandidate type, as noted in: Issue 474
  28. Renamed state change event handlers to onstatechange, as noted in: Issue 475
  29. Updated description of RTCIceGatherer closed state, as noted in: Issue 476
  30. Updated description of RTCIceTransport object, as noted in: Issue 477
  31. Updated description of relatedPort, as noted in: Issue 484
  32. Updated description of RTCIceParameters, as noted in: Issue 485
  33. Clarified exceptions in RTCDataChannel construction, as noted in: Issue 492
  34. Provided a reference to error.message, as noted in: Issue 495
  35. Clarified RTCRtpReceiver description, as noted in: Issue 496
  36. Clarified default for clockRate attribute, as noted in: Issue 500
  37. Removed use of "null if unset", as noted in: Issue 503
  38. Updated RTCSctpTransport constructor, as noted in: Issue 504
  39. Clarified behavior of getCapabilities(), as noted in: Issue 509
  40. Addressed issues with RTCDataChannelParameters, as noted in: Issue 519

Changes since 20 November 2015

  1. Clarified unhandledrtp event contents prior to calling receive(), as noted in: Issue 243
  2. Added support for ptime, as noted in: Issue 160
  3. Clarified behavior of send() when encodings is unset, as noted in: Issue 187
  4. Fixed invalid import in examples, as noted in: Issue 250
  5. Added support for Forward Error Correction (FEC), as noted in: Issue 253
  6. Added support for "V" bit in RTCRtpContributingSource, as noted in: Issue 263
  7. Added definition of maxBitrate, as noted in: Issue 267
  8. Clarified definition of audioLevel, as noted in: Issue 377
  9. Use USVString for datachannel.send(), as noted in: PR 387
  10. Clarified requirements for DTMF A-D tone support, as noted in: Issue 391
  11. Changed RTCRtpContributingSource from an interface to a dictionary, as noted in: Issue 289
  12. Added support for maxFramerate encoding parameter, as noted in: Issue 412
  13. Clarified behavior of getRemoteCertificates(), as noted in: Issue 378
  14. Added support for remote peer ICE-lite implementation, as noted in: Issue 293
  15. Clarified RTCDtlsTransportState definition, as noted in: Issue 294
  16. Added explanation for unset iceServers, as noted in: Issue 302
  17. Sync of certificate management API with WebRTC 1.0 changes, as noted in: Issue 303
  18. Added "public" to RTCIceGatherPolicy, as noted in: Issue 305
  19. Fixed problems in Examples 6, 7, 22 and 24, as noted in: Issue 310
  20. Clarified value of the component attribute, as noted in: Issue 314
  21. Clarified behavior with multiple local or remote certificates, as noted in: Issue 317
  22. Added credentialType attribute to Examples, as noted in: Issue 323
  23. Clarified alert handling in RTCDtlsTransportState, as noted in: Issue 327
  24. Added example RTCIceTransportState transitions, as noted in: Issue 332
  25. Clarified object garbage collection, as noted in: Issue 338
  26. Fixed certificate example errors, as noted in: Issue 340
  27. Clarified RTP matching rules, as noted in: Issue 344
  28. Clarified value of rtcpTransport for BUNDLE and RTP/RTCP mux use, as noted in: Issue 349
  29. Fixed markup issues in respec, as noted in: Issue 345
  30. Addressed issues with document anchor links, as noted in: Issue 353
  31. Clarified meaning of active for an RTCRtpReceiver, as noted in: Issue 355
  32. Updated RTCDataChannel event table, as noted in: Issue 358
  33. Clarified behavior of resolutionScale, as noted in: Issue 362
  34. Updated RTP matching rules in Section 8.3 to support FEC/RTX/RED, as noted in: Issue 368
  35. Clarified certificate checking behavior, as noted in: Issue 372
  36. Clarified encodingId syntax, as noted in: Issue 375
  37. Added url to RTCIceGathererEvent, as noted in: Issue 376
  38. Added RangeError for resolutionScale <1.0, as noted in: Issue 379
  39. Added clarification on level asymmetry, as noted in: Issue 382
  40. Clarified DTMF tone requirements, as noted in: Issue 384
  41. Clarified Generic NACK settings, as noted in: Issue 395

Changes since 05 October 2015

  1. Added support for Opus capabilities and settings, as noted in: Issue 252
  2. Added payloadType attribute to RTCRtpRtxParameters, as noted in: Issue 254
  3. Clarified meaning of unset RTCRtpCodecCapability.clockRate, as noted in: Issue 255
  4. Updated VP8 and H.264 capabilities and added VP8 and H.264 settings, as noted in: Issue 258
  5. Added RTX codec parameters, as noted in: Issue 259
  6. Added RED codec parameters, as noted in: Issue 260
  7. Substituted degradationPreference for framerateBias and moved it to RTCRtpParameters, as noted in: Issue 262
  8. Added RID support to the unhandledrtp event, as noted in: Issue 265
  9. Updated references, as noted in: Issue 268
  10. Changed codec parameter and option names to camelCase, as noted in: Issue 273
  11. Added section of codec options, as noted in: Issue 274
  12. Clarified meaning of codec capabilities and options, as noted in: Issue 275 and Issue 277
  13. Clarified behavior in RTCRtpSender constructor and setTrack() when track.readyState is "ended", as noted in: Issue 278

Changes since 22 June 2015

  1. Added support for the WebRTC 1.0 certificate management API, as noted in: Issue 195
  2. Added certificate argument to the RTCDtlsTransport constructor, as noted in: Issue 218
  3. Added the failed state to RTCDtlsTransportState, as noted in: Issue 219
  4. Changed getNominatedCandidatePair to getSelectedCandidatePair, as noted in: Issue 220
  5. Added support for WebRTC 1.0 RTCIceCredentialType, as noted in: Issue 222
  6. Clarified behavior of createAssociatedGatherer(), as noted in: Issue 223
  7. Changed spelling from "iceservers" to "iceServers" for consistency with WebRTC 1.0, as noted in: Issue 225
  8. Added support for SCTP port numbers, as noted in: Issue 227
  9. Changed "outbound-rtp" to "outboundrtp" within the Statistics API, as noted in: Issue 229
  10. Changed maxPacketLifetime and maxRetransmits from unsigned short to unsigned long, as noted in: Issue 231
  11. Clarified DataChannel negotiation, as noted in: Issue 233
  12. Added getContributingSources() method, as noted in: Issue 236
  13. Fixes to Examples 5 and 6, as noted in: Issue 237 and Issue 239
  14. Clarified behavior of RTCDataChannel.send(), as noted in: Issue 240
  15. Fixed typos in Example 11, as noted in: Issue 241 and Issue 248
  16. Added text relating to RTCDataChannel exceptions and errors, as noted in: Issue 242
  17. Reconciliation of RTCRtpEncodingParameters dictionary with WebRTC 1.0, as noted in: Issue 249

Changes since 7 May 2015

  1. Addressed Philipp Hancke's review comments, as noted in: Issue 198
  2. Added the failed state to RTCIceTransportState, as noted in: Issue 199
  3. Added text relating to handling of incoming media packets prior to remote fingerprint verification, as noted in: Issue 200
  4. Added a complete attribute to the RTCIceCandidateComplete dictionary, as noted in: Issue 207
  5. Updated the description of RTCIceGatherer.close() and the closed state, as noted in: Issue 208
  6. Updated Statistics API error handling to reflect proposed changes to the WebRTC 1.0 API, as noted in: Issue 214
  7. Updated Section 10 (RTCDtmfSender) to reflect changes in the WebRTC 1.0 API, as noted in: Issue 215
  8. Clarified state transitions due to consent failure, as noted in: Issue 216
  9. Added a reference to [[FEC]], as noted in: Issue 217

Changes since 25 March 2015

  1. sender.setTrack() updated to return a Promise, as noted in: Issue 148
  2. Added RTCIceGatherer as an optional argument to the RTCIceTransport constructor, as noted in: Issue 174
  3. Clarified handling of contradictory RTP/RTCP multiplexing settings, as noted in: Issue 185
  4. Clarified error handling relating to RTCIceTransport, RTCDtlsTransport and RTCIceGatherer objects in the closed state, as noted in: Issue 186
  5. Added component attribute and createAssociatedGatherer() method to the RTCIceGatherer object, as noted in: Issue 188
  6. Added close() method to the RTCIceGatherer object as noted in: Issue 189
  7. Clarified behavior of TCP candidate types, as noted in: Issue 190
  8. Clarified behavior of iceGatherer.onlocalcandidate, as noted in: Issue 191
  9. Updated terminology in Section 1.1 as noted in: Issue 193
  10. Updated RTCDtlsTransportState definitions, as noted in: Issue 194
  11. Updated RTCIceTransportState definitions, as noted in: Issue 197

Changes since 22 January 2015

  1. Updated Section 8.3 on RTP matching rules, as noted in: Issue 48
  2. Further updates to the Statistics API, reflecting: Issue 85
  3. Added support for maxptime, as noted in: Issue 160
  4. Revised the text relating to RTCDtlsTransport.start(), as noted in: Issue 168
  5. Clarified pre-requisites for insertDTMF(), based on: Issue 178
  6. Added Section 13.4 and updated Section 9.5.1 to clarify aspects of RTCP sending and receiving, based on: Issue 180
  7. Fixed miscellaneous typos, as noted in: Issue 183
  8. Added informative reference to [[RFC3264]] Section 5.1, as noted in: Issue 184

Changes since 14 October 2014

  1. Update to the Statistics API, reflecting: Issue 85
  2. Update on 'automatic' use of scalable video coding, as noted in: Issue 156
  3. Update to the H.264 parameters, as noted in: Issue 158
  4. Update to the 'Big Picture', as noted in: Issue 159
  5. Changed 'RTCIceTransportEvent' to 'RTCIceGathererEvent' as noted in: Issue 161
  6. Update to RTCRtpUnhandledEvent as noted in: Issue 163
  7. Added support for RTCIceGatherer.state as noted in: Issue 164
  8. Revised the text relating to RTCIceTransport.start() as noted in: Issue 166
  9. Added text relating to DTLS interoperability with WebRTC 1.0, as noted in: Issue 167
  10. Added a reference to the ICE consent specification, as noted in: Issue 171

Changes since 20 August 2014

  1. Address questions about RTCDtlsTransport.start(), as noted in: Issue 146
  2. Address questions about RTCRtpCodecCapability.preferredPayloadType, as noted in: Issue 147
  3. Address questions about RTCRtpSender.setTrack() error handling, as noted in: Issue 148
  4. Address 'automatic' use of scalable video coding (in RTCRtpReceiver.receive()) as noted in: Issue 149
  5. Renamed RTCIceListener to RTCIceGatherer as noted in: Issue 150
  6. Added text on multiplexing of STUN, TURN, DTLS and RTP/RTCP, as noted in: Issue 151
  7. Address issue with queueing of candidate events within the RTCIceGatherer, as noted in: Issue 152
  8. Clarify behavior of RTCRtpReceiver.getCapabilities(kind), as noted in: Issue 153

Changes since 16 July 2014

  1. Clarification of the ICE restart issue, as noted in : Issue 93
  2. Clarified onerror usage in sender and receiver objects, as noted in: Issue 95
  3. Clarified SST-MS capability issue noted in: Issue 108
  4. Clarification of send() and receive() usage as noted in: Issue 119
  5. Changed ICE state diagram as noted in: Issue 122
  6. Removed getParameters methods and changed send() method as noted in: Issue 136
  7. Changed definition of framerateScale and resolutionScale as noted in: Issue 137
  8. Substituted muxId for receiverId as noted in: Issue 138 and Issue 140
  9. Clarified the setting of track.kind as described in: Issue 141
  10. Added SSRC conflict event to the RTCRtpSender, as described in: Issue 143
  11. Addressed the "end of candidates" issues noted in: Issue 142 and Issue 144

Changes since 16 June 2014

  1. Added section on WebRTC 1.0 compatibility issues, responding to Issue 66
  2. Added Identity support, as described in Issue 78
  3. Reworked getStats() method, as described in Issue 85
  4. Removed ICE restart method described in Issue 93
  5. Addressed CNAME and synchronization context issues described in Issue 94
  6. Fixed WebIDL issues noted in Issue 97
  7. Addressed NITs described in Issue 99
  8. DTLS transport issues fixed as described in Issue 100
  9. ICE transport issues fixed as described in Issue 101
  10. ICE transport controller fixes made as described in Issue 102
  11. Sender and Receiver object fixes made as described in Issue 103
  12. Fixed RTCRtpEncodingParameters default issues described in Issue 104
  13. Fixed 'Big Picture' issues descibed in Issue 105
  14. Fixed RTCRtpParameters default issues described in Issue 106
  15. Added a multi-stream capability, as noted in Issue 108
  16. Removed quality scalability capabilities and parameters, as described in Issue 109
  17. Added scalability examples as requested in Issue 110
  18. Addressed WebRTC 1.0 Data Channel compatibility issue described in Issue 111
  19. Removed header extensions from RTCRtpCodecParameters as described in Issue 113
  20. Addressed RTP/RTCP non-mux issues with IdP as described in Issue 114
  21. Added getParameter methods to RTCRtpSender and RTCRtpReceiver objects, as described in Issue 116
  22. Added layering diagrams as requested in Issue 117
  23. Added a typedef for payloadtype, as described in Issue 118
  24. Moved onerror from the RTCIceTransport object to the RTCIceListener object as described in Issue 121
  25. Added explanation of Voice Activity Detection (VAD), responding to Issue 129
  26. Clarified the meaning of maxTemporalLayers and maxSpatialLayers, as noted in Issue 130
  27. Added [[!RFC6051]] to the list of header extensions and removed RFC 5450, as noted in Issue 131
  28. Addressed ICE terminology issues, as described in Issue 132
  29. Separated references into Normative and Informative, as noted in Issue 133

Changes since 14 May 2014

  1. Added support for non-multiplexed RTP/RTCP and ICE freezing, as described in Issue 57
  2. Added support for getRemoteCertificates(), as described in Issue 67
  3. Removed filterParameters() and createParameters() methods, as described in Issue 80
  4. Partially addressed capabilities issues, as described in Issue 84
  5. Addressed WebIDL type issues described in Issue 88
  6. Addressed Overview section issues described in Issue 91
  7. Addressed readonly attribute issues described in Issue 92
  8. Added ICE restart method to address the issue described in Issue 93
  9. Added onerror eventhandler to sender and receiver objects as described in Issue 95

Changes since 29 April 2014

  1. ICE restart explanation added, as described in Issue 59
  2. Fixes for error handling, as described in Issue 75
  3. Fixes for miscellaneous NITs, as described in Issue 76
  4. Enable retrieval of the SSRC to be used by RTCP, as described in Issue 77
  5. Support for retrieval of audio and video capabilities, as described in Issue 81
  6. getStats interface updated, as described in Issue 82
  7. Partially addressed SVC issues described in Issue 83
  8. Partially addressed statistics update issues described in Issue 85

Changes since 12 April 2014

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

Changes since 13 February 2014

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

Changes since 07 November 2013

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