RTCPeerConnection

The RTCPeerConnection interface represents a WebRTC connection between the local computer and a remote peer. It provides methods to connect to a remote peer, maintain and monitor the connection, and close the connection once it's no longer needed.

Constructor

RTCPeerConnection()

Returns a newly-created RTCPeerConnection, which represents a connection between the local device and a remote peer.

Static methods

generateCertificate()

Creates an X.509 certificate and its corresponding private key, returning a Promise that resolves with the new RTCCertificate once it is generated.

Properties

Also inherits properties from EventTarget.

canTrickleIceCandidates Read only

Returns a boolean value which indicates whether or not the remote peer can accept trickled ICE candidates.

connectionState Read only

Indicates the current state of the peer connection by returning one of the strings new, connecting, connected, disconnected, failed, or closed.

currentLocalDescription Read only

Returns an RTCSessionDescription object describing the local end of the connection as it was most recently successfully negotiated since the last time this RTCPeerConnection finished negotiating and connecting to a remote peer. Also included is a list of any ICE candidates that may already have been generated by the ICE agent since the offer or answer represented by the description was first instantiated.

currentRemoteDescription Read only

Returns an RTCSessionDescription object describing the remote end of the connection as it was most recently successfully negotiated since the last time this RTCPeerConnection finished negotiating and connecting to a remote peer. Also included is a list of any ICE candidates that may already have been generated by the ICE agent since the offer or answer represented by the description was first instantiated.

iceConnectionState Read only

Returns a string which state of the ICE agent associated with this RTCPeerConnection. It can be one of the following values: new, checking, connected, completed, failed, disconnected, or closed.

iceGatheringState Read only

Returns a string that describes connection's ICE gathering state. This lets you detect, for example, when collection of ICE candidates has finished. Possible values are: new, gathering, or complete.

localDescription Read only

Returns an RTCSessionDescription describing the session for the local end of the connection. If it has not yet been set, returns null.

peerIdentity Read only

Returns a Promise that resolves to an RTCIdentityAssertion which contains a string identifying the remote peer. Once this promise resolves successfully, the resulting identity is the target peer identity and will not change for the duration of the connection.

pendingLocalDescription Read only

Returns an RTCSessionDescription object describing a pending configuration change for the local end of the connection. This does not describe the connection as it currently stands, but as it may exist in the near future.

pendingRemoteDescription Read only

Returns an RTCSessionDescription object describing a pending configuration change for the remote end of the connection. This does not describe the connection as it currently stands, but as it may exist in the near future.

remoteDescription Read only

Returns an RTCSessionDescription object describing the session, including configuration and media information, for the remote end of the connection. If this hasn't been set yet, this returns null.

sctp Read only

Returns an RTCSctpTransport object describing the SCTP transport layer over which SCTP data is being sent and received. If SCTP hasn't been negotiated, this value is null.

signalingState Read only

Returns a string describing the state of the signaling process on the local end of the connection while connecting or reconnecting to another peer. It is one of the following values: stable, have-local-offer, have-remote-offer, have-local-pranswer, have-remote-pranswer, or closed.

Event handlers

Also inherits event handlers from EventTarget.

onconnectionstatechange

Is an event handler which is called to handle the connectionstatechange event. This happens whenever the aggregate state of the connection changes. The aggregate state is a combination of the states of all of the individual network transports being used by the connection.

ondatachannel

Is an event handler which specifies a function which is called to handle the datachannel event. This event, of type RTCDataChannelEvent, is sent when an RTCDataChannel is added to the connection by the remote peer calling createDataChannel().

onicecandidate

Is an event handler which specifies a function which is called to handle the icecandidate event. This happens whenever the local ICE agent needs to deliver a message to the other peer through the signaling server.

onicecandidateerror

Is an event handler which specifies a function which is called to handle the icecandidateerror event. This event is fired when an error occurs during the ICE candidate gathering process.

oniceconnectionstatechange

Is an event handler which specifies a function which is called to handle the iceconnectionstatechange event. This happens whenever the local ICE agent needs to deliver a message to the other peer through the signaling server.

onicegatheringstatechange

Is an event handler which specifies a function which is called to handle the icegatheringstatechange event. This happens when the ICE gathering state changes.

onnegotiationneeded

Is an event handler which specifies a function which is called to handle the negotiationneeded event. This event is fired when a change has occurred which requires session negotiation. This negotiation should be carried out as the offerer, because some session changes cannot be negotiated as the answerer.

onsignalingstatechange

Is an event handler which specifies a function which is called to handle the signalingstatechange event. The function receives as input the event object of type Event; this event is sent when the peer connection's signalingState changes, which may happen either because of a call to setLocalDescription() or to setRemoteDescription().

ontrack

Is an event handler which specifies a function which is called to handle the track event. The function receives as input the event object, of type RTCTrackEvent; this event is sent when a new incoming MediaStreamTrack has been created and associated with an RTCRtpReceiver object which has been added to the set of receivers on the connection.

Obsolete properties

onaddstream This is an obsolete API and is no longer guaranteed to work.

Is an event handler which specifies a function which is called to handle the obsolete addstream event.

onremovestream This is an obsolete API and is no longer guaranteed to work.

Is an event handler which specifies a function which is called to handle the obsolete removestream event.

Methods

Also inherits methods from EventTarget.

addIceCandidate()

Adds a new remote candidate to the RTCPeerConnection's remote description, which describes the state of the remote end of the connection.

addTrack()

Adds a new MediaStreamTrack to the set of tracks which will be transmitted to the other peer.

addTransceiver()

Creates a new RTCRtpTransceiver and adds it to the set of transceivers associated with the connection. Each transceiver represents a bidirectional stream, with both an RTCRtpSender and an RTCRtpReceiver associated with it.

close()

Closes the current peer connection.

createAnswer()

Initiates the creation an SDP answer to an offer received from a remote peer during the offer/answer negotiation of a WebRTC connection. The answer contains information about any media already attached to the session, codecs and options supported by the browser, and any ICE candidates already gathered.

createDataChannel()

Initiates the creation a new channel linked with the remote peer, over which any kind of data may be transmitted. This can be useful for back-channel content, such as images, file transfer, text chat, game update packets, and so forth.

createOffer()

Initiates the creation of an SDP offer for the purpose of starting a new WebRTC connection to a remote peer. The SDP offer includes information about any MediaStreamTrack objects already attached to the WebRTC session, codec, and options supported by the browser, as well as any candidates already gathered by the ICE agent, for the purpose of being sent over the signaling channel to a potential peer to request a connection or to update the configuration of an existing connection.

getConfiguration()

Returns an object which indicates the current configuration of the connection.

getIdentityAssertion()

Initiates the gathering of an identity assertion and returns a Promise which resolves to an identity assertion encoded as a string. This has an effect only if signalingState is not closed.

getReceivers()

Returns an array of RTCRtpReceiver objects, each of which represents one RTP receiver.

getSenders()

Returns an array of RTCRtpSender objects, each of which represents the RTP sender responsible for transmitting one track's data.

getStats()

Returns a Promise which resolves with data providing statistics about either the overall connection or about the specified MediaStreamTrack.

getTransceivers()

Returns a list of all the RTCRtpTransceiver objects being used to send and receive data on the connection.

removeTrack()

Tells the local end of the connection to stop sending media from the specified track, without actually removing the corresponding RTCRtpSender from the list of senders as reported by getSenders(). If the track is already stopped, or is not in the connection's senders list, this method has no effect.

restartIce()

Allows to easily request that ICE candidate gathering be redone on both ends of the connection. This simplifies the process by allowing the same method to be used by either the caller or the receiver to trigger an ICE restart.

setConfiguration()

Sets the current configuration of the connection based on the values included in the specified object. This lets you change the ICE servers used by the connection and which transport policies to use.

setIdentityProvider()

Sets the Identity Provider (IdP) to the triplet given in parameter: its name, the protocol used to communicate with it and an username. The protocol and the username are optional.

setLocalDescription()

Changes the local description associated with the connection. This description specifies the properties of the local end of the connection, including the media format. It returns a Promise which is fulfilled once the description has been changed, asynchronously.

setRemoteDescription()

Sets the specified session description as the remote peer's current offer or answer. The description specifies the properties of the remote end of the connection, including the media format. It returns a Promise which is fulfilled once the description has been changed, asynchronously.

Obsolete methods

addStream() This is an obsolete API and is no longer guaranteed to work.

Adds a MediaStream as a local source of audio or video. Instead of using this obsolete method, you should instead use addTrack() once for each track you wish to send to the remote peer.

createDTMFSender() This is an obsolete API and is no longer guaranteed to work.

Creates a new RTCDTMFSender, associated to a specific MediaStreamTrack, that will be able to send DTMF phone signaling over the connection.

getStreamById() This is an obsolete API and is no longer guaranteed to work.

Returns the MediaStream with the given id that is associated with local or remote end of the connection. This property has been replaced with the getSenders() and getReceivers() methods.

removeStream() This is an obsolete API and is no longer guaranteed to work.

Removes a MediaStream as a local source of audio or video. Because this method is obsolete, you should instead use removeTrack().

Events

Listen to these events using addEventListener() or by assigning an event listener to the oneventname property of this interface.

connectionstatechange

Sent when the overall connectivity status of the RTCPeerConnection changes. Also available through the onconnectionstatechange event handler property.

datachannel

Sent when the remote peer adds an RTCDataChannel to the connection. Also available through the ondatachannel event handler property.

icecandidate

Sent to request that the specified candidate be transmitted to the remote peer. Also available through the onicecandidate event handler property.

icecandidateerror

Sent to the connection if an error occurred during ICE candidate gathering. The event describes the error. Also available through the onicecandidateerror event handler property.

iceconnectionstatechange

Sent when the state of the ICE connection changes, such as when it disconnects. Also available using the oniceconnectionstatechange event handler property.

icegatheringstatechange

Sent when the ICE layer's gathering state, reflected by iceGatheringState, changes. This indicates whether ICE negotiation has not yet begun (new), has begun gathering candidates (gathering), or has completed (complete). Also available using the onicegatheringstatechange event handler property.

negotiationneeded

Sent when negotiation or renegotiation of the ICE connection needs to be performed; this can happen both when first opening a connection as well as when it is necessary to adapt to changing network conditions. The receiver should respond by creating an offer and sending it to the other peer. Also available as the onnegotiationneeded event handler property.

signalingstatechange

Sent when the connection's ICE signaling state changes. Also available through the onsignalingstatechange event handler property.

track

Sent after a new track has been added to one of the RTCRtpReceiver instances which comprise the connection. Also available as the ontrack event handler property.

Obsolete events

addstream This is an obsolete API and is no longer guaranteed to work.

Sent when a new MediaStream has been added to the connection. Instead of listening for this obsolete event, you should listen for track events; one is sent for each MediaStreamTrack added to the connection. Also available as the onaddstream event handler property.

removestream This is an obsolete API and is no longer guaranteed to work.

Sent when a MediaStream is removed from the connection. Instead of listening for this obsolete event, you should listen for removetrack events on each stream. Also available as the onremovestream event handler property.

Specifications

Specification
WebRTC 1.0: Real-Time Communication Between Browsers (WebRTC 1.0)
# interface-definition

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
RTCPeerConnection
56
23
15
15
44
22
No
43
15
11
56
≤37
56
25
44
22
43
14
11
6.0
1.5
RTCPeerConnection
56
Before Chrome 63, the default value for the configuration.rtcpMuxPolicy parameter is "negotiate" instead of "required".
23
15
15
44
22
No
43
Before Opera 50, the default value for the configuration.rtcpMuxPolicy parameter is "negotiate" instead of "required".
15
11
56
Before WebView 63, the default value for the configuration.rtcpMuxPolicy parameter is "negotiate" instead of "required".
≤37
56
Before Chrome 63, the default value for the configuration.rtcpMuxPolicy parameter is "negotiate" instead of "required".
25
44
22
43
Before Opera Android 46, the default value for the configuration.rtcpMuxPolicy parameter is "negotiate" instead of "required".
14
11
6.0
Before Samsung Internet 8.0, the default value for the configuration.rtcpMuxPolicy parameter is "negotiate" instead of "required".
1.5
addIceCandidate
24
15
22
Starting in Firefox 68, the candidate parameter is optional when calling addIceCandidate(). A null value for candidate indicates no more candidates will be sent, while an empty candidate string indicates that no more candidates will be sent for the current generation of candidates.
No
15
11
≤37
25
44
Starting in Firefox 68, the candidate parameter is optional when calling addIceCandidate(). A null value for candidate indicates no more candidates will be sent, while an empty candidate string indicates that no more candidates will be sent for the current generation of candidates.
14
11
1.5
addStream
24
15
22
No
15
11-12
≤37
25
44
14
11-12
1.5
addstream_event
24
15
22
No
15
No
≤37
25
44
14
No
1.5
addTrack
64
79
22
No
51
11
64
64
44
47
11
9.0
addTransceiver
69
79
59
No
No
11
69
69
59
No
11
10.0
canTrickleIceCandidates
No
15-79
47
No
No
No
No
No
44
No
No
No
close
23
15
22
No
15
11
≤37
25
22
14
11
1.5
connectionState
72
79
No
No
60
11
72
72
No
51
11
11.0
connectionstatechange_event
72
79
No
No
60
11
72
72
No
51
No
11.0
createAnswer
24
15
22
No
15
11
≤37
25
44
14
11
1.5
createDataChannel
24
79
22
No
15
11
≤37
25
44
14
11
1.5
createDTMFSender
27
79
22
No
15
No
≤37
27
44
15
No
1.5
createOffer
24
15
22
No
15
11
≤37
25
44
14
11
1.5
currentLocalDescription
70
79
22
No
57
11
70
70
44
49
11
10.0
currentRemoteDescription
70
79
57
No
57
11
70
70
Yes
49
11
10.0
datachannel_event
25
79
22
No
15
11
≤37
25
44
14
11
1.5
generateCertificate
48
79
22
No
35
12.1
48
48
44
35
12.2
6.0
getConfiguration
70
15
22
No
57
11
70
70
44
49
11
10.0
getIdentityAssertion
No
≤18-79
40
No
No
No
No
No
40
No
No
No
getLocalStreams
27
15
22
No
15
11-12
≤37
27
44
15
11-12
1.5
getReceivers
59
79
34
No
46
11
59
59
34
43
11
6.0
getRemoteStreams
27
15
22
No
15
11-12
≤37
27
44
15
11-12
1.5
getSenders
64
79
34
No
51
11
64
64
34
47
11
6.0
getStats
24
15
22
No
15
11
≤37
25
22
14
11
1.5
getStreamById
56-62
15-79
22-53
No
43-49
11-12
56-62
56-62
44
43-46
11-12.2
6.0-8.0
getTransceivers
69
79
59
No
56
11
79
69
59
48
11
10.0
icecandidate_event
24
15
22
No
15
11
≤37
25
44
14
11
1.5
icecandidateerror_event
77
79
No
No
64
14.1
77
77
No
55
14.5
12.0
iceConnectionState
26
15
52
No
15
11
≤37
26
Yes
14
11
1.5
iceconnectionstatechange_event
28
15
22
No
43
11
≤37
28
44
43
11
1.5
iceGatheringState
25
15
22
No
15
11
≤37
25
44
14
11
1.5
icegatheringstatechange_event
59
15
22
No
46
11
59
59
44
43
11
7.0
idpLoginUrl
No
No
40
No
No
No
No
No
40
No
No
No
localDescription
24
15
22
No
15
11
≤37
25
44
14
11
1.5
negotiationneeded_event
24
15
22
No
15
11
≤37
25
44
14
11
1.5
onaddstream
24
15
22
No
15
11-12
≤37
25
44
14
11-12
1.5
onconnectionstatechange
72
79
No
No
No
11
72
72
No
No
11
11.0
ondatachannel
25
79
22
No
15
11
≤37
25
44
14
11
1.5
onicecandidate
24
15
22
No
15
11
≤37
25
44
14
11
1.5
onicecandidateerror
77
79
No
No
64
14.1
77
77
No
55
14.5
12.0
oniceconnectionstatechange
28
15
22
No
15
11
≤37
28
44
15
11
1.5
onicegatheringstatechange
59
15
22
No
46
11
59
59
44
43
11
7.0
onnegotiationneeded
24
15
22
No
15
11
≤37
25
44
14
11
1.5
onremovestream
24
15
22-60
No
15
No
≤37
25
44-60
14
No
1.5
onsignalingstatechange
28
15
22
No
15
11
≤37
28
44
15
11
1.5
ontrack
64
79
22
No
51
11
64
64
44
47
11
6.0
peerIdentity
No
≤18-79
40
No
No
No
No
No
40
No
No
No
pendingLocalDescription
70
79
22
No
57
11
70
70
44
49
11
10.0
pendingRemoteDescription
70
79
22
No
57
11
70
70
44
49
11
10.0
remoteDescription
24
15
22
No
15
11
≤37
25
44
14
11
1.5
removeStream
24
15
22-51
No
15
11-12
≤37
25
44
14
11-12
1.5
removestream_event
24
15
22-60
No
15
No
≤37
25
44-60
14
No
1.5
removeTrack
64
79
22
No
51
11
64
64
44
47
11
6.0
restartIce
77
79
70
No
No
14.1
77
77
No
55
14.5
12.0
sctp
76
79
No
No
No
No
76
76
No
54
No
12.0
setConfiguration
48
79
No
No
35
11
48
48
No
35
11
6.0
setIdentityProvider
No
≤18-79
40
No
No
No
No
No
40
No
No
No
setLocalDescription
24
15
22
Firefox does not support descriptions of type pranswer.
No
15
11
≤37
25
44
14
11
1.5
setRemoteDescription
24
15
22
No
15
11
≤37
25
44
14
11
1.5
signalingState
26
15
22
No
15
11
≤37
26
44
14
11
1.5
signalingstatechange_event
28
15
22
No
15
11
≤37
28
44
15
No
1.5
track_event
64
≤18
22
No
43
11
64
64
44
43
11
6.0

See also

© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection