RTCPeerConnection

The connection between the local peer and a remote one.

class webrtc.interfaces.rtc_peer_connection.RTCPeerConnection(configuration=None)

A connection to a remote peer, which negotiates and carries media tracks and data channels.

The application exchanges descriptions (create_offer(), create_answer()) and ICE candidates with the remote peer over its own signaling channel. Operations that change the negotiation run one after another, in the order they’re called. See MDN: RTCPeerConnection.

Events:

negotiationneeded (webrtc.Event) – Negotiation (an offer/answer exchange) is needed.
icecandidate (webrtc.RTCPeerConnectionIceEvent) – A local ICE candidate was gathered and should be sent to the remote peer. Its candidate is None once gathering is complete.
icecandidateerror (webrtc.RTCPeerConnectionIceErrorEvent) – A STUN or TURN server failed.
signalingstatechange (webrtc.Event) – signaling_state changed.
iceconnectionstatechange (webrtc.Event) – ice_connection_state changed.
icegatheringstatechange (webrtc.Event) – ice_gathering_state changed.
connectionstatechange (webrtc.Event) – connection_state changed.
track (webrtc.RTCTrackEvent) – A remote track was negotiated.
datachannel (webrtc.RTCDataChannelEvent) – The remote peer created a data channel.

A connection with handlers or a pending operation stays alive until it or its event loop closes.

Parameters:

configuration (webrtc.RTCConfiguration, optional) – The configuration of the connection. The defaults of webrtc.RTCConfiguration are used if it’s omitted.

Raises:

webrtc.InvalidSyntaxError – If an ICE server URL is invalid.
webrtc.InvalidAccessError – If a TURN server has no credentials, or a certificate has expired.
ValueError – If a member of the configuration is out of range.
TypeError – If a member of the configuration has a wrong type, or a value its enum doesn’t have.

Events

negotiationneeded: Event
signalingstatechange: Event
iceconnectionstatechange: Event
icegatheringstatechange: Event
connectionstatechange: Event
icecandidate: RTCPeerConnectionIceEvent
icecandidateerror: RTCPeerConnectionIceErrorEvent
track: RTCTrackEvent
datachannel: RTCDataChannelEvent

Handlers are registered with on().

async create_offer(options=None)

Creates an offer that starts a negotiation or renegotiates one.

The offer describes the transceivers and data channels of the connection, with the codecs it supports and the ICE candidates gathered so far. It isn’t applied until it’s passed to set_local_description(). See MDN: RTCPeerConnection/createOffer.

Parameters:: options (webrtc.RTCOfferOptions, optional) – How to create the offer.
Returns:: webrtc.RTCSessionDescriptionInit – The offer, to set with set_local_description().
Raises:: webrtc.InvalidStateError – If the signaling state isn’t stable or have-local-offer, or the connection is closed.
Return type:: RTCSessionDescriptionInit

async create_answer(options=None)

Creates an answer to the offer set as the remote description.

It isn’t applied until it’s passed to set_local_description(). See MDN: RTCPeerConnection/createAnswer.

Parameters:

options (webrtc.RTCAnswerOptions, optional) – How to create the answer.

Returns:

webrtc.RTCSessionDescriptionInit – The answer, to set with set_local_description().

Raises:

TypeError – If the options aren’t an webrtc.RTCAnswerOptions.
webrtc.InvalidStateError – If the connection is closed or has no remote offer.

Return type:

RTCSessionDescriptionInit

async set_local_description(description=None)

Applies a local session description, which starts ICE gathering.

See MDN: RTCPeerConnection/setLocalDescription.

Parameters:

description (webrtc.RTCSessionDescription, optional) – The description, as returned by create_offer() or create_answer(), or a rollback one. An webrtc.RTCSessionDescriptionInit or webrtc.RTCLocalSessionDescriptionInit is accepted too, with its SDP modified if needed. Without it, or without a type and an SDP, the offer or the answer the signaling state calls for is created and set.

Raises:

webrtc.InvalidStateError – If the type doesn’t match the signaling state, or the connection is closed.
webrtc.InvalidModificationError – If the SDP changes the fingerprint create_offer() or create_answer() made.
webrtc.RTCError – If the SDP can’t be parsed (sdp_syntax_error).
TypeError – If the description has an SDP but no type, or is neither of the accepted types.

async set_remote_description(description)

Applies an offer, an answer or a rollback received from the remote peer.

An offer set while there’s a local offer rolls the local one back first. Remote tracks the description adds are announced with track events. See MDN: RTCPeerConnection/setRemoteDescription.

Parameters:

description (webrtc.RTCSessionDescriptionInit) – The description received from the remote peer, like one from webrtc.RTCSessionDescriptionInit.from_json(). An webrtc.RTCSessionDescription is accepted too.

Raises:

webrtc.InvalidStateError – If the type doesn’t match the signaling state, or the connection is closed.
webrtc.RTCError – If the SDP can’t be parsed (sdp_syntax_error).
webrtc.InvalidAccessError – If the description can’t be applied.
TypeError – If the description is neither of the accepted types.

add_track(track, *streams)

Starts sending a track to the remote peer, from the next negotiation.

If there’s an unused transceiver of the same kind, it’s reused. Otherwise a new one is added. See MDN: RTCPeerConnection/addTrack.

Parameters:

track (webrtc.MediaStreamTrack) – The track to send.
*streams (webrtc.MediaStream) – The local streams the remote peer receives the track in.

Returns:

webrtc.RTCRtpSender – The sender of the track.

Raises:

webrtc.InvalidStateError – If the connection is closed.
webrtc.InvalidAccessError – If a sender of the connection already has the track.

Return type:

RTCRtpSender

add_transceiver(track_or_kind, init=None)

Adds a new transceiver, negotiated with the next offer.

See MDN: RTCPeerConnection/addTransceiver.

Parameters:

track_or_kind (webrtc.MediaStreamTrack or webrtc.MediaType) – The track the sender of the transceiver sends, or the kind of media ('audio' or 'video') for a transceiver without one.
init (webrtc.RTCRtpTransceiverInit, optional) – The options of the new transceiver.

Returns:

webrtc.RTCRtpTransceiver – The new transceiver.

Raises:

TypeError – If the kind is neither audio nor video, or a rid of the send encodings is invalid, or missing or repeated with several encodings.
webrtc.OperationError – If the codec of a send encoding can’t be sent.
webrtc.InvalidStateError – If the connection is closed.

Return type:

RTCRtpTransceiver

get_transceivers()

Returns the transceivers of the connection, in the order they were added.

See MDN: RTCPeerConnection/getTransceivers.

Returns:: list of webrtc.RTCRtpTransceiver – The transceivers.
Return type:: list[RTCRtpTransceiver]

get_senders()

Returns the senders of the transceivers of the connection, one per transceiver.

See MDN: RTCPeerConnection/getSenders.

Returns:: list of webrtc.RTCRtpSender – The senders, including the ones without a track.
Return type:: list[RTCRtpSender]

get_receivers()

Returns the receivers of the transceivers of the connection, one per transceiver.

See MDN: RTCPeerConnection/getReceivers.

Returns:: list of webrtc.RTCRtpReceiver – The receivers.
Return type:: list[RTCRtpReceiver]

remove_track(sender)

Stops sending the track of a sender, from the next negotiation. The sender stays in get_senders().

Does nothing if the sender has no track, or is stopped or rolled back. See MDN: RTCPeerConnection/removeTrack.

Parameters:

sender (webrtc.RTCRtpSender) – A sender of this connection.

Raises:

webrtc.InvalidStateError – If the connection is closed.
webrtc.InvalidAccessError – If the sender wasn’t created by this connection.

async add_ice_candidate(candidate=None)

Adds a candidate received from the remote peer to the remote description.

See MDN: RTCPeerConnection/addIceCandidate.

Parameters:

candidate (webrtc.RTCIceCandidateInit or webrtc.RTCIceCandidate, optional) – The candidate, like one from webrtc.RTCIceCandidateInit.from_json(). An empty candidate, or None, means the end of candidates.

Raises:

TypeError – If a non-empty candidate has neither sdp_mid nor sdp_m_line_index.
webrtc.InvalidStateError – If there’s no remote description, or the connection is closed.
webrtc.OperationError – If the candidate can’t be parsed or doesn’t match a media section.

create_data_channel(label, data_channel_dict=None)

Creates a channel to exchange messages with the remote peer.

The first channel needs a negotiation, which adds the SCTP transport. A negotiated channel isn’t announced to the remote peer, so both peers create it with the same id. See MDN: RTCPeerConnection/createDataChannel.

Parameters:

label (str) – The name of the channel, up to 65535 bytes in UTF-8.
data_channel_dict (webrtc.RTCDataChannelInit, optional) – How to create the channel.

Returns:

webrtc.RTCDataChannel – The channel.

Raises:

TypeError – If the label or an option is out of range, or both max_packet_life_time and max_retransmits are set, or negotiated is set without id.
webrtc.InvalidStateError – If the connection is closed.
webrtc.OperationError – If the id is in use, or no id is left.

Return type:

RTCDataChannel

async get_stats(selector=None)

Collects the stats of the connection, or of the sender or the receiver of a track.

See MDN: RTCPeerConnection/getStats.

Parameters:

selector (webrtc.MediaStreamTrack, optional) – A track of exactly one sender or receiver of the connection. Only the stats of that sender or receiver are collected.

Returns:

webrtc.RTCStatsReport – The stats.

Raises:

webrtc.InvalidAccessError – If no sender or receiver, or more than one, has the track.
webrtc.InvalidStateError – If the connection is closed.

Return type:

RTCStatsReport

async static generate_certificate(keygen_algorithm)

Generates a key and a self-signed certificate on a worker thread, for RTCConfiguration.certificates.

See MDN: RTCPeerConnection/generateCertificate_static.

Parameters:

keygen_algorithm (str or webrtc.Algorithm) – A WebCrypto algorithm: 'ECDSA' (with the P-256 curve), an webrtc.EcKeyGenParams, or an webrtc.RsaHashedKeyGenParams like RsaHashedKeyGenParams('RSASSA-PKCS1-v1_5', modulus_length=2048, public_exponent=bytes([1, 0, 1]), hash='SHA-256'). Its expires sets for how many milliseconds the certificate is valid, up to a year (30 days by default).

Returns:

webrtc.RTCCertificate – The certificate.

Raises:

webrtc.NotSupportedError – If the algorithm isn’t supported.
TypeError – If expires isn’t an unsigned 64-bit integer.

Return type:

webrtc.RTCCertificate

get_configuration()

Returns the configuration of the connection, as it was last set.

The certificates are the ones in use, generated or given. See MDN: RTCPeerConnection/getConfiguration.

Returns:: webrtc.RTCConfiguration – A copy of the configuration. Changing it doesn’t affect the connection.
Return type:: RTCConfiguration

set_configuration(configuration=None)

Replaces the configuration of the connection. Members that aren’t set get their default values.

Changed ICE servers or ICE transport policy apply to the candidates gathered next, like after restart_ice(). See MDN: RTCPeerConnection/setConfiguration.

Parameters:

configuration (webrtc.RTCConfiguration, optional) – The new configuration.

Raises:

webrtc.InvalidStateError – If the connection is closed.
webrtc.InvalidModificationError – If a member that can’t be changed differs, like webrtc.RTCConfiguration.bundle_policy or webrtc.RTCConfiguration.always_negotiate_data_channels.
webrtc.InvalidSyntaxError – If an ICE server URL is invalid.
webrtc.InvalidAccessError – If a TURN server has no credentials, or a certificate has expired.
ValueError – If a member of the configuration is out of range.
TypeError – If a member of the configuration has a wrong type, or a value its enum doesn’t have.

restart_ice()

Requests an ICE restart, with new credentials and candidates, from the next negotiation on either side.

It leads to a negotiationneeded event. It does nothing before the first local description, since that one already has new credentials, or once the connection is closed. See MDN: RTCPeerConnection/restartIce.

close()

Closes the connection for good, stopping its transceivers and data channels.

No events follow except remote tracks’ ended. See MDN: RTCPeerConnection/close.

property sctp: RTCSctpTransport | None