Table of Contents

Class WebRTCPeerConnection

Interface to a WebRTC peer connection.

Inheritance
WebRTCPeerConnection
Derived

Remarks

A WebRTC connection between the local computer and a remote peer. Provides an interface to connect, maintain and monitor the connection.

Setting up a WebRTC connection between two peers may not seem a trivial task, but it can be broken down into 3 main steps:

  • The peer that wants to initiate the connection (A from now on) creates an offer and send it to the other peer (B from now on).

  • B receives the offer, generate and answer, and sends it to A).

  • A and B then generates and exchange ICE candidates with each other.

After these steps, the connection should become connected. Keep on reading or look into the tutorial for more information.

Methods

add_ice_candidate(String, int, String)

Add an ice candidate generated by a remote peer (and received over the signaling server). See WebRTCPeerConnection.ice_candidate_created.

int add_ice_candidate(String media, int index, String name)

Parameters

media String
index int
name String

close

Close the peer connection and all data channels associated with it.

Note: You cannot reuse this object for a new connection unless you call WebRTCPeerConnection.initialize.

void close

create_data_channel(String, Dictionary)

Returns a new WebRTCDataChannel (or null on failure) with given label and optionally configured via the options dictionary. This method can only be called when the connection is in state WebRTCPeerConnection.STATE_NEW.

There are two ways to create a working data channel: either call WebRTCPeerConnection.create_data_channel on only one of the peer and listen to WebRTCPeerConnection.data_channel_received on the other, or call WebRTCPeerConnection.create_data_channel on both peers, with the same values, and the "negotiated" option set to true.

Valid options are:

{
    "negotiated": true, # When set to true (default off), means the channel is negotiated out of band. "id" must be set too. "data_channel_received" will not be called.
    "id": 1, # When "negotiated" is true this value must also be set to the same value on both peer.

    # Only one of maxRetransmits and maxPacketLifeTime can be specified, not both. They make the channel unreliable (but also better at real time).
    "maxRetransmits": 1, # Specify the maximum number of attempt the peer will make to retransmits packets if they are not acknowledged.
    "maxPacketLifeTime": 100, # Specify the maximum amount of time before giving up retransmitions of unacknowledged packets (in milliseconds).
    "ordered": true, # When in unreliable mode (i.e. either "maxRetransmits" or "maxPacketLifetime" is set), "ordered" (true by default) specify if packet ordering is to be enforced.

    "protocol": "my-custom-protocol", # A custom sub-protocol string for this channel.

}

Note: You must keep a reference to channels created this way, or it will be closed.

WebRTCDataChannel create_data_channel(String label, Dictionary options)

Parameters

label String
options Dictionary

create_offer

Creates a new SDP offer to start a WebRTC connection with a remote peer. At least one WebRTCDataChannel must have been created before calling this method.

If this functions returns @GlobalScope.OK, WebRTCPeerConnection.session_description_created will be called when the session is ready to be sent.

int create_offer

get_connection_state

Qualifiers: const

Returns the connection state. See ConnectionState.

int get_connection_state

get_gathering_state

Qualifiers: const

Returns the ICE GatheringState of the connection. This lets you detect, for example, when collection of ICE candidates has finished.

int get_gathering_state

get_signaling_state

Qualifiers: const

Returns the signaling state on the local end of the connection while connecting or reconnecting to another peer.

int get_signaling_state

initialize(Dictionary)

Re-initialize this peer connection, closing any previously active connection, and going back to state WebRTCPeerConnection.STATE_NEW. A dictionary of configuration options can be passed to configure the peer connection.

Valid configuration options are:

{
    "iceServers": [
        {
            "urls": [ "stun:stun.example.com:3478" ], # One or more STUN servers.
        },
        {
            "urls": [ "turn:turn.example.com:3478" ], # One or more TURN servers.
            "username": "a_username", # Optional username for the TURN server.
            "credential": "a_password", # Optional password for the TURN server.
        }

    ]

}


int initialize(Dictionary configuration)

Parameters

configuration Dictionary

poll

Call this method frequently (e.g. in Node._process or Node._physics_process) to properly receive signals.

int poll

set_default_extension(StringName)

Qualifiers: static

Sets the extension_class as the default WebRTCPeerConnectionExtension returned when creating a new WebRTCPeerConnection.

void set_default_extension(StringName extension_class)

Parameters

extension_class StringName

set_local_description(String, String)

Sets the SDP description of the local peer. This should be called in response to WebRTCPeerConnection.session_description_created.

After calling this function the peer will start emitting WebRTCPeerConnection.ice_candidate_created (unless an Error different from @GlobalScope.OK is returned).

int set_local_description(String type, String sdp)

Parameters

type String
sdp String

set_remote_description(String, String)

Sets the SDP description of the remote peer. This should be called with the values generated by a remote peer and received over the signaling server.

If type is "offer" the peer will emit WebRTCPeerConnection.session_description_created with the appropriate answer.

If type is "answer" the peer will start emitting WebRTCPeerConnection.ice_candidate_created.

int set_remote_description(String type, String sdp)

Parameters

type String
sdp String

Events

data_channel_received(WebRTCDataChannel)

Emitted when a new in-band channel is received, i.e. when the channel was created with negotiated: false (default).

The object will be an instance of WebRTCDataChannel. You must keep a reference of it or it will be closed automatically. See WebRTCPeerConnection.create_data_channel.

signal data_channel_received(WebRTCDataChannel channel)

Parameters

channel WebRTCDataChannel

ice_candidate_created(String, int, String)

Emitted when a new ICE candidate has been created. The three parameters are meant to be passed to the remote peer over the signaling server.

signal ice_candidate_created(String media, int index, String name)

Parameters

media String
index int
name String

session_description_created(String, String)

Emitted after a successful call to create_offer or WebRTCPeerConnection.set_remote_description (when it generates an answer). The parameters are meant to be passed to WebRTCPeerConnection.set_local_description on this object, and sent to the remote peer over the signaling server.

signal session_description_created(String type, String sdp)

Parameters

type String
sdp String