RTCPeerConnection: RTCPeerConnection() constructor

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨September 2017⁩.

* Some parts of this feature may have varying levels of support.

TheRTCPeerConnection() constructor returns a newly-createdRTCPeerConnection, which represents a connection between the local device and a remote peer.

Syntax

new RTCPeerConnection()new RTCPeerConnection(configuration)

Parameters

configurationOptional

An object providing options to configure the new connection:

bundlePolicyOptional

Specifies how to handle negotiation of candidates when the remote peer is not compatible with theSDP BUNDLE standard. If the remote endpoint is BUNDLE-aware, all media tracks and data channels are bundled onto a single transport at the completion of negotiation, regardless of policy used, and any superfluous transports that were created initially are closed at that point.

In technical terms, a BUNDLE lets all media flow between two peers flow across a single5-tuple; that is, from a single IP and port on one peer to a single IP and port on the other peer, using the same transport protocol.

This must be one of the following string values, if notbalanced is assumed:

"balanced": The ICE agent initially creates oneRTCDtlsTransport for each type of content added: audio, video, and data channels. If the remote endpoint is not BUNDLE-aware, then each of these DTLS transports handles all the communication for one type of data.
"max-compat": The ICE agent initially creates oneRTCDtlsTransport per media track and a separate one for data channels. If the remote endpoint is not BUNDLE-aware, everything is negotiated on these separate DTLS transports.
"max-bundle": The ICE agent initially creates only a singleRTCDtlsTransport to carry all of theRTCPeerConnection's data. If the remote endpoint is not BUNDLE-aware, then only a single track will be negotiated and the rest ignored.

certificatesOptional

AnArray of objects of typeRTCCertificate which are used by the connection for authentication. If this property isn't specified, a set of certificates is generated automatically for eachRTCPeerConnection instance. Although only one certificate is used by a given connection, providing certificates for multiple algorithms may improve the odds of successfully connecting in some circumstances. SeeUsing certificates for further information.

Note:This configuration option cannot be changed after it is first specified; once the certificates have been set, this property is ignored in future calls toRTCPeerConnection.setConfiguration().

iceCandidatePoolSizeOptional

An unsigned 16-bit integer value which specifies the size of the prefetched ICE candidate pool. The default value is 0 (meaning no candidate prefetching will occur). You may find in some cases that connections can be established more quickly by allowing the ICE agent to start fetching ICE candidates before you start trying to connect, so that they're already available for inspection whenRTCPeerConnection.setLocalDescription() is called.

Note:Changing the size of the ICE candidate pool may trigger the beginning of ICE gathering.

iceServersOptional

An array of objects, each describing one server which may be used by the ICE agent; these are typically STUN and/or TURN servers. If this isn't specified, the connection attempt will be made with no STUN or TURN server available, which limits the connection to local peers. Each object may have the following properties:

credentialOptional: The credential to use when logging into the server. This is only used if the object represents a TURN server.
credentialTypeOptional Deprecated Non-standard: If the object represents a TURN server, this attribute specifies what kind ofcredential is to be used when connecting. The default is"password".
urls: Thisrequired property is either a single string or an array of strings, each specifying a URL which can be used to connect to the server.
usernameOptional: If the object represents a TURN server, then this is the username to use during the authentication.

iceTransportPolicyOptional

A string representing the current ICE transport policy. Possible values are:

"all": All ICE candidates will be considered. This is the default value.
"public"Deprecated: Only ICE candidates with public IP addresses will be considered.
"relay": Only ICE candidates whose IP addresses are being relayed, such as those being passed through a TURN server, will be considered.

peerIdentityOptional

A string which specifies the target peer identity for theRTCPeerConnection. If this value is set (it defaults tonull), theRTCPeerConnection will not connect to a remote peer unless it can successfully authenticate with the given name.

rtcpMuxPolicyOptional

A string which specifies the RTCP mux policy to use when gathering ICE candidates, in order to support non-multiplexed RTCP. Possible values are:

"negotiate": Instructs the ICE agent to gather bothRTP andRTCP candidates. If the remote peer can multiplex RTCP, then RTCP candidates are multiplexed atop the corresponding RTP candidates. Otherwise, both the RTP and RTCP candidates are returned, separately.
"require": Tells the ICE agent to gather ICE candidates for only RTP, and to multiplex RTCP atop them. If the remote peer doesn't support RTCP multiplexing, then session negotiation fails. This is the default value.

Return value

A newly-createdRTCPeerConnection object, configured as described byconfiguration, if specified; otherwise, configured to appropriate basic defaults.

Using certificates

When you wish to provide your own certificates for use by anRTCPeerConnection instead of having theRTCPeerConnection generate them automatically, you do so by calling the staticRTCPeerConnection.generateCertificate() function.

Thecertificates property's value cannot be changed once it's first specified. If it's included in the configuration passed into a call to a connection'ssetConfiguration(), it is ignored.

This attribute supports providing multiple certificates because even though a given DTLS connection uses only one certificate, providing multiple certificates allows support for multiple encryption algorithms. The implementation ofRTCPeerConnection will choose which certificate to use based on the algorithms it and the remote peer support, as determined during DTLS handshake.

If you don't provide certificates, new ones are generated automatically. One obvious benefit to providing your own is identity key continuity—if you use the same certificate for subsequent calls, the remote peer can tell you're the same caller. This also avoids the cost of generating new keys.