Skip to main content

aiortp

CI

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=True emission 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 — PortAllocator for 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.typed marker 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 localhost
  • dtmf.py — sending and receiving DTMF digits
  • codec_roundtrip.py — encode/decode with each built-in codec
  • raw_packets.py — low-level RTP/RTCP packet construction
  • send_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)

Source distribution for aiortp 0.8.0
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)

Table of built distributions (wheels) for aiortp 0.8.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page