4.2 Configuration

4.2.1 RTCConfiguration Dictionary

The RTCConfiguration defines a set of parameters to configure how the peer-to-peer communication established via RTCPeerConnection is established or re-established.

  1. WebIDLdictionary RTCConfiguration {
  2.   sequence<RTCIceServer> iceServers;
  3.   RTCIceTransportPolicy iceTransportPolicy;
  4.   RTCBundlePolicy bundlePolicy;
  5.   RTCRtcpMuxPolicy rtcpMuxPolicy;
  6.   sequence<RTCCertificate> certificates;
  7.   [EnforceRange] octet iceCandidatePoolSize = 0;
  8. };
Dictionary RTCConfiguration Members

iceServers of type sequence<RTCIceServer>

An array of objects describing servers available to be used by ICE, such as STUN and TURN servers.

iceTransportPolicy of type RTCIceTransportPolicy.

Indicates which candidates the ICE Agent is allowed to use.

bundlePolicy of type RTCBundlePolicy.

Indicates which media-bundling policy to use when gathering ICE candidates.

rtcpMuxPolicy of type RTCRtcpMuxPolicy.

Indicates which rtcp-mux policy to use when gathering ICE candidates.

certificates of type sequence<RTCCertificate>

A set of certificates that the RTCPeerConnection uses to authenticate.

Valid values for this parameter are created through calls to the generateCertificate() function.

Although any given DTLS connection will use only one certificate, this attribute allows the caller to provide multiple certificates that support different algorithms. The final certificate will be selected based on the DTLS handshake, which establishes which certificates are allowed. The RTCPeerConnection implementation selects which of the certificates is used for a given connection; how certificates are selected is outside the scope of this specification.

Note

Existing implementations only utilize the first certificate provided; the others are ignored.

If this value is absent, then a default set of certificates is generated for each RTCPeerConnection instance.

This option allows applications to establish key continuity. An RTCCertificate can be persisted in [INDEXEDDB] and reused. Persistence and reuse also avoids the cost of key generation.

The value for this configuration option cannot change after its value is initially selected.

iceCandidatePoolSize of type octet, defaulting to 0

Size of the prefetched ICE pool as defined in [RFC8829] (section 3.5.4. and section 4.1.1.).

4.2.2 RTCIceCredentialType Enum

  1. WebIDLenum RTCIceCredentialType {
  2.   "password"
  3. };
Enumeration description
passwordThe credential is a long-term authentication username and password, as described in [RFC5389], Section 10.2.

4.2.3 RTCIceServer Dictionary

The RTCIceServer dictionary is used to describe the STUN and TURN servers that can be used by the ICE Agent to establish a connection with a peer.

  1. WebIDLdictionary RTCIceServer {
  2.   required (DOMString or sequence<DOMString>) urls;
  3.   DOMString username;
  4.   DOMString credential;
  5.   RTCIceCredentialType credentialType = "password";
  6. };
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, and credentialType is “password“, then this attribute specifies the username to use with that TURN server.

credential of type DOMString

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 represents a long-term authentication password, as described in [RFC5389], Section 10.2.

Note

To support additional values of credentialType, credential may evolve in future as a union.

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:

Example 1

  1. [
  2.   {urls: 'stun:stun1.example.net'},
  3.   {urls: ['turns:turn.example.org', 'turn:turn.example.net'],
  4.     username: 'user',
  5.     credential: 'myPassword',
  6.     credentialType: 'password'},
  7. ];

4.2.4 RTCIceTransportPolicy Enum

As described in [RFC8829] (section 4.1.1.), if the iceTransportPolicy member of the RTCConfiguration is specified, it defines the ICE candidate policy [RFC8829] (section 3.5.3.) the browser uses to surface the permitted candidates to the application; only these candidates will be used for connectivity checks.

  1. WebIDLenum RTCIceTransportPolicy {
  2.   "relay",
  3.   "all"
  4. };
Enumeration description (non-normative)
relay

The ICE Agent uses only media relay candidates such as candidates passing through a TURN server.

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

The ICE Agent can use any type of candidate when this value is specified.

Note
The implementation can still use its own candidate filtering policy in order to limit the IP addresses exposed to the application, as noted in the description of RTCIceCandidate.address.

4.2.5 RTCBundlePolicy Enum

As described in [RFC8829] (section 4.1.1.), bundle policy affects which media tracks are negotiated if the remote endpoint is not bundle-aware, and what ICE candidates are gathered. If the remote endpoint is bundle-aware, all media tracks and data channels are bundled onto the same transport.

  1. WebIDLenum RTCBundlePolicy {
  2.   "balanced",
  3.   "max-compat",
  4.   "max-bundle"
  5. };
Enumeration description (non-normative)
balancedGather ICE candidates for each media type in use (audio, video, and data). If the remote endpoint is not bundle-aware, negotiate only one audio and video track on separate transports.
max-compatGather ICE candidates for each track. If the remote endpoint is not bundle-aware, negotiate all media tracks on separate transports.
max-bundleGather ICE candidates for only one track. If the remote endpoint is not bundle-aware, negotiate only one media track.

4.2.6 RTCRtcpMuxPolicy Enum

As described in [RFC8829] (section 4.1.1.), the RTCRtcpMuxPolicy affects what ICE candidates are gathered to support non-multiplexed RTCP. The only value defined in this spec is “require“.

  1. WebIDL            enum RTCRtcpMuxPolicy {
  2.   "require"
  3. };
Enumeration description (non-normative)
requireGather ICE candidates only for RTP and multiplex RTCP on the RTP candidates. If the remote endpoint is not capable of rtcp-mux, session negotiation will fail.

4.2.7 Offer/Answer Options

These dictionaries describe the options that can be used to control the offer/answer creation process.

  1. WebIDLdictionary RTCOfferAnswerOptions {};
Dictionary RTCOfferAnswerOptions Members
  1. WebIDL            dictionary RTCOfferOptions : RTCOfferAnswerOptions {
  2.   boolean iceRestart = false;
  3. };
Dictionary RTCOfferOptions Members

iceRestart of type boolean, defaulting to false

When the value of this dictionary member is true, or the relevant RTCPeerConnection object’s [[LocalIceCredentialsToReplace]] slot is not empty, then the generated description will have ICE credentials that are different from the current credentials (as visible in the currentLocalDescription attribute’s SDP). Applying the generated description will restart ICE, as described in section 9.1.1.1 of [RFC5245].

When the value of this dictionary member is false, and the relevant RTCPeerConnection object’s [[LocalIceCredentialsToReplace]] slot is empty, and the currentLocalDescription attribute has valid ICE credentials, then the generated description will have the same ICE credentials as the current value from the currentLocalDescription attribute.

Note

Performing an ICE restart is recommended when iceConnectionState transitions to “failed“. An application may additionally choose to listen for the iceConnectionState transition to “disconnected“ and then use other sources of information (such as using getStats to measure if the number of bytes sent or received over the next couple of seconds increases) to determine whether an ICE restart is advisable.

The RTCAnswerOptions dictionary describe options specific to session description of type “answer“ (none in this version of the specification).

  1. WebIDLdictionary RTCAnswerOptions : RTCOfferAnswerOptions {};