0
# aiortc
1

2
A comprehensive Python implementation of Web Real-Time Communication (WebRTC) and Object Real-Time Communication (ORTC) protocols built on asyncio. aiortc enables real-time peer-to-peer communication with support for audio, video, and data channels, offering features like SDP generation/parsing, Interactive Connectivity Establishment (ICE), DTLS encryption, SRTP/SRTCP for media streams, and a pure Python SCTP implementation for data channels.
3

4
## Package Information
5

6
- **Package Name**: aiortc
7
- **Language**: Python
8
- **Installation**: `pip install aiortc`
9
- **Version**: 1.13.0
10

11
## Core Imports
12

13
```python
14
import aiortc
15
```
16

17
Common imports for WebRTC applications:
18

19
```python
20
from aiortc import (
21
    RTCPeerConnection,
22
    RTCConfiguration,
23
    RTCIceServer,
24
    RTCSessionDescription,
25
    AudioStreamTrack,
26
    VideoStreamTrack
27
)
28
```
29

30
## Basic Usage
31

32
```python
33
import aiortc
34
import asyncio
35

36
async def create_peer_connection():
37
    # Create peer connection with STUN server
38
    configuration = aiortc.RTCConfiguration(
39
        iceServers=[aiortc.RTCIceServer("stun:stun.l.google.com:19302")]
40
    )
41
    pc = aiortc.RTCPeerConnection(configuration=configuration)
42
    
43
    # Add media tracks
44
    audio_track = aiortc.AudioStreamTrack()  # Generates silence
45
    video_track = aiortc.VideoStreamTrack()  # Generates green frames
46
    pc.addTrack(audio_track)
47
    pc.addTrack(video_track)
48
    
49
    # Create data channel
50
    channel = pc.createDataChannel("chat")
51
    
52
    # Create and set local description
53
    offer = await pc.createOffer()
54
    await pc.setLocalDescription(offer)
55
    
56
    return pc
57

58
# Run async function
59
pc = asyncio.run(create_peer_connection())
60
```
61

62
## Architecture
63

64
aiortc follows the WebRTC standard architecture with these key components:
65

66
- **RTCPeerConnection**: Main entry point managing the complete peer-to-peer connection lifecycle
67
- **Transport Layer**: ICE, DTLS, and SCTP transports handling connectivity, security, and data delivery
68
- **Media Layer**: RTP senders/receivers and transceivers for audio/video streaming
69
- **Data Channels**: SCTP-based reliable data transport for application messages
70
- **Media Streams**: Abstract base classes for custom audio/video track implementations
71

72
The library provides a pure Python implementation that follows JavaScript WebRTC APIs while using Pythonic constructs like coroutines instead of promises and EventEmitter for events.
73

74
## Capabilities
75

76
### Peer Connection Management
77

78
Core WebRTC peer connection functionality including connection establishment, signaling state management, ICE candidate handling, and session description processing.
79

80
```python { .api }
81
class RTCPeerConnection:
82
    def __init__(self, configuration=None): ...
83
    async def createOffer(self): ...
84
    async def createAnswer(self): ...
85
    async def setLocalDescription(self, description): ...
86
    async def setRemoteDescription(self, description): ...
87
    async def addIceCandidate(self, candidate): ...
88
    def addTrack(self, track, *streams): ...
89
    def addTransceiver(self, trackOrKind, direction="sendrecv"): ...
90
    def createDataChannel(self, label, **options): ...
91
    async def close(self): ...
92
```
93

94
[Peer Connection](./peer-connection.md)
95

96
### Media Streaming
97

98
Audio and video track management with base classes for custom media sources, support for multiple media formats, and integration with the RTP protocol stack.
99

100
```python { .api }
101
class MediaStreamTrack:
102
    async def recv(self): ...
103
    def stop(self): ...
104

105
class AudioStreamTrack(MediaStreamTrack):
106
    async def recv(self): ...
107

108
class VideoStreamTrack(MediaStreamTrack):
109
    async def recv(self): ...
110
    async def next_timestamp(self): ...
111
```
112

113
[Media Streaming](./media-streaming.md)
114

115
### RTP Transport
116

117
Real-time Transport Protocol implementation with senders, receivers, transceivers, and complete parameter configuration for audio/video streaming.
118

119
```python { .api }
120
class RTCRtpSender:
121
    async def send(self, parameters): ...
122
    async def replaceTrack(self, track): ...
123
    async def getStats(self): ...
124

125
class RTCRtpReceiver:
126
    async def receive(self, parameters): ...
127
    async def getStats(self): ...
128

129
class RTCRtpTransceiver:
130
    def setCodecPreferences(self, codecs): ...
131
    def stop(self): ...
132
```
133

134
[RTP Transport](./rtp-transport.md)
135

136
### Data Channels
137

138
SCTP-based data channels for reliable application data transport with support for ordered/unordered delivery, partial reliability, and binary/text messages.
139

140
```python { .api }
141
class RTCDataChannel:
142
    def send(self, data): ...
143
    def close(self): ...
144

145
class RTCDataChannelParameters:
146
    def __init__(self, label, **options): ...
147
```
148

149
[Data Channels](./data-channels.md)
150

151
### Network Transport
152

153
Low-level transport layer including ICE connectivity establishment, DTLS security, and SCTP association management for reliable data delivery.
154

155
```python { .api }
156
class RTCIceTransport:
157
    async def start(self, remoteParameters): ...
158
    def addRemoteCandidate(self, candidate): ...
159

160
class RTCDtlsTransport:
161
    async def start(self, remoteParameters): ...
162
    def getLocalParameters(self): ...
163

164
class RTCSctpTransport:
165
    async def start(self, remoteCaps, remotePort): ...
166
```
167

168
[Network Transport](./network-transport.md)
169

170
### Configuration and Parameters
171

172
WebRTC configuration objects, RTP parameters, codec capabilities, and session description handling for connection setup and media negotiation.
173

174
```python { .api }
175
class RTCConfiguration:
176
    def __init__(self, iceServers=None, bundlePolicy=None): ...
177

178
class RTCIceServer:
179
    def __init__(self, urls, username=None, credential=None): ...
180

181
class RTCSessionDescription:
182
    def __init__(self, sdp, type): ...
183
```
184

185
[Configuration](./configuration.md)
186

187
### Statistics and Monitoring
188

189
Connection statistics, media quality metrics, and transport performance monitoring for debugging and quality assurance.
190

191
```python { .api }
192
class RTCStatsReport:
193
    def add(self, stats): ...
194

195
class RTCInboundRtpStreamStats: ...
196
class RTCOutboundRtpStreamStats: ...
197
class RTCTransportStats: ...
198
```
199

200
[Statistics](./statistics.md)
201

202
## Exception Handling
203

204
aiortc defines specific exception types for different error conditions:
205

206
```python { .api }
207
class InvalidAccessError(Exception): ...
208
class InvalidStateError(Exception): ...
209
class MediaStreamError(Exception): ...
210
```
211

212
Common error scenarios include invalid state transitions, access violations, and media processing failures.
213

214
## Types
215

216
```python { .api }
217
# Bundle policy enumeration
218
class RTCBundlePolicy:
219
    BALANCED = "balanced"
220
    MAX_COMPAT = "max-compat" 
221
    MAX_BUNDLE = "max-bundle"
222

223
# RTP capabilities and parameters
224
class RTCRtpCapabilities: ...
225
class RTCRtpParameters: ...
226
class RTCRtpCodecParameters: ...
227

228
# DTLS and ICE parameters
229
class RTCDtlsParameters: ...
230
class RTCIceParameters: ...
231
class RTCIceCandidate: ...
232

233
# SCTP capabilities
234
class RTCSctpCapabilities: ...
235
```