webrtc_gcc (webrtc v0.1.0)

View Source

Google Congestion Control (draft-ietf-rmcat-gcc-02), sender side, as a sans-IO engine.

Inputs:

  • feedback/3: per-packet results of transport-wide feedback (webrtc_twcc_sender:feedback/3). They drive the delay-based controller (webrtc_gcc_delay, webrtc_gcc_aimd) with the acknowledged rate over 500 ms of arrivals as R_hat, and the loss-based controller.
  • loss_report/3: the fraction lost of an RTCP receiver report, used by the loss-based controller while no transport-wide feedback has been received. With such a peer (RTP/AVPF without transport-cc, RFC 8834 §7.1) the first report seeds the estimate with the rate actually being sent, so a forwarded stream is not limited by the start guess; from then on the estimate is backed by input (pacing applies), drops on loss above 10% and, below 2% loss, never falls under the rate getting through.
  • probe_result/3: the bitrate a probe cluster got through, which the delay-based estimate takes unless over-use is detected.
  • remb/3: a receiver estimated maximum bitrate (draft-alvestrand-rmcat-remb), an upper bound of the estimate.
  • set_rtt/2: round-trip time from RTCP reports. Without it the RTT is estimated from feedback (send time of the newest packet reported to the feedback arrival).
  • sent/3: every packet sent, for the feedback timeout.

Loss-based controller (§6), run once at least 20 packets have been reported since the previous run (as libwebrtc does, so that a single loss in a small report does not count as 20%), or one second has passed. Only packets sent after the last decrease (of either controller) count: losses of packets sent at the old rate say nothing about the new one, and would cut the rate twice. Below 2% loss the estimate As_hat grows by 5%, and keeps growing by 5% per feedback report without loss until the next run (§6 runs the controller on every report); between 2% and 10% it is held at the current target, above 10% it becomes target x (1 - 0.5 p), at most once per 300 ms + RTT. The target is min(A_hat, As_hat, REMB), clamped to [min, max] bitrate.

Lack of feedback (RFC 8836 §2 item 10): when packets were sent but no feedback arrived for feedback_timeout ms (default 1500) after feedback had been flowing, the target is cut by 20%, once per timeout.

Output: target/1, and {bandwidth_estimate, Bps} events returned by every call that may change it, when the target moved by more than change_threshold (default 0.05) of the last reported value. No estimate is reported before the first feedback, receiver report or REMB.

Summary

Functions

The delay detector's signal: normal, overuse or underuse.

True once an estimate is backed by feedback (transport-wide feedback, receiver reports or REMB).

Fraction lost (0..255) of an RTCP report block for one of our streams. Ignored once transport-wide feedback drives the estimate.

Options: start_bitrate (default 300000), min_bitrate (30000), max_bitrate (50000000), startup_gain (1.5), change_threshold (0.05), feedback_timeout (1500).

The bitrate a probe cluster got through (webrtc_cc_probe): the delay-based estimate jumps to it, unless the detector sees over-use (libwebrtc's DelayBasedBwe does the same). The loss-based estimate is lifted to it too, as libwebrtc's SetSendBitrate does: a lower max_bitrate or a feedback timeout may have cut it.

Bits per second sent over the last second (0 before a full second).

Change the bitrate limits (min_bitrate, max_bitrate).

Types

event/0

-type event() :: {bandwidth_estimate, pos_integer()}.

state/0

-opaque state()

Functions

delay_state(Gcc)

-spec delay_state(state()) -> atom().

The delay detector's signal: normal, overuse or underuse.

feedback(Results, Now, G)

-spec feedback([webrtc_twcc_sender:result()], integer(), state()) -> {[event()], state()}.

handle_timeout(Now, G)

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

has_input(Gcc)

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

True once an estimate is backed by feedback (transport-wide feedback, receiver reports or REMB).

info(Gcc)

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

loss_report(Fraction, Now, Gcc)

-spec loss_report(0..255, integer(), state()) -> {[event()], state()}.

Fraction lost (0..255) of an RTCP report block for one of our streams. Ignored once transport-wide feedback drives the estimate.

new(Opts)

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

Options: start_bitrate (default 300000), min_bitrate (30000), max_bitrate (50000000), startup_gain (1.5), change_threshold (0.05), feedback_timeout (1500).

next_timeout(Gcc)

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

probe_result(Bps, Now, Gcc)

-spec probe_result(pos_integer(), integer(), state()) -> {[event()], state()}.

The bitrate a probe cluster got through (webrtc_cc_probe): the delay-based estimate jumps to it, unless the detector sees over-use (libwebrtc's DelayBasedBwe does the same). The loss-based estimate is lifted to it too, as libwebrtc's SetSendBitrate does: a lower max_bitrate or a feedback timeout may have cut it.

remb(Bps, Now, G)

-spec remb(non_neg_integer(), integer(), state()) -> {[event()], state()}.

sending_rate(Now, Gcc)

-spec sending_rate(integer(), state()) -> non_neg_integer().

Bits per second sent over the last second (0 before a full second).

sent(Size, Now, G)

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

set_limits(Opts, Gcc)

-spec set_limits(map(), state()) -> {[event()], state()}.

Change the bitrate limits (min_bitrate, max_bitrate).

set_rtt(Ms, G)

-spec set_rtt(non_neg_integer(), state()) -> state().

target(Gcc)

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