aiortp
Asyncio RTP/RTCP library for Python — audio and video.
Plain RTP/RTCP for audio and video — no WebRTC, no ICE, no DTLS. Built for telephony, VoIP, and video streaming applications where you need direct control over RTP streams.
Portions derived from aiortc by Jeremy Lainé (BSD-3-Clause).
Features
- Pure Python — zero required dependencies, Python >=3.11
- AsyncIO native — built on
asyncio.DatagramProtocol - Audio codecs — G.711 µ-law/A-law, L16, G.722 (
pip install aiortp[g722]), Opus (pip install aiortp[opus]) - Video codecs — H.264 (RFC 6184), VP8 (RFC 7741), VP9 (RFC 9628) depacketization/packetization
- RTCP — Sender Reports (with real RTP timestamps), Receiver Reports, SDES, BYE, PLI, NACK (retransmission on by default for video, opt-in for audio via
nack_retransmit=True) - DTMF — RFC 4733 telephone-event send/receive with redundant end packets
- Jitter buffer — reordering for both audio (timestamp boundaries) and video (marker-bit frame detection)
- Adaptive clocked playout — opt-in
playout=True: audio delivered on a steady 20 ms media clock from an adaptive jitter buffer that follows measured network jitter - Paced sending — opt-in
paced=True: outgoing frames queued and transmitted one per ptime, silence encoded as timestamp jumps,await session.drain() - Packet loss concealment — confirmed-lost audio replaced with native Opus PLC or generic fade-out repetition, keeping the delivered stream temporally continuous
- Comfort noise (RFC 3389) — opt-in
cn=Trueemission during paced silence (level measured from the stream); PT 13 reception always handled — playout generates the noise, never reads it as loss - Auto-timestamps — optional automatic RTP timestamp generation for audio and video
- Port allocation —
PortAllocatorfor managed even/odd RTP/RTCP port pairs - STUN — inline Binding Responses (IPv4/IPv6, no MESSAGE-INTEGRITY) for simple connectivity probes — not a full ICE agent
- Symmetric RTP — opt-in remote address latching from inbound packets (RFC 4961) for NAT traversal
- TX redundancy — opt-in
duplicate_tx=True: every datagram is re-sent one frame later (receivers dedupe by sequence number), riding out single losses and short bursts on degraded links at the cost of doubled bandwidth - Mid-call robustness — remote SSRC changes (re-INVITE, hold/resume, SBC failover) relatch automatically: stats and buffers reset, video re-keys via PLI
- Fully typed — PEP 561
py.typedmarker included
Installation
pip install aiortp
With optional codecs:
pip install aiortp[opus] # Opus support
pip install aiortp[g722] # G.722 wideband
G.711 encode uses numpy when it is installed (pip install aiortp[numpy]),
which takes it from ~4 µs to under 1 µs per 20 ms frame. Without numpy it
falls back to the standard library; both paths produce the same bytes.
Quick Start — Audio
import asyncio
from aiortp import RTPSession, PayloadType
async def main():
session_a = await RTPSession.create(
local_addr=("127.0.0.1", 10000),
remote_addr=("127.0.0.1", 10002),
payload_type=PayloadType.PCMU,
)
session_b = await RTPSession.create(
local_addr=("127.0.0.1", 10002),
remote_addr=("127.0.0.1", 10000),
payload_type=PayloadType.PCMU,
)
def on_audio(data: bytes, timestamp: int) -> None:
print(f"Received {len(data)} bytes, ts={timestamp}")
session_b.on_audio = on_audio
# Send with auto-incrementing timestamps (160 samples/frame for PCMU)
pcm = b"\x00" * 320 # 160 samples of silence (20ms at 8kHz)
for i in range(10):
session_a.send_audio_pcm_auto(pcm)
await asyncio.sleep(1)
await session_a.close()
await session_b.close()
asyncio.run(main())
Quick Start — Video
import asyncio
from aiortp import VideoRTPSession
async def main():
sender = await VideoRTPSession.create(
local_addr=("127.0.0.1", 20000),
remote_addr=("127.0.0.1", 20002),
codec="h264", # also "vp8" or "vp9"
fps=30,
)
receiver = await VideoRTPSession.create(
local_addr=("127.0.0.1", 20002),
remote_addr=("127.0.0.1", 20000),
codec="h264",
)
def on_frame(data: bytes, timestamp: int, is_keyframe: bool) -> None:
print(f"Frame: {len(data)} bytes, keyframe={is_keyframe}")
receiver.on_frame = on_frame
# Send H.264 NAL units with auto-incrementing timestamps
sps = bytes([0x67, 0x42, 0x00, 0x1E])
pps = bytes([0x68, 0xCE, 0x38, 0x80])
idr = bytes([0x65]) + b"\x00" * 100
sender.send_frame_auto([sps, pps, idr], keyframe=True)
await asyncio.sleep(1)
await sender.close()
await receiver.close()
asyncio.run(main())
DTMF
# Send
session.send_dtmf("1", duration_ms=160, timestamp=0)
# Receive
def on_dtmf(digit: str, duration: int) -> None:
print(f"Got DTMF: {digit}")
session.on_dtmf = on_dtmf
Packet Loss Concealment
With skip_audio_gaps=True, the jitter buffer confirms losses by sequence-number
analysis (sender pauses such as DTMF or VAD suppression are never treated as loss).
Confirmed-lost packets are replaced with concealment PCM before on_audio, so the
delivered stream stays temporally continuous — recordings and AEC alignment are
preserved. Opus uses native libopus PLC; other codecs fall back to a generic
concealer (last-frame repetition fading to silence over 60 ms, then silence).
session = await RTPSession.create(
local_addr=("0.0.0.0", 10000),
remote_addr=("10.0.0.1", 10000),
payload_type=PayloadType.PCMU,
skip_audio_gaps=True, # required: loss is confirmed by the jitter buffer
plc=True, # default — set False to skip lost audio silently
)
print(session.stats["concealed_frames"]) # packets replaced by concealment
In playout mode (playout=True) concealment is deadline-based inside the
playout buffer instead — no extra configuration needed.
Clocked Playout & Paced Sending
With playout=True, on_audio fires on a steady ptime clock (20 ms ticks)
instead of on packet arrival. Frames wait in an adaptive playout buffer whose
target depth follows measured network jitter (bounded by
playout_max_delay_ms, default 200 ms): sustained jitter grows the buffer by
inserting a concealment frame, calm networks shrink it by dropping one.
Missing frames are concealed at their deadline (native Opus PLC or fade-out);
after 120 ms of continuous concealment the gap is treated as a sender pause
(DTX, hold, DTMF) and delivery suspends until the stream resumes.
With paced=True, send_audio_auto / send_audio_pcm_auto enqueue frames
and the session transmits one per ptime on its media clock — push faster than
real time (e.g. a whole file) and the wire stays correctly paced. Silence is
a timestamp jump, not stale packets.
session = await RTPSession.create(
local_addr=("0.0.0.0", 10000),
remote_addr=("10.0.0.1", 10000),
payload_type=PayloadType.PCMU,
playout=True, # clocked receive: on_audio every 20 ms
paced=True, # clocked send: one frame per 20 ms
)
session.on_audio = lambda pcm, ts: sink.write(pcm)
for frame in pcm_frames: # any rate — even all at once
session.send_audio_pcm_auto(frame)
await session.drain() # wait until everything is on the wire
print(session.stats["playout_delay_ms"], session.stats["playout_target_ms"])
Comfort noise (RFC 3389)
With cn=True (requires paced=True), entering a silence period — the
send queue running empty after talk — emits a comfort-noise packet whose
level is measured from the outgoing stream, refreshed every 3 s while the
silence lasts. The first audio frame after silence carries the RFC 3551
talkspurt marker.
Reception is always on, independent of cn: PT 13 packets (configurable
via cn_payload_type) consume sequence numbers without ever reading as
packet loss. In playout mode the silence is filled with generated noise at
the signalled level from the CN timestamp onward (cn_frames in stats),
falling back to suspension if the sender disappears for 30 s; in
arrival-driven mode the level is surfaced through on_cn(level).
OpusCodec(dtx=True) additionally enables the encoder's DTX flag —
whether libopus emits DTX frames depends on its mode selection; aiortp's
silence suppression works through paced mode + CN regardless.
Timing characteristics
Media clocks schedule against absolute deadlines on the event loop, so pacing and playout never accumulate drift: a delayed tick catches up instead of shifting the stream. Indicative measurements (20 ms ticks over 5 s, CPython 3.12, Apple Silicon): mean tick deviation ~0.5 ms and < 0.1 ms cumulative drift on an idle loop; under a hostile load that holds the loop in 5 ms chunks, per-tick deviation rises to ~10 ms while cumulative drift stays below 8 ms and no tick is lost.
Per-tick precision is bounded by event-loop responsiveness: anything that
blocks the loop for N ms delays ticks by up to N ms. Keep on_audio
callbacks light, offload heavy work, and consider uvloop for busy
applications. Sender-side pacing jitter is absorbed by the receiver's
jitter buffer like any other network jitter.
Video RTCP Feedback
# Request a keyframe from the remote sender
receiver.request_keyframe()
# Get notified when the remote side requests a keyframe
def on_keyframe_needed() -> None:
print("Remote requested a keyframe")
sender.on_keyframe_needed = on_keyframe_needed
Port Allocator
from aiortp import PortAllocator, RTPSession
allocator = PortAllocator(port_range=(10000, 20000))
# Session will use an even/odd port pair from the allocator
session = await RTPSession.create(
local_addr=("0.0.0.0", 0),
remote_addr=("10.0.0.1", 10000),
payload_type=0,
port_allocator=allocator,
)
# Ports are released automatically on close
NAT Traversal
With symmetric_rtp=True, the remote RTP and RTCP addresses are latched
from inbound packets (RFC 4961 / comedia) after a successful parse — the
session keeps working when the peer sits behind NAT and its real source
address differs from the SDP one. For signalled address changes
(re-INVITE), session.update_remote((host, port)) stays the explicit
override. The transport also answers STUN Binding Requests so simple
connectivity probes pass.
Session Statistics
session.stats returns a snapshot dict; keys appear as features are used:
- always:
ssrc,packets_sent,octets_sent,concealed_frames - receiving:
packets_received,packets_lost,jitter - from remote receiver reports:
remote_fraction_lost,remote_packets_lost,remote_jitter - playout:
playout_delay_ms,playout_target_ms,expansions,accelerations,late_dropped,underrun_suspensions,cn_frames - paced:
queue_depth,paced_sent,empty_ticks,cn_sent
session.on_receiver_report fires with each incoming RR block reporting
on this session's stream.
Codec Registry
from aiortp import get_codec, register_codec, PayloadType
codec = get_codec(PayloadType.PCMU) # or PCMA, L16, G722; Opus registers as PT 111
encoded = codec.encode(pcm_bytes)
decoded = codec.decode(encoded)
register_codec(96, MyCodec) # custom codecs: subclass aiortp.Codec
Low-Level Packets
from aiortp import RtpPacket, RtcpPacket, is_rtcp
# Parse
packet = RtpPacket.parse(data)
print(packet.sequence_number, packet.timestamp, packet.payload_type)
# Build
packet = RtpPacket(
payload_type=0,
sequence_number=1000,
timestamp=8000,
ssrc=0xDEADBEEF,
payload=b"\x80" * 160,
)
data = packet.serialize()
# Demux RTP vs RTCP
if is_rtcp(data):
rtcp_packets = RtcpPacket.parse(data)
Video Depacketizers (Standalone)
from aiortp import H264Depacketizer, VP8Depacketizer, VP9Depacketizer
# H.264: feed RTP payloads, get NAL units
depkt = H264Depacketizer()
nals = depkt.feed(rtp_payload, marker=is_last_packet)
# VP8/VP9: feed RTP payloads, get (frame_data, is_keyframe) tuples
depkt = VP8Depacketizer()
frames = depkt.feed(rtp_payload, marker=is_last_packet)
Examples
See the examples/ directory:
loopback.py— two sessions exchanging G.711 audio on localhostdtmf.py— sending and receiving DTMF digitscodec_roundtrip.py— encode/decode with each built-in codecraw_packets.py— low-level RTP/RTCP packet constructionsend_wav.py— stream a WAV file over RTP with paced sending
License
MIT. See LICENSE for details.
Metadata
Release files for aiortp 0.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aiortp-0.8.0.tar.gz | 82.8 kB | Without provenance | Details for aiortp-0.8.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aiortp-0.8.0-py3-none-any.whl | Python 3 | none | any | Details for aiortp-0.8.0-py3-none-any.whl |
Total release size: 140.7 kB
Release files / aiortp-0.8.0.tar.gz
| Download URL | aiortp-0.8.0.tar.gz |
|---|---|
| Size | 82.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7d335306710c6bdc48c3c765c0b68746a8307f09a7d5bf0d690382972ccf43f6
|
|
BLAKE2b-256 checksum How to use checksums |
5b8adb5a3050e41384641febd6fb40dabf7a53b98539c7cd0f6ea1698ae123a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / aiortp-0.8.0-py3-none-any.whl
| Download URL | aiortp-0.8.0-py3-none-any.whl |
|---|---|
| Size | 57.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9c2840b2ddcf5de923c2fade3ad2947245e8a891dff391244331318ca6f5c859
|
|
BLAKE2b-256 checksum How to use checksums |
d78173fc3ce665499a31341d43faf245893011c3822b42f982752f6eb0b82c09
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Security for aiortp 0.8.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.