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: Optional[RTCSctpTransport]

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

property signalingState

The current signaling state.

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

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

coroutine addIceCandidate(self, candidate)

Add a new RTCIceCandidate received from the remote peer.

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

Parameters

candidate (RTCIceCandidate) – The new remote candidate.

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

coroutine close()

Terminate the ICE agent, ending ICE processing and streams.

coroutine 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

coroutine createOffer(self)

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]

coroutine getStats(self)

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]

coroutine setLocalDescription(self, sessionDescription)

Change the local description associated with the connection.

Parameters

sessionDescription (RTCSessionDescription) – An RTCSessionDescription generated by createOffer() or createAnswer().

Return type

None

coroutine setRemoteDescription(self, 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.RTCConfiguration(iceServers=None)

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.

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)

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.

coroutine gather(self)

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.

coroutine addRemoteCandidate(self, 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]

coroutine start(self, remoteParameters)

Initiate connectivity checks.

Parameters

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

Return type

None

coroutine stop(self)

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: 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

The associated RTCIceTransport instance.

getLocalParameters()

Get the local parameters of the DTLS transport.

Return type

RTCDtlsParameters

coroutine start(self, remoteParameters)

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

Parameters

remoteParameters (RTCDtlsParameters) – An RTCDtlsParameters.

Return type

None

coroutine stop(self)

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

coroutine getStats(self)

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]

coroutine receive(self, parameters)

Attempt to set the parameters controlling the receiving of media.

Parameters

parameters (RTCRtpReceiveParameters) – The RTCRtpParameters for the receiver.

Return type

None

coroutine stop(self)

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

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

coroutine getStats(self)

Returns statistics about the RTP sender.

Return type

RTCStatsReport

coroutine send(self, parameters)

Attempt to set the parameters controlling the sending of media.

Parameters

parameters (RTCRtpSendParameters) – The RTCRtpSendParameters for the sender.

Return type

None

coroutine stop()

Irreversibly stop the sender.

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: Optional[str]

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

coroutine stop()

Permanently stops the RTCRtpTransceiver.

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: Optional[int]

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

The RTCDtlsTransport over which SCTP data is transmitted.

classmethod getCapabilities()

Retrieve the capabilities of the transport.

Return type

RTCSctpCapabilities

coroutine start(self, remoteCaps, remotePort)

Start the transport.

Return type

None

coroutine stop(self)

Stop the transport.

Return type

None

class State(value)

An enumeration.

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: Optional[int]

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: Optional[int]

The maximum time in milliseconds during which transmissions are attempted.

property maxRetransmits: Optional[int]

“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

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.

coroutine recv(self)

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.