Encode and decode RTP Control Protocol (RTCP) packets.
What problem this solves
RTP carries media; RTCP carries session control: sender and receiver reports, source descriptions, BYE, and AVPF feedback such as NACK or PLI. An SFU or endpoint must parse compound RTCP from UDP and generate replies for loss recovery, bitrate hints, and diagnostics. This module maps wire bytes to typed structs and back, after SRTCP decryption when keys are available.
RTCP rides alongside RTP on the same UDP session (often the same port when RFC 5761 mux is enabled). Senders publish statistics; receivers report loss and jitter; both sides exchange source descriptions (CNAME) and session teardown (BYE). Feedback packets (NACK, PLI, FIR) support loss recovery and keyframe requests in video calls.
Wire format: each RTCP packet has a common header (version, type, length) and
a type-specific body. Multiple packets are concatenated into a compound
packet without extra framing; decode/1 walks the buffer recursively.
%XMediaLib.Rtcp{} wraps a list of decoded payload structs in :payloads.
When trailing bytes cannot be parsed (typical for SRTCP ciphertext), decode
sets :encrypted to the original binary and still returns {:ok, _}.
SRTCP decryption belongs in XMediaLib.Srtp before calling decode/1 on
plaintext RTCP.
RFCs
- RFC 3550 - RTCP common format, SR, RR, SDES, BYE, APP
- RFC 5761 - RTP and RTCP on one port
- RFC 3711 - SRTCP encryption
- RFC 2032 - FIR and NACK (H.261)
- RFC 3611 - RTCP XR
- RFC 4585 - RTP/AVPF feedback (NACK, PLI, SLI, RPSI, AFB)
- RFC 5450 - inter-arrival jitter
- RFC 5484 - SMPTE timecode
- draft-holmer-rmcat-transport-wide-cc-extensions
- transport-wide congestion control feedback (
Twcc, RTPFB fmt 15)
- transport-wide congestion control feedback (
- draft-alvestrand-rmcat-remb
- Receiver Estimated Maximum Bitrate (
Remb, PSFB AFB"REMB")
- Receiver Estimated Maximum Bitrate (
Summary
Functions
Decodes a compound RTCP packet (or SRTCP plaintext after XMediaLib.Srtp).
Decodes RFC 3550 BYE SSRC list and optional reason text.
Decodes RFC 3550 report blocks from SR/RR packet bodies.
Accumulator clause for decode_rblocks/2.
Decodes SDES items inside one chunk.
Decodes RFC 3550 SDES chunks into a list of keyword proplists.
Decodes RFC 3611 XR report blocks from an XR packet body.
Accumulator clause for decode_xrblocks/2.
Encodes %Rtcp{} or a single RTCP payload struct to binary.
Encodes RFC 3550 APP packet.
Encodes RFC 3550 BYE for ssrcs_list with optional message charlist.
Encodes RFC 2032 FIR for ssrc.
Encodes RFC 2032 legacy NACK for ssrc.
Encodes one %Rblock{} or equivalent tuple fields.
Encodes one report block from raw field values.
Encodes a list of %Rblock{} structs.
Encodes RFC 3550 Receiver Report with report_blocks.
Encodes RFC 3550 SDES compound from a list of item proplists.
Encodes one SDES item or chunk field.
Encodes one SDES chunk (keyword proplist) with 32-bit padding.
Encodes RFC 3550 Sender Report with report_blocks.
Encodes RFC 3611 Extended Report with xrblocks.
Encodes one %Xrblock{} or {type, ts, data} tuple.
Encodes one XR block; data length must be a multiple of four.
Encodes a list of %Xrblock{} structs.
Types
Functions
Decodes a compound RTCP packet (or SRTCP plaintext after XMediaLib.Srtp).
Returns {:ok, %Rtcp{}}. Unparsed trailing bytes set :encrypted on the struct.
Examples
iex> fir = %XMediaLib.Rtcp.Fir{ssrc: 4096}
iex> bin = XMediaLib.Rtcp.encode(fir)
iex> {:ok, %XMediaLib.Rtcp{payloads: [decoded]}} = XMediaLib.Rtcp.decode(bin)
iex> decoded.ssrc
4096Internal accumulator for decode/1; prefer the public decode/1 entry point.
Decodes RFC 3550 BYE SSRC list and optional reason text.
Decodes RFC 3550 report blocks from SR/RR packet bodies.
Returns {rblocks, padding} where padding is any unconsumed tail bytes.
Accumulator clause for decode_rblocks/2.
Decodes SDES items inside one chunk.
Returns {items, rest} when the chunk ends; recurses for known item types.
Handles a known AddPac CNAME quirk with extra padding.
Decodes RFC 3550 SDES chunks into a list of keyword proplists.
Decodes RFC 3611 XR report blocks from an XR packet body.
Accumulator clause for decode_xrblocks/2.
Encodes %Rtcp{} or a single RTCP payload struct to binary.
When :encrypted is set, returns that binary unchanged (already SRTCP).
Examples
iex> bye = %XMediaLib.Rtcp.Bye{ssrc: [1, 2], message: ~c"done"}
iex> bin = XMediaLib.Rtcp.encode(bye)
iex> {:ok, rtcp} = XMediaLib.Rtcp.decode(bin)
iex> [decoded] = rtcp.payloads
iex> decoded.ssrc
[1, 2]Encodes RFC 3550 APP packet.
name must be exactly four bytes; data length must be a multiple of four.
Returns binary or {:error, :bad_data}.
Encodes RFC 3550 BYE for ssrcs_list with optional message charlist.
Encodes RFC 2032 FIR for ssrc.
Encodes RFC 2032 legacy NACK for ssrc.
Encodes one %Rblock{} or equivalent tuple fields.
Encodes one report block from raw field values.
Encodes a list of %Rblock{} structs.
Encodes RFC 3550 Receiver Report with report_blocks.
Encodes RFC 3550 SDES compound from a list of item proplists.
Encodes one SDES item or chunk field.
Accepts :ssrc, :cname, :name, :email, :phone, :loc, :tool,
:note, :priv, :eof, or a raw type octet with binary value.
Encodes one SDES chunk (keyword proplist) with 32-bit padding.
Encodes RFC 3550 Sender Report with report_blocks.
Encodes RFC 3611 Extended Report with xrblocks.
Encodes one %Xrblock{} or {type, ts, data} tuple.
Encodes one XR block; data length must be a multiple of four.
Encodes a list of %Xrblock{} structs.