webrtc_rtp (webrtc v0.1.0)

View Source

RTP packet codec (RFC 3550 §5.1).

decode/1 parses a packet into an #rtp{} record and validates the version, the CSRC list, the header extension length and the padding count (RFC 3550 §5.1, Appendix A.1). The header extension is kept raw as {Profile, Data}; decode/2 with #{extensions => parse} turns RFC 8285 extensions into [{Id, Data}]. encode/1 accepts both forms.

For forwarding, peek/1 reads the fixed header fields and rewrite/2 patches seq, timestamp, SSRC, payload type or marker in place without touching the rest of the packet.

classify/1 demultiplexes RTP and RTCP sharing one port by the second octet (RFC 5761 §4): values 192..223 are RTCP.

Sequence and timestamp arithmetic lives in webrtc_rtp_seq.

Summary

Functions

Classify a packet received on an rtcp-mux port. The second octet holds the RTCP packet type, which overlaps the RTP marker bit and payload type; RTCP types 192..223 map to RTP payload types 64..95, which RFC 5761 forbids when multiplexing.

Decode with options. #{extensions => parse} decodes RFC 8285 header extensions into a list of elements; a packet whose extension profile is not RFC 8285 keeps the raw form.

Encode a packet. An ext given as a list of elements is encoded with webrtc_rtp_ext:encode/1 (one-byte form when every element fits, two-byte form otherwise). Raises badarg on out of range fields, more than 15 CSRCs or an extension that is not a multiple of 4 bytes.

Return the RFC 8285 elements of a decoded packet.

Size of the RTP header (fixed part, CSRCs and extension) of an encoded packet, i.e. the offset of the payload.

Read the fixed header fields without decoding the packet.

Patch fixed header fields of an encoded packet in place. Only the first 12 octets are rewritten; CSRCs, extensions, payload and padding are copied unchanged.

Types

decode_error/0

-type decode_error() :: truncated | bad_version | bad_padding | bad_extension | {bad_extension, term()}.

header/0

-type header() ::
          #{marker := boolean(),
            pt := 0..127,
            seq := 0..65535,
            ts := 0..4294967295,
            ssrc := 0..4294967295}.

packet/0

-type packet() ::
          #rtp{version :: 2,
               padding :: 0..255,
               marker :: boolean(),
               pt :: 0..127,
               seq :: 0..65535,
               ts :: 0..4294967295,
               ssrc :: 0..4294967295,
               csrcs :: [0..4294967295],
               ext :: undefined | {Profile :: 0..65535, Data :: binary()} | [webrtc_rtp_ext:element()],
               payload :: binary()}.

rewrite/0

-type rewrite() ::
          #{marker => boolean(),
            pt => 0..127,
            seq => 0..65535,
            ts => 0..4294967295,
            ssrc => 0..4294967295}.

Functions

classify(_)

-spec classify(binary()) -> rtp | rtcp | unknown.

Classify a packet received on an rtcp-mux port. The second octet holds the RTCP packet type, which overlaps the RTP marker bit and payload type; RTCP types 192..223 map to RTP payload types 64..95, which RFC 5761 forbids when multiplexing.

decode(Bin)

-spec decode(binary()) -> {ok, packet()} | {error, decode_error()}.

decode(Bin, Opts)

-spec decode(binary(), #{extensions => raw | parse}) -> {ok, packet()} | {error, decode_error()}.

Decode with options. #{extensions => parse} decodes RFC 8285 header extensions into a list of elements; a packet whose extension profile is not RFC 8285 keeps the raw form.

encode(Rtp)

-spec encode(packet()) -> binary().

Encode a packet. An ext given as a list of elements is encoded with webrtc_rtp_ext:encode/1 (one-byte form when every element fits, two-byte form otherwise). Raises badarg on out of range fields, more than 15 CSRCs or an extension that is not a multiple of 4 bytes.

extensions(Rtp)

-spec extensions(packet()) -> {ok, [webrtc_rtp_ext:element()]} | {error, term()}.

Return the RFC 8285 elements of a decoded packet.

header_size(B)

-spec header_size(binary()) -> {ok, pos_integer()} | {error, decode_error()}.

Size of the RTP header (fixed part, CSRCs and extension) of an encoded packet, i.e. the offset of the payload.

is_rtcp(Bin)

-spec is_rtcp(binary()) -> boolean().

peek(B)

-spec peek(binary()) -> {ok, header()} | {error, truncated | bad_version}.

Read the fixed header fields without decoding the packet.

rewrite(B, Changes)

-spec rewrite(binary(), rewrite()) -> {ok, binary()} | {error, truncated | bad_version}.

Patch fixed header fields of an encoded packet in place. Only the first 12 octets are rewritten; CSRCs, extensions, payload and padding are copied unchanged.