fix(webrtc): PLI rate limiting + bitrate cap + VBV units (closes #23)

Root causes (3, discovered via Oracle review + x264 source verification):

A. PLI storm: WebRtcInner.force_keyframe_to_encode is a single bool with
   no rate limit. Client PLI storms (5 PLIs in 845ms observed) produced
   5 back-to-back IDRs (~1.5MB burst), swamping the network.

B. Bitrate runaway: BWE feedback had no upper bound. Observed bitrate
   escalating from 5 Mbps to 9.9 Mbps in 12 seconds, all applied to
   encoder. Combined with A, made each IDR grow 4-5x.

C. VBV effectively disabled (NEW finding not in original issue):
   x264's vbv-maxrate and vbv-bufsize x264opts expect kbit/s and kbit
   (confirmed via x264 source ratecontrol.c:658-661 which multiplies by
   1000 at use site). The code passed bps, making VBV interpret 5.5 Mbps
   as 5.5 Gbps (clipped to 2 Gbps). Buffer was 173MB instead of 172KB,
   so VBV never constrained anything. This is why IDRs could balloon to
   336KB after runtime bitrate increases.

Fixes (3, all in this commit per Oracle review):

Fix 0 (avhw.rs): divide bitrate by 1000 when formatting x264opts string.
  Updated existing vbv_x264opts_format and vbv_bufsize_is_quarter_of_maxrate
  tests to assert correct kbit/s values. Old tests passed but asserted
  wrong values - classic 'tests covered the wrong implementation'.

Fix 1 (webrtc.rs): split keyframe trigger into two paths.
  - set_need_keyframe() (internal: connect, resolution change) remains
    unthrottled but updates last_forced_keyframe_at timestamp.
  - request_keyframe_from_viewer() (external PLI) rate-limited to
    Duration::from_secs(1), checked against last_forced_keyframe_at.
  - Key insight from Oracle: track ALL keyframe production time, not
    just PLI time, to prevent 'connect -> immediate PLI -> duplicate IDR'.

Fix 2 (args.rs + state_portal.rs + avhw.rs):
  - New --max-bitrate CLI flag, default 8 Mbps.
  - Primary clamp in webrtc_thread_loop (policy layer): clamp BWE via
    variable shadowing so all downstream code (bitrate_tx, resolution
    adaptation) uses clamped value.
  - Defensive guardrail in encode_cpu_frame UpdateBitrate handler:
    50 Mbps hard ceiling in case future callers bypass policy layer.
  - Per Oracle: flat 8 Mbps default, no auto-scaling
    (max(8M, 2*initial) would have failed the observed case).

Verification (82.1s session, 34.7 fps avg vs previous 18.2):

PLI storm absorption:
  - 15 PLIs received from viewer
  - 10 PLIs throttled (67%)
  - 6 IDRs produced total (1 connect + 5 honored)
  - 3 distinct PLI storms (625ms, 640ms, 858ms duration) all absorbed

VBV constraint working:
  - First IDR: 65KB (was 67KB)
  - Largest IDR: 169KB (was 336KB)
  - All IDRs under VBV buffer bound of 172KB
  - No more runaway IDR growth

Bitrate cap working:
  - 5 bitrate updates applied (was 8)
  - Peak bitrate: 7.4 Mbps (was 9.9 Mbps)
  - 52952 BWE readings clamped (>8 Mbps filtered out)

Overall quality:
  - Frame rate: 34.7 fps (was 18.2, 1.9x improvement, exceeds 30 fps target)
  - Average bitrate: 4451 kb/s (was 5616, lower and more stable)

Out of scope (deferred to future work):
  - Runtime VBV reconfiguration on bitrate change (Fix 3): encoder
    recreation is expensive, observe whether VBV mismatch becomes a
    quality issue after cap is in place
  - Asymmetric BWE filter (Fix 4): rise=15%/fall=5% thresholds; nice
    tuning but cap is sufficient for now
  - Compositor stalls (#15): still causes some stutter at session end
    but no longer compounds into latency

Tests:
  - cargo test: 91 passed + 3 passed + 0 failed
  - vbv_x264opts_format and vbv_bufsize_is_quarter_of_maxrate updated
    and passing with new kbit/s assertions
  - SAFETY comments preserved verbatim
  - cargo build --release: clean, no new warnings
This commit is contained in:
dailz
2026-06-20 20:36:44 +08:00
parent f38adf70f9
commit 9a522e2f99
7 changed files with 108 additions and 18 deletions
+1
View File
@@ -110,6 +110,7 @@ fn main() -> Result<()> {
hw_accel: "vaapi".to_string(),
drm_device: None,
bitrate: None,
max_bitrate: 8_000_000,
gop_size: None,
verbose: false,
backend: Some("portal".to_string()),
+1
View File
@@ -881,6 +881,7 @@ fn main() -> Result<()> {
hw_accel: "vaapi".to_string(),
drm_device: None,
bitrate: None,
max_bitrate: 8_000_000,
gop_size: None,
verbose: false,
backend: Some("portal".to_string()),