webrtc_cc (webrtc v0.1.0)

View Source

Congestion control of one media session, as a sans-IO engine: transport-wide sequence numbers and feedback (webrtc_twcc_sender, webrtc_twcc_receiver), the bandwidth estimate (webrtc_gcc), the pacer (webrtc_pacer) and the RTP circuit breakers (webrtc_circuit_breaker). webrtc_media drives it.

Send path: enqueue/3 takes {Class, Size, Data} and returns the Data that may leave now; handle_timeout/2 returns the rest when the pacer allows. For each packet that leaves, the caller puts twcc_seq/1 (when not undefined) in the transport-wide-cc header extension, then calls sent/4 with the wire size.

Pacing applies once the estimate is backed by feedback (transport-wide feedback or REMB): before that, or when the peer gives no feedback at all, the target is a guess and packets are not held back. The pacing rate is pacing_factor x target. Retransmissions are limited to the target bitrate over one second, as libwebrtc does: after a sudden capacity drop, NACKs for everything lost would otherwise keep the bottleneck overloaded. Retransmissions over the limit are dropped and counted (rtx_limited).

Events: {bandwidth_estimate, Bps} and {circuit_breaker, Key, Reason}.

Circuit breakers (RFC 8083, mandatory in WebRTC per RFC 8834 §7.1): the RTCP and media timeout breakers halt their stream (§4.5, the sender ceases transmission): halted/2 tells the media session to stop sending RTP on it. The congestion breaker first cuts the target to a tenth of the rate being sent, as §4.3 allows, and re-arms; if it triggers again over the next CB_INTERVAL the stream is halted. The cut is lifted once circuit_breaker_hold ms pass without a new trigger. It is not restarted automatically; resume/3 restarts it, no sooner than circuit_breaker_hold ms (default 15000, the RTCP timeout interval) after it tripped, so a retry loop cannot keep overloading the path (RFC 8083 §4.5, RFC 8084).

Probing (webrtc_cc_probe): with transport-wide feedback, the first video packet starts probe clusters of padding packets ahead of the estimate; their results lift it at once instead of the slow startup ramp. Later it probes again while media is application limited, after a large drop once the path recovers, and on a raised max_bitrate.

Options (all optional): pacing (default true), probing (default true), pacing_factor (2.5), burst_ms (10), max_queue_packets (1000), max_queue_ms (1000), twcc_interval (100), rtcp_timeout (15000), circuit_breaker_hold (15000), and the webrtc_gcc options start_bitrate, min_bitrate, max_bitrate, startup_gain, change_threshold, feedback_timeout.

Summary

Functions

A packet carrying transport-wide sequence number Seq arrived.

The peer's RTP packet Ssrc/Seq arrived with ECN codepoint Ecn, for RFC 8888 feedback.

Whether the peer reports on our packets with RFC 8888 feedback.

Turn transport-wide CC on for sending (the peer accepts the extension) and for receiving (we offered it), sender_ssrc being the SSRC our feedback is sent from.

Whether RTP should go out ECT(0): RFC 8888 feedback reports the marks, the socket can set them, and the path did not clear them.

{true, Reason} when a circuit breaker halted stream Key.

Returns the packets the pacer releases, followed by the probe padding packets due ({probe, Cluster, Size}: send one padding packet of that size and report it with sent_probe/5), the transport-wide feedback to send and events.

A report block about stream Key, with the round-trip time in milliseconds when it could be computed.

Restart a stream halted by a circuit breaker, once the hold time has passed.

Congestion feedback from the peer: transport-wide feedback or REMB. Other packets are ignored.

A packet of stream Key left with Size bytes on the wire.

A probe padding packet of cluster Cluster left (see handle_timeout/2).

The same, with the probe packet's SSRC and sequence number for RFC 8888 feedback.

RTP packet Ssrc/Seq of stream Key left with Size bytes: sent/4, and kept for RFC 8888 feedback when that is negotiated.

Change options at run time: pacing (false releases every queued packet), pacing_factor, min_bitrate, max_bitrate.

The transport-wide sequence number for the next packet that leaves, undefined when the extension is not negotiated.

A video packet left: with transport-wide feedback the first probes start (webrtc_cc_probe).

Types

event/0

rtcp_u32/0

-type rtcp_u32() :: 0..4294967295.

state/0

-opaque state()

Functions

arrival(Seq, Ssrc, Now, Cc)

-spec arrival(0..65535, 0..4294967295, integer(), state()) -> state().

A packet carrying transport-wide sequence number Seq arrived.

ccfb_arrival(Ssrc, Seq, Ecn, Now, Cc)

-spec ccfb_arrival(0..4294967295, 0..65535, 0..3, integer(), state()) -> state().

The peer's RTP packet Ssrc/Seq arrived with ECN codepoint Ecn, for RFC 8888 feedback.

ccfb_send(Cc)

-spec ccfb_send(state()) -> boolean().

Whether the peer reports on our packets with RFC 8888 feedback.

configure(Opts, Cc0)

-spec configure(#{twcc_send := boolean(),
                  twcc_recv := boolean(),
                  sender_ssrc := 0..4294967295,
                  ccfb => boolean(),
                  ecn => boolean()},
                state()) ->
                   state().

Turn transport-wide CC on for sending (the peer accepts the extension) and for receiving (we offered it), sender_ssrc being the SSRC our feedback is sent from.

ecn_mark(Cc)

-spec ecn_mark(state()) -> boolean().

Whether RTP should go out ECT(0): RFC 8888 feedback reports the marks, the socket can set them, and the path did not clear them.

enqueue(Pkt, Now, Cc)

-spec enqueue(webrtc_pacer:packet(), integer(), state()) -> {[term()], state()}.

halted(Key, Cc)

-spec halted(term(), state()) -> false | {true, atom()}.

{true, Reason} when a circuit breaker halted stream Key.

handle_timeout(Now, Cc000)

-spec handle_timeout(integer(), state()) ->
                        {[term()],
                         [#rtcp_twcc{sender_ssrc :: rtcp_u32(),
                                     media_ssrc :: rtcp_u32(),
                                     base_seq :: 0..65535,
                                     ref_time :: -8388608..8388607,
                                     fb_count :: 0..255,
                                     packets :: [{0..65535, not_received | -32768..32767}]}],
                         [event()],
                         state()}.

Returns the packets the pacer releases, followed by the probe padding packets due ({probe, Cluster, Size}: send one padding packet of that size and report it with sent_probe/5), the transport-wide feedback to send and events.

new(Opts)

-spec new(map()) -> state().

next_timeout(Cc)

-spec next_timeout(state()) -> integer() | infinity.

report(Key, Rtcp_rb, Rtt, Now, Cc0)

-spec report(term(),
             #rtcp_rb{ssrc :: rtcp_u32(),
                      fraction_lost :: 0..255,
                      lost :: -8388608..8388607,
                      ext_seq :: rtcp_u32(),
                      jitter :: rtcp_u32(),
                      lsr :: rtcp_u32(),
                      dlsr :: rtcp_u32()},
             non_neg_integer() | undefined,
             integer(),
             state()) ->
                {[event()], state()}.

A report block about stream Key, with the round-trip time in milliseconds when it could be computed.

resume(Key, Now, Cc)

-spec resume(term(), integer(), state()) ->
                {ok, state()} | {error, not_halted | {retry_after, pos_integer()}}.

Restart a stream halted by a circuit breaker, once the hold time has passed.

rtcp(Rtcp_twcc, Now, Cc)

-spec rtcp(term(), integer(), state()) -> {[event()], state()}.

Congestion feedback from the peer: transport-wide feedback or REMB. Other packets are ignored.

sent(Key, Size, Now, Cc)

-spec sent(term(), non_neg_integer(), integer(), state()) -> state().

A packet of stream Key left with Size bytes on the wire.

sent_probe(Key, Size, Now, Cluster, Cc)

-spec sent_probe(term(), non_neg_integer(), integer(), pos_integer(), state()) -> state().

A probe padding packet of cluster Cluster left (see handle_timeout/2).

sent_probe_rtp(Key, Ssrc, Seq, Size, Now, Cluster, Cc)

-spec sent_probe_rtp(term(),
                     0..4294967295,
                     0..65535,
                     non_neg_integer(),
                     integer(),
                     pos_integer(),
                     state()) ->
                        state().

The same, with the probe packet's SSRC and sequence number for RFC 8888 feedback.

sent_rtp(Key, Ssrc, Seq, Size, Now, Cc)

-spec sent_rtp(term(), 0..4294967295, 0..65535, non_neg_integer(), integer(), state()) -> state().

RTP packet Ssrc/Seq of stream Key left with Size bytes: sent/4, and kept for RFC 8888 feedback when that is negotiated.

set_options(Opts, Now, Cc0)

-spec set_options(map(), integer(), state()) -> {[term()], [event()], state()}.

Change options at run time: pacing (false releases every queued packet), pacing_factor, min_bitrate, max_bitrate.

stats(Cc)

-spec stats(state()) -> map().

target(Cc)

-spec target(state()) -> pos_integer().

twcc_seq(Cc)

-spec twcc_seq(state()) -> 0..65535 | undefined.

The transport-wide sequence number for the next packet that leaves, undefined when the extension is not negotiated.

video_sent(Now, Cc)

-spec video_sent(integer(), state()) -> state().

A video packet left: with transport-wide feedback the first probes start (webrtc_cc_probe).