feat(realtime): scale uplink maxBitrate with publish fps below 15 fps

[eilon-decart]

What

getDefaultVideoPublishOptions derives the uplink maxBitrate from the intended publish fps instead of using the static 3.5M cap, engaging only below 15 fps:

declared fps	maxBitrate	bits/frame	change
30 (all registry models today)	3.5M	~117kbit	none — byte-identical
≥15	3.5M	≤233kbit	none
10	2.0M	200kbit	new
≤5	1.0M floor	—	new

The fps is threaded from prepareBrowserConnection (which already receives resolveFpsNumber(model.fps) for the mirror canvas) into the media-channel factory. React-native path unchanged (no publishFps → natural rate).

Why

Chrome's encoder spends its per-second budget regardless of cadence, so a 10 fps publisher packs ~3× the bytes into every frame (44KB vs 14KB). Those frames' wire-arrival span inflates the server's ingest jitter buffer — measured +98ms at 10 fps on a clean path. Scaling to ~200kbit/frame restores full 30 fps-parity:

10 fps arm (GCP us-east4 → us-east-1 SFU → usw2 test-pool)	ingest hold p50	server residency	e2e p50	uplink QP
default 3.5M (today)	129.7	505	660	14.2
capped 2.0M (this PR)	28.4	403 (= 30fps parity)	557	18.1

Full causal A/B (19 sessions, size vs interval decomposition, dose–response, both IL and us-east4 clients): DecartAI/api → experiments/2026-07-28-livekit-size-vs-interval-jb/ (branch eilon/feature/lk-input-latency).

Guardrail evidence baked into the constants: at ≥15 fps a binding cap measurably hurts (rate-controller churn, +32ms), and very low caps hit the simulcast layer-starvation cliff — hence the 15 fps threshold and the 1M floor.

Tests

• tests/publish-options.unit.test.ts — 6 new unit tests (threshold, scaling, floor, natural-rate ceiling, omitted-fps fallback), all green.
• pnpm typecheck / suite: the pre-existing frame-metadata-diagnostics.ts typecheck error and the msw unit.test.ts env failure exist identically on origin/main — not introduced here (verified via stash A/B).

Follow-up (separate PR)

This covers declared low-fps models. Users whose camera actually delivers <15 fps while the model declares 30 need the measured-fps adaptive loop (sender.getStats() → live setParameters re-apply with hysteresis) — mechanism already validated by the probe's cap loop.

Linear (Platform team): PLA-660

---

Note

Medium Risk
Touches realtime uplink encoding for all browser sessions where fps is passed, but the scaling gate limits behavior change to declared fps below 15 fps; default registry paths remain unchanged.

Overview
Low-fps models now get a dynamic uplink maxBitrate instead of the fixed 3.5M cap. getDefaultVideoPublishOptions scales toward ~200 kbit/frame when declared publish fps is below 15, with a 1M floor and the existing codec ceiling; at ≥15 fps or when fps is omitted, behavior stays byte-identical to today.

Browser setup passes the model’s intended publishFps from prepareBrowserConnection into createLiveKitMediaChannel, so LiveKit publish options reflect declared cadence. New REALTIME_CONFIG.livekit knobs document the threshold and scaling constants.

Tests: publish-options.unit.test.ts covers threshold, scaling, floor, ceiling, and omitted-fps fallback.

^{Reviewed by Cursor Bugbot for commit 87b18b6. Bugbot is set up for automated code reviews on this repo. Configure here.}