API Reference

WebRTC

class aiortc.RTCPeerConnection(configuration=None)

The RTCPeerConnection interface represents a WebRTC connection between the local computer and a remote peer.

Parameters:

configuration (Optional[RTCConfiguration]) – An optional RTCConfiguration.

property connectionState: str

The current connection state.

Possible values: “connected”, “connecting”, “closed”, “failed”, “new”.

When the state changes, the “connectionstatechange” event is fired.

property iceConnectionState: str

The current ICE connection state.

Possible values: “checking”, “completed”, “closed”, “failed”, “new”.

When the state changes, the “iceconnectionstatechange” event is fired.

property iceGatheringState: str

The current ICE gathering state.

Possible values: “complete”, “gathering”, “new”.

When the state changes, the “icegatheringstatechange” event is fired.

property localDescription: RTCSessionDescription

An RTCSessionDescription describing the session for the local end of the connection.

property remoteDescription: RTCSessionDescription

An RTCSessionDescription describing the session for the remote end of the connection.

property sctp: RTCSctpTransport | None

An RTCSctpTransport describing the SCTP transport being used for datachannels or None.

property signalingState: str

The current signaling state.

Possible values: “closed”, “have-local-offer”, “have-remote-offer”, “stable”.

When the state changes, the “signalingstatechange” event is fired.

await addIceCandidate(candidate)

Add a new RTCIceCandidate received from the remote peer.

The specified candidate must have a value for either sdpMid or sdpMLineIndex.

Parameters:

candidate (Optional[RTCIceCandidate]) – The new remote candidate or None to signal end-of-candidates.

Return type:

None

addTrack(track)

Add a MediaStreamTrack to the set of media tracks which will be transmitted to the remote peer.

Return type:

RTCRtpSender

addTransceiver(trackOrKind, direction='sendrecv')

Add a new RTCRtpTransceiver.

Return type:

RTCRtpTransceiver

await close()

Terminate the ICE agent, ending ICE processing and streams.

Return type:

None

await createAnswer()

Create an SDP answer to an offer received from a remote peer during the offer/answer negotiation of a WebRTC connection.

Return type:

RTCSessionDescription

createDataChannel(label, maxPacketLifeTime=None, maxRetransmits=None, ordered=True, protocol='', negotiated=False, id=None)

Create a data channel with the given label.

Return type:

RTCDataChannel

await createOffer()

Create an SDP offer for the purpose of starting a new WebRTC connection to a remote peer.

Return type:

RTCSessionDescription

getReceivers()

Returns the list of RTCRtpReceiver objects that are currently attached to the connection.

Return type:

list[RTCRtpReceiver]

getSenders()

Returns the list of RTCRtpSender objects that are currently attached to the connection.

Return type:

list[RTCRtpSender]

await getStats()

Returns statistics for the connection.

Return type:

RTCStatsReport

getTransceivers()

Returns the list of RTCRtpTransceiver objects that are currently attached to the connection.

Return type:

list[RTCRtpTransceiver]

await setLocalDescription(sessionDescription=None)

Change the local description associated with the connection.

Parameters:

sessionDescription (Optional[RTCSessionDescription]) – An RTCSessionDescription generated by createOffer() or createAnswer() or None to implicitly create an offer or create an answer, as needed.

Return type:

None

await setRemoteDescription(sessionDescription)

Changes the remote description associated with the connection.

Parameters:

sessionDescription (RTCSessionDescription) – An RTCSessionDescription created from information received over the signaling channel.

Return type:

None

class aiortc.RTCSessionDescription(sdp, type)

The RTCSessionDescription dictionary describes one end of a connection and how it’s configured.

class aiortc.RTCBundlePolicy

The RTCBundlePolicy affects which media tracks are negotiated if the remote endpoint is not bundle-aware, and what ICE candidates are gathered.

See https://w3c.github.io/webrtc-pc/#rtcbundlepolicy-enum

BALANCED = 'balanced'

Gather 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_COMPAT = 'max-compat'

Gather ICE candidates for each track. If the remote endpoint is not bundle-aware, negotiate all media tracks on separate transports.

MAX_BUNDLE = 'max-bundle'

Gather ICE candidates for only one track. If the remote endpoint is not bundle-aware, negotiate only one media track.

class aiortc.RTCConfiguration(iceServers=None, bundlePolicy=RTCBundlePolicy.BALANCED)

The RTCConfiguration dictionary is used to provide configuration options for an RTCPeerConnection.

iceServers: Optional[list[RTCIceServer]] = None

A list of RTCIceServer objects to configure STUN / TURN servers.

bundlePolicy: RTCBundlePolicy = 'balanced'

The media-bundling policy to use when gathering ICE candidates.

Interactive Connectivity Establishment (ICE)

class aiortc.RTCIceCandidate(component, foundation, ip, port, priority, protocol, type, relatedAddress=None, relatedPort=None, sdpMid=None, sdpMLineIndex=None, tcpType=None)

The RTCIceCandidate interface represents a candidate Interactive Connectivity Establishment (ICE) configuration which may be used to establish an RTCPeerConnection.

class aiortc.RTCIceGatherer(iceServers=None, local_username=None, local_password=None)

The RTCIceGatherer interface gathers local host, server reflexive and relay candidates, as well as enabling the retrieval of local Interactive Connectivity Establishment (ICE) parameters which can be exchanged in signaling.

property state: str

The current state of the ICE gatherer.

await gather()

Gather ICE candidates.

Return type:

None

classmethod getDefaultIceServers()

Return the list of default RTCIceServer.

Return type:

list[RTCIceServer]

getLocalCandidates()

Retrieve the list of valid local candidates associated with the ICE gatherer.

Return type:

list[RTCIceCandidate]

getLocalParameters()

Retrieve the ICE parameters of the ICE gatherer.

Return type:

RTCIceParameters

class aiortc.RTCIceTransport(gatherer)

The RTCIceTransport interface allows an application access to information about the Interactive Connectivity Establishment (ICE) transport over which packets are sent and received.

Parameters:

gatherer (RTCIceGatherer) – An RTCIceGatherer.

property iceGatherer: RTCIceGatherer

The ICE gatherer passed in the constructor.

property role: str

The current role of the ICE transport.

Either ‘controlling’ or ‘controlled’.

property state: str

The current state of the ICE transport.

await addRemoteCandidate(candidate)

Add a remote candidate.

Parameters:

candidate (Optional[RTCIceCandidate]) – The new candidate or None to signal end of candidates.

Return type:

None

getRemoteCandidates()

Retrieve the list of candidates associated with the remote RTCIceTransport.

Return type:

list[RTCIceCandidate]

await start(remoteParameters)

Initiate connectivity checks.

Parameters:

remoteParameters (RTCIceParameters) – The RTCIceParameters associated with the remote RTCIceTransport.

Return type:

None

await stop()

Irreversibly stop the RTCIceTransport.

Return type:

None

class aiortc.RTCIceParameters(usernameFragment=None, password=None, iceLite=False)

The RTCIceParameters dictionary includes the ICE username fragment and password and other ICE-related parameters.

usernameFragment: Optional[str] = None

ICE username fragment.

password: Optional[str] = None

ICE password.

class aiortc.RTCIceServer(urls, username=None, credential=None, credentialType='password')

The RTCIceServer dictionary defines how to connect to a single STUN or TURN server. It includes both the URL and the necessary credentials, if any, to connect to the server.

urls: Union[str, list[str]]

This required property is either a single string or a list of strings, each specifying a URL which can be used to connect to the server.

username: Optional[str] = None

The username to use during authentication (for TURN only).

credential: Optional[str] = None

The credential to use during authentication (for TURN only).

Datagram Transport Layer Security (DTLS)

class aiortc.RTCCertificate(key, cert)

The RTCCertificate interface enables the certificates used by an RTCDtlsTransport.

To generate a certificate and the corresponding private key use generateCertificate().

property expires: datetime

The date and time after which the certificate will be considered invalid.

getFingerprints()

Returns the list of certificate fingerprints, one of which is computed with the digest algorithm used in the certificate signature.

Return type:

list[RTCDtlsFingerprint]

classmethod generateCertificate()

Create and return an X.509 certificate and corresponding private key.

Return type:

RTCCertificate

class aiortc.RTCDtlsTransport(transport, certificates)

The RTCDtlsTransport object includes information relating to Datagram Transport Layer Security (DTLS) transport.

Parameters:
property state: str

The current state of the DTLS transport.

One of ‘new’, ‘connecting’, ‘connected’, ‘closed’ or ‘failed’.

property transport: RTCIceTransport

The associated RTCIceTransport instance.

getLocalParameters()

Get the local parameters of the DTLS transport.

Return type:

RTCDtlsParameters

await start(remoteParameters)

Start DTLS transport negotiation with the parameters of the remote DTLS transport.

Parameters:

remoteParameters (RTCDtlsParameters) – An RTCDtlsParameters.

Return type:

None

await stop()

Stop and close the DTLS transport.

Return type:

None

class aiortc.RTCDtlsParameters(fingerprints=<factory>, role='auto')

The RTCDtlsParameters dictionary includes information relating to DTLS configuration.

fingerprints: list[RTCDtlsFingerprint]

List of RTCDtlsFingerprint, one fingerprint for each certificate.

role: str = 'auto'

The DTLS role, with a default of auto.

class aiortc.RTCDtlsFingerprint(algorithm, value)

The RTCDtlsFingerprint dictionary includes the hash function algorithm and certificate fingerprint.

algorithm: str

The hash function name, for instance ‘sha-256’.

value: str

The fingerprint value.

Real-time Transport Protocol (RTP)

class aiortc.RTCRtpReceiver(kind, transport)

The RTCRtpReceiver interface manages the reception and decoding of data for a MediaStreamTrack.

Parameters:
property track: MediaStreamTrack

The MediaStreamTrack which is being handled by the receiver.

property transport: RTCDtlsTransport

The RTCDtlsTransport over which the media for the receiver’s track is received.

classmethod getCapabilities(kind)

Returns the most optimistic view of the system’s capabilities for receiving media of the given kind.

Return type:

RTCRtpCapabilities

await getStats()

Returns statistics about the RTP receiver.

Return type:

RTCStatsReport

getSynchronizationSources()

Returns a RTCRtpSynchronizationSource for each unique SSRC identifier received in the last 10 seconds.

Return type:

list[RTCRtpSynchronizationSource]

await receive(parameters)

Attempt to set the parameters controlling the receiving of media.

Parameters:

parameters (RTCRtpReceiveParameters) – The RTCRtpParameters for the receiver.

Return type:

None

await stop()

Irreversibly stop the receiver.

Return type:

None

class aiortc.RTCRtpSender(trackOrKind, transport)

The RTCRtpSender interface provides the ability to control and obtain details about how a particular MediaStreamTrack is encoded and sent to a remote peer.

Parameters:
property track: MediaStreamTrack

The MediaStreamTrack which is being handled by the sender.

property transport: RTCDtlsTransport

The RTCDtlsTransport over which media data for the track is transmitted.

classmethod getCapabilities(kind)

Returns the most optimistic view of the system’s capabilities for sending media of the given kind.

Return type:

RTCRtpCapabilities

await getStats()

Returns statistics about the RTP sender.

Return type:

RTCStatsReport

await send(parameters)

Attempt to set the parameters controlling the sending of media.

Parameters:

parameters (RTCRtpSendParameters) – The RTCRtpSendParameters for the sender.

Return type:

None

await stop()

Irreversibly stop the sender.

Return type:

None

class aiortc.RTCRtpTransceiver(kind, receiver, sender, direction='sendrecv')

The RTCRtpTransceiver interface describes a permanent pairing of an RTCRtpSender and an RTCRtpReceiver, along with some shared state.

property currentDirection: str | None

The currently negotiated direction of the transceiver.

One of ‘sendrecv’, ‘sendonly’, ‘recvonly’, ‘inactive’ or None.

property direction: str

The preferred direction of the transceiver, which will be used in RTCPeerConnection.createOffer() and RTCPeerConnection.createAnswer().

One of ‘sendrecv’, ‘sendonly’, ‘recvonly’ or ‘inactive’.

property receiver: RTCRtpReceiver

The RTCRtpReceiver that handles receiving and decoding incoming media.

property sender: RTCRtpSender

The RTCRtpSender responsible for encoding and sending data to the remote peer.

setCodecPreferences(codecs)

Override the default codec preferences.

See RTCRtpSender.getCapabilities() and RTCRtpReceiver.getCapabilities() for the supported codecs.

Parameters:

codecs (list[RTCRtpCodecCapability]) – A list of RTCRtpCodecCapability, in decreasing order of preference. If empty, restores the default preferences.

Return type:

None

await stop()

Permanently stops the RTCRtpTransceiver.

Return type:

None

class aiortc.RTCRtpSynchronizationSource(timestamp, source)

The RTCRtpSynchronizationSource dictionary contains information about a synchronization source (SSRC).

timestamp: datetime

The timestamp associated with this source.

source: int

The SSRC identifier associated with this source.

class aiortc.RTCRtpCapabilities(codecs=<factory>, headerExtensions=<factory>)

The RTCRtpCapabilities dictionary provides information about support codecs and header extensions.

codecs: list[RTCRtpCodecCapability]

A list of RTCRtpCodecCapability.

headerExtensions: list[RTCRtpHeaderExtensionCapability]

A list of RTCRtpHeaderExtensionCapability.

class aiortc.RTCRtpCodecCapability(mimeType, clockRate, channels=None, parameters=<factory>)

The RTCRtpCodecCapability dictionary provides information on codec capabilities.

mimeType: str

The codec MIME media type/subtype, for instance ‘audio/PCMU’.

clockRate: int

The codec clock rate expressed in Hertz.

channels: Optional[int] = None

The number of channels supported (e.g. two for stereo).

parameters: dict[str, Union[int, str, None]]

Codec-specific parameters available for signaling.

class aiortc.RTCRtpHeaderExtensionCapability(uri)

The RTCRtpHeaderExtensionCapability dictionary provides information on a supported header extension.

uri: str

The URI of the RTP header extension.

class aiortc.RTCRtpParameters(codecs=<factory>, headerExtensions=<factory>, muxId='', rtcp=<factory>)

The RTCRtpParameters dictionary describes the configuration of an RTCRtpReceiver or an RTCRtpSender.

codecs: list[RTCRtpCodecParameters]

A list of RTCRtpCodecParameters to send or receive.

headerExtensions: list[RTCRtpHeaderExtensionParameters]

A list of RTCRtpHeaderExtensionParameters.

muxId: str = ''

The muxId assigned to the RTP stream, if any, empty string if unset.

rtcp: RTCRtcpParameters

Parameters to configure RTCP.

class aiortc.RTCRtpCodecParameters(mimeType, clockRate, channels=None, payloadType=None, rtcpFeedback=<factory>, parameters=<factory>)

The RTCRtpCodecParameters dictionary provides information on codec settings.

mimeType: str

The codec MIME media type/subtype, for instance ‘audio/PCMU’.

clockRate: int

The codec clock rate expressed in Hertz.

channels: Optional[int] = None

The number of channels supported (e.g. two for stereo).

payloadType: Optional[int] = None

The value that goes in the RTP Payload Type Field.

rtcpFeedback: list[RTCRtcpFeedback]

Transport layer and codec-specific feedback messages for this codec.

parameters: dict[str, Union[int, str, None]]

Codec-specific parameters available for signaling.

class aiortc.RTCRtcpParameters(cname=None, mux=False, ssrc=None)

The RTCRtcpParameters dictionary provides information on RTCP settings.

cname: Optional[str] = None

The Canonical Name (CNAME) used by RTCP.

mux: bool = False

Whether RTP and RTCP are multiplexed.

ssrc: Optional[int] = None

The Synchronization Source identifier.

Stream Control Transmission Protocol (SCTP)

class aiortc.RTCSctpTransport(transport, port=5000)

The RTCSctpTransport interface includes information relating to Stream Control Transmission Protocol (SCTP) transport.

Parameters:

transport (RTCDtlsTransport) – An RTCDtlsTransport.

property maxChannels: int | None

The maximum number of RTCDataChannel that can be used simultaneously.

property port: int

The local SCTP port number used for data channels.

property state: str

The current state of the SCTP transport.

property transport: RTCDtlsTransport

The RTCDtlsTransport over which SCTP data is transmitted.

classmethod getCapabilities()

Retrieve the capabilities of the transport.

Return type:

RTCSctpCapabilities

await start(remoteCaps, remotePort)

Start the transport.

Return type:

None

await stop()

Stop the transport.

Return type:

None

class State(value)
class aiortc.RTCSctpCapabilities(maxMessageSize)

The RTCSctpCapabilities dictionary provides information about the capabilities of the RTCSctpTransport.

maxMessageSize: int

The maximum size of data that the implementation can send or 0 if the implementation can handle messages of any size.

Data channels

class aiortc.RTCDataChannel(transport, parameters, send_open=True)

The RTCDataChannel interface represents a network channel which can be used for bidirectional peer-to-peer transfers of arbitrary data.

Parameters:
property bufferedAmount: int

The number of bytes of data currently queued to be sent over the data channel.

property bufferedAmountLowThreshold: int

The number of bytes of buffered outgoing data that is considered “low”.

property negotiated: bool

Whether data channel was negotiated out-of-band.

property id: int | None

An ID number which uniquely identifies the data channel.

property label: str

A name describing the data channel.

These labels are not required to be unique.

property ordered: bool

Indicates whether or not the data channel guarantees in-order delivery of messages.

property maxPacketLifeTime: int | None

The maximum time in milliseconds during which transmissions are attempted.

property maxRetransmits: int | None

“The maximum number of retransmissions that are attempted.

property protocol: str

The name of the subprotocol in use.

property readyState: str

A string indicating the current state of the underlying data transport.

property transport: RTCSctpTransport

The RTCSctpTransport over which data is transmitted.

close()

Close the data channel.

Return type:

None

send(data)

Send data across the data channel to the remote peer.

Return type:

None

class aiortc.RTCDataChannelParameters(label='', maxPacketLifeTime=None, maxRetransmits=None, ordered=True, protocol='', negotiated=False, id=None)

The RTCDataChannelParameters dictionary describes the configuration of an RTCDataChannel.

label: str = ''

A name describing the data channel.

maxPacketLifeTime: Optional[int] = None

The maximum time in milliseconds during which transmissions are attempted.

maxRetransmits: Optional[int] = None

The maximum number of retransmissions that are attempted.

ordered: bool = True

Whether the data channel guarantees in-order delivery of messages.

protocol: str = ''

The name of the subprotocol in use.

negotiated: bool = False

Whether data channel will be negotiated out of-band, where both sides create data channel with an agreed-upon ID.

id: Optional[int] = None

An numeric ID for the channel; permitted values are 0-65534. If you don’t include this option, the user agent will select an ID for you. Must be set when negotiating out-of-band.

Media

class aiortc.MediaStreamTrack

A single media track within a stream.

property id: str

An automatically generated globally unique ID.

abstractmethod await recv()

Receive the next AudioFrame, VideoFrame or Packet

Return type:

Union[Frame, Packet]

Statistics

class aiortc.RTCStatsReport

Provides statistics data about WebRTC connections as returned by the RTCPeerConnection.getStats(), RTCRtpReceiver.getStats() and RTCRtpSender.getStats() coroutines.

This object consists of a mapping of string identifiers to objects which are instances of:

class aiortc.RTCInboundRtpStreamStats(timestamp, type, id, ssrc, kind, transportId, packetsReceived, packetsLost, jitter)

The RTCInboundRtpStreamStats dictionary represents the measurement metrics for the incoming RTP media stream.

class aiortc.RTCOutboundRtpStreamStats(timestamp, type, id, ssrc, kind, transportId, packetsSent, bytesSent, trackId)

The RTCOutboundRtpStreamStats dictionary represents the measurement metrics for the outgoing RTP stream.

class aiortc.RTCRemoteInboundRtpStreamStats(timestamp, type, id, ssrc, kind, transportId, packetsReceived, packetsLost, jitter, roundTripTime, fractionLost)

The RTCRemoteInboundRtpStreamStats dictionary represents the remote endpoint’s measurement metrics for a particular incoming RTP stream.

class aiortc.RTCRemoteOutboundRtpStreamStats(timestamp, type, id, ssrc, kind, transportId, packetsSent, bytesSent, remoteTimestamp=None)

The RTCRemoteOutboundRtpStreamStats dictionary represents the remote endpoint’s measurement metrics for its outgoing RTP stream.

class aiortc.RTCTransportStats(timestamp, type, id, packetsSent, packetsReceived, bytesSent, bytesReceived, iceRole, dtlsState)

RTCTransportStats(timestamp: datetime.datetime, type: str, id: str, packetsSent: int, packetsReceived: int, bytesSent: int, bytesReceived: int, iceRole: str, dtlsState: str)

packetsSent: int

Total number of packets sent over this transport.

packetsReceived: int

Total number of packets received over this transport.

bytesSent: int

Total number of bytes sent over this transport.

bytesReceived: int

Total number of bytes received over this transport.

iceRole: str

The current value of RTCIceTransport.role.

dtlsState: str

The current value of RTCDtlsTransport.state.