webrtc_cc (webrtc v0.1.0)
View SourceCongestion 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
-type event() :: webrtc_gcc:event() | webrtc_circuit_breaker:event().
-type rtcp_u32() :: 0..4294967295.
-opaque state()
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.
-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.
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.
-spec enqueue(webrtc_pacer:packet(), integer(), state()) -> {[term()], state()}.
{true, Reason} when a circuit breaker halted stream Key.
-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.
-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.
-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.
Congestion feedback from the peer: transport-wide feedback or REMB. Other packets are ignored.
-spec sent(term(), non_neg_integer(), integer(), state()) -> state().
A packet of stream Key left with Size bytes on the wire.
-spec sent_probe(term(), non_neg_integer(), integer(), pos_integer(), state()) -> state().
A probe padding packet of cluster Cluster left (see handle_timeout/2).
-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.
-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.
Change options at run time: pacing (false releases every queued packet), pacing_factor, min_bitrate, max_bitrate.
-spec target(state()) -> pos_integer().
-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.
A video packet left: with transport-wide feedback the first probes start (webrtc_cc_probe).