Crate rtc_interceptor

Expand description

RTC Interceptor - Sans-IO interceptor framework for RTP/RTCP processing.

This crate provides a composable interceptor framework built on top of the sansio::Protocol trait. Interceptors can process, modify, or generate RTP/RTCP packets as they flow through the pipeline.

§Available Interceptors

§RTCP Reports

Interceptor	Description
`SenderReportInterceptor`	Generates RTCP Sender Reports (SR) for local streams and filters hop-by-hop RTCP feedback
`ReceiverReportInterceptor`	Generates RTCP Receiver Reports (RR) based on incoming RTP statistics

§NACK (Negative Acknowledgement)

Interceptor	Description
`NackGeneratorInterceptor`	Detects missing RTP packets and generates NACK requests (RFC 4585)
`NackResponderInterceptor`	Buffers sent packets and retransmits on NACK, with optional RTX support (RFC 4588)

§TWCC (Transport Wide Congestion Control)

Interceptor	Description
`TwccSenderInterceptor`	Adds transport-wide sequence numbers to outgoing RTP packets
`TwccReceiverInterceptor`	Tracks incoming packets and generates TransportLayerCC feedback

§Utility

Interceptor	Description
`NoopInterceptor`	Pass-through terminal for interceptor chains

§Design

Each interceptor wraps an inner Interceptor and can:

Process incoming/outgoing RTP/RTCP packets
Modify packet contents (headers, payloads)
Generate new packets (e.g., RTCP Sender/Receiver Reports)
Handle timeouts for periodic tasks (e.g., report generation)
Track stream statistics and state

All interceptors work with TaggedPacket (RTP or RTCP packets with transport metadata). The innermost interceptor is typically NoopInterceptor, which serves as the terminal.

§No Direction Concept

Important: Unlike PeerConnection’s pipeline where read and write have opposite processing direction orders, interceptors have no direction concept.

In PeerConnection’s pipeline:

Read:  Network → HandlerA → HandlerB → HandlerC → Application
Write: Application → HandlerC → HandlerB → HandlerA → Network
       (reversed order)

In Interceptor chains, all operations flow in the same direction:

handle_read:    Outer → Inner (A.handle_read calls B.handle_read calls C.handle_read)
handle_write:   Outer → Inner (A.handle_write calls B.handle_write calls C.handle_write)
handle_event:   Outer → Inner (A.handle_event calls B.handle_event calls C.handle_event)
handle_timeout: Outer → Inner (A.handle_timeout calls B.handle_timeout calls C.handle_timeout)

poll_read:    Outer → Inner (A.poll_read calls B.poll_read calls C.poll_read)
poll_write:   Outer → Inner (A.poll_write calls B.poll_write calls C.poll_write)
poll_event:   Outer → Inner (A.poll_event calls B.poll_event calls C.poll_event)
poll_timeout: Outer → Inner (A.poll_timeout calls B.poll_timeout calls C.poll_timeout)

This means interceptors are symmetric - they process read, write, and event in the same structural order. The distinction between “inbound” and “outbound” is semantic (based on message content), not structural (based on call order).

§Quick Start

use rtc_interceptor::{
    Registry, SenderReportBuilder, ReceiverReportBuilder,
    NackGeneratorBuilder, NackResponderBuilder,
    TwccSenderBuilder, TwccReceiverBuilder,
};
use std::time::Duration;

// Build a full-featured interceptor chain
let chain = Registry::new()
    // RTCP reports
    .with(SenderReportBuilder::new()
        .with_interval(Duration::from_secs(1))
        .build())
    .with(ReceiverReportBuilder::new()
        .with_interval(Duration::from_secs(1))
        .build())
    // NACK for packet loss recovery
    .with(NackGeneratorBuilder::new()
        .with_size(512)
        .with_interval(Duration::from_millis(100))
        .build())
    .with(NackResponderBuilder::new()
        .with_size(1024)
        .build())
    // TWCC for congestion control
    .with(TwccSenderBuilder::new().build())
    .with(TwccReceiverBuilder::new()
        .with_interval(Duration::from_millis(100))
        .build())
    .build();

§Stream Binding

Before interceptors can process packets for a stream, the stream must be bound:

use rtc_interceptor::{StreamInfo, RTCPFeedback, RTPHeaderExtension};

// Create stream info with NACK and TWCC support
let stream_info = StreamInfo {
    ssrc: 0x12345678,
    clock_rate: 90000,
    mime_type: "video/VP8".to_string(),
    payload_type: 96,
    rtcp_feedback: vec![RTCPFeedback {
        typ: "nack".to_string(),
        parameter: String::new(),
    }],
    rtp_header_extensions: vec![RTPHeaderExtension {
        uri: "http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01".to_string(),
        id: 5,
    }],
    ..Default::default()
};

// Bind for outgoing streams (sender side)
chain.bind_local_stream(&stream_info);

// Bind for incoming streams (receiver side)
chain.bind_remote_stream(&stream_info);

Structs§

NackGeneratorBuilder: Builder for the NackGeneratorInterceptor.
NackGeneratorInterceptor: Interceptor that generates NACK requests for missing RTP packets.
NackResponderBuilder: Builder for the NackResponderInterceptor.
NackResponderInterceptor: Interceptor that responds to NACK requests by retransmitting packets.
NoopInterceptor: A no-operation interceptor that simply queues messages for pass-through.
RTCPFeedback: RTCP feedback mechanism negotiated for the stream.
RTPHeaderExtension: RTP header extension as negotiated via SDP (RFC 5285).
ReceiverReportBuilder: Builder for the ReceiverReportInterceptor.
ReceiverReportInterceptor: Interceptor that generates RTCP Receiver Reports.
Registry: Registry for constructing interceptor chains.
SenderReportBuilder: Builder for the SenderReportInterceptor.
SenderReportInterceptor: Interceptor that filters hop-by-hop RTCP reports.
StreamInfo: Stream context passed to interceptor bind/unbind callbacks.
TwccReceiverBuilder: Builder for the TwccReceiverInterceptor.
TwccReceiverInterceptor: Interceptor that tracks incoming RTP packets and generates TWCC feedback.
TwccSenderBuilder: Builder for the TwccSenderInterceptor.
TwccSenderInterceptor: Interceptor that adds transport-wide sequence numbers to outgoing RTP packets.

Enums§

Packet: RTP/RTCP Packet

Traits§

Interceptor: Trait for RTP/RTCP interceptors with fixed Protocol type parameters.

Type Aliases§

TaggedPacket: Tagged packet with transport metadata.