webrtc_rtcp_sched (webrtc v0.1.0)

View Source

RTCP transmission scheduler of a media session: when regular reports go out (RFC 3550 §6.3 and Appendix A.7 with the RTP/AVPF rules of RFC 4585 §3.5) and whether feedback can be sent now under the RTCP bandwidth (RFC 4585 §3.5.2, RFC 8834 §5.1).

The interval itself comes from webrtc_rtcp_interval; this module keeps the scheduler state: the time of the last regular report (tp), the next one (tn), the average compound size, the membership counts and the feedback budget. It is a pure value: every call takes the current time in milliseconds and returns the new state.

  S0 = webrtc_rtcp_sched:new(Now, #{session_bandwidth => 2000000}),
  Deadline = webrtc_rtcp_sched:next_timeout(S0),
  %% at the deadline:
  case webrtc_rtcp_sched:expire(Now, S0) of
      {send, S1} -> %% build the compound, then
                    webrtc_rtcp_sched:regular_sent(Now, Size, S1);
      {wait, S1} -> S1
  end,
  %% feedback to send:
  case webrtc_rtcp_sched:feedback(Now, Size, S) of
      {now, S1} -> %% send it
      {later, S1} -> %% keep it; next_timeout/1 says when to retry
  end.

Regular reports. The first one goes out after the AVPF initial interval (Tmin 0 point to point, RFC 4585 §3.4 d), so the peer gets an RTT and loss report early. Later ones use the RFC 3550 interval computed from the RTCP bandwidth (5% of the session bandwidth), the membership and the average compound size, randomised and reconsidered at expiry (§6.3.6), and never closer than the local T_rr_interval (report_interval, RFC 4585 §3.5.3), dithered in [0.5, 1.5).

Feedback (NACK, PLI, FIR, transport-wide congestion control). AVPF point to point has no dithering (T_dither_max is 0, §3.5.2): feedback goes out at once while the budget allows. The budget refills at the RTCP bandwidth and holds one second of it (at least one full datagram). Feedback that does not fit waits until it does, instead of the next regular report as early mode would (§3.5.2 step 4): waiting a regular interval would make retransmission requests useless and starve congestion control.

Sizes passed in are the SRTCP datagram sizes; 28 octets of IPv4 and UDP header are added for the average (§6.3.3 counts lower layers).

Options of new/2:

  • session_bandwidth (bit/s, default 600000): both directions; the RTCP bandwidth is 5% of it.
  • report_interval (ms, default 1000, 0 for none): the local T_rr_interval, a floor on the regular interval.
  • members and senders (default 2 and 1).
  • uniform: a zero-arity fun returning a float in [0, 1), the randomisation source (default webrtc_rtcp_interval:uniform/0).

Summary

Functions

The regular report timer expired (Appendix A.7 OnExpire): send when the reconsidered interval since the last report has elapsed, otherwise wait with the timer moved.

Can a feedback packet of Size octets go out now? later sets the retry time returned by next_timeout/1.

The earliest time something is due: the next regular report or a feedback retry.

A regular compound of Size octets went out at Now.

New membership: Members participants, Senders of them sent RTP, WeSent when we did since the last report. When members leave, the timers move closer (reverse reconsideration, §6.3.4).

The session bandwidth changed (bit/s, both directions).

Types

state/0

-opaque state()

Functions

expire(Now, Sched)

-spec expire(integer(), state()) -> {send | wait, state()}.

The regular report timer expired (Appendix A.7 OnExpire): send when the reconsidered interval since the last report has elapsed, otherwise wait with the timer moved.

feedback(Now, Size, S0)

-spec feedback(integer(), non_neg_integer(), state()) -> {now | later, state()}.

Can a feedback packet of Size octets go out now? later sets the retry time returned by next_timeout/1.

info(Sched)

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

new(Now, Opts)

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

next_timeout(Sched)

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

The earliest time something is due: the next regular report or a feedback retry.

regular_sent(Now, Size, S0)

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

A regular compound of Size octets went out at Now.

set_membership(Now, Members, Senders, WeSent, Sched)

-spec set_membership(integer(), pos_integer(), non_neg_integer(), boolean(), state()) -> state().

New membership: Members participants, Senders of them sent RTP, WeSent when we did since the last report. When members leave, the timers move closer (reverse reconsideration, §6.3.4).

set_session_bandwidth(Bps, S)

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

The session bandwidth changed (bit/s, both directions).