webrtc_red (webrtc v0.1.0)

View Source

RTP payload for redundant data (RFC 2198).

A RED payload is a list of block headers, then the blocks in the same order. A redundant block's header has F = 1, its payload type, a 14-bit timestamp offset back from the packet's timestamp and a 10-bit length (4 bytes); the last header, the primary block's, has F = 0 and its payload type only (1 byte) (§3).

WebRTC uses it for audio redundancy (RFC 8854 §5.2) and to carry ULPFEC with the video it protects (RFC 5109 §14.2).

Summary

Functions

The blocks of a RED payload, oldest first, the primary last (offset 0). Headers that do not add up to the payload are an error.

A RED payload: redundant blocks, oldest first, then the primary block. Redundant blocks the header cannot describe (an offset or a length out of range, §3) are left out.

The RTP packets a RED packet carries: the primary with the packet's sequence number and marker, and the redundant blocks as the packets they repeat, the n-th before the primary taking sequence number seq - n (one block per earlier packet, as libwebrtc sends them). Blocks whose payload type Keep refuses are left out.

The same, with the sequence number of a redundant block given by SeqOf(Index, Count, Offset). A block carries no sequence number (§3): a sender may repeat an older packet than the previous one (GStreamer's distance), so the receiver finds it from the timestamp offset and the packet duration.

What a receiver delivers for a RED packet, given its history: the redundant blocks that repair a lost packet (before the RED packet, within the history, received neither under that sequence number nor that timestamp), then the primary.

Record a received packet in a receiver's history.

Types

block/0

-type block() :: {0..127, 0..16383, binary()}.

history/0

-type history() :: [{0..65535, non_neg_integer()}].

Functions

decode(Bin)

-spec decode(binary()) -> {ok, [block()]} | {error, term()}.

The blocks of a RED payload, oldest first, the primary last (offset 0). Headers that do not add up to the payload are an error.

encode(Redundant, _)

-spec encode([block()], {0..127, binary()}) -> binary().

A RED payload: redundant blocks, oldest first, then the primary block. Redundant blocks the header cannot describe (an offset or a length out of range, §3) are left out.

packets(Rtp, Blocks, Keep)

-spec packets(#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()},
              [block()],
              fun((0..127) -> boolean())) ->
                 [#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()}].

The RTP packets a RED packet carries: the primary with the packet's sequence number and marker, and the redundant blocks as the packets they repeat, the n-th before the primary taking sequence number seq - n (one block per earlier packet, as libwebrtc sends them). Blocks whose payload type Keep refuses are left out.

packets(Rtp, Blocks, Keep, SeqOf)

-spec packets(#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()},
              [block()],
              fun((0..127) -> boolean()),
              fun((pos_integer(), pos_integer(), 0..16383) -> 0..65535)) ->
                 [#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()}].

The same, with the sequence number of a redundant block given by SeqOf(Index, Count, Offset). A block carries no sequence number (§3): a sender may repeat an older packet than the previous one (GStreamer's distance), so the receiver finds it from the timestamp offset and the packet duration.

repair(Rtp, Blocks, Keep, History)

-spec repair(#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()},
             [block()],
             fun((0..127) -> boolean()),
             history()) ->
                {[#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()}],
                 [#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()}]}.

What a receiver delivers for a RED packet, given its history: the redundant blocks that repair a lost packet (before the RED packet, within the history, received neither under that sequence number nor that timestamp), then the primary.

A block carries no sequence number (§3), and a sender may repeat an older packet than the previous one (GStreamer's distance). The block is placed between the latest packet received before its timestamp and the RED packet, the gap spread evenly over the packets between them; without such a packet, the n-th block before the primary is the n-th packet before it (libwebrtc's layout).

seen(Seq, Ts, History)

-spec seen(0..65535, non_neg_integer(), history()) -> history().

Record a received packet in a receiver's history.