Cap video bitrate and report it to the server

[Karolk99]

Cap video bitrate and report it to the server

Fixes video freezes caused by the high simulcast layer running at ~6 Mbps while the SFU assumed 2.5 Mbps.

Changes

• Hard cap for video bandwidth. New MAX_BANDWIDTH_LIMITS (1500 kbps single stream, 150 / 500 / 1500 kbps for low / medium / high), exported from webrtc-client and ts-client.
• Every limit is resolved against the cap. addTrack, setTrackBandwidth and setEncodingBandwidth clamp values above the cap (with a console.warn) and treat 0 or a missing variant as "use the cap". Audio tracks are unaffected.
• Simulcast limits are no longer dropped. addTrack coerced a Map of per-variant limits to 0, so user-provided simulcast limits never reached the encoder.
• Real bitrates in the SDP offer. trackIdToBitrates now carries per-variant bitrates derived from the configured limits instead of a hardcoded 1.5 Mbps in the wrong field. setTrackBandwidth also sent kbps where the server expects bps; both setters now keep trackContext.maxBandwidth in sync.
• react-client defaults to the cap. bandwidthLimits fills missing values from MAX_BANDWIDTH_LIMITS; the simulcast prop is now Partial.

Breaking change

0 no longer means "unlimited" for video limits. It resolves to the cap.

Testing

• New unit tests for the clamp, the defaults and the reported bitrates.
• Verified on sandbox with fishjam-videoroom using 0.30.2-rc.0.

Documentation impact

• Documentation update required
• Documentation updated in another PR
• No documentation update required

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to
  not work as expected)

[linear]

FCE-3835

[Copilot]

🟡 Changes recommended

Unresolved moderate findings remain in simulcast limit handling, audio bandwidth behavior, and bitrate reporting.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR caps outgoing video bitrate and reports resolved per-track and per-layer limits to the server.

Changes:

• Adds centralized video bitrate caps and resolution.
• Preserves simulcast limits and updates bitrate reporting.
• Updates React defaults, types, documentation, and tests.

File summaries

File	Reviewed changes and final findings
packages/webrtc-client/tests/methods/bandwidthLimits.test.ts	Tests bitrate caps, defaults, and reporting.
packages/webrtc-client/tests/methods/addTrackMethod.test.ts	Tests simulcast bandwidth limits.
packages/webrtc-client/src/webRTCEndpoint.ts	Applies bandwidth resolution. Moderate findings: default simulcast limits resolve to an invalid numeric value, and audio limits are incorrectly capped. Nit: update stale public API documentation.
packages/webrtc-client/src/types.ts	Updates bandwidth-limit documentation.
packages/webrtc-client/src/tracks/Local.ts	Synchronizes bandwidth state. Moderate finding: setTrackBandwidth replaces simulcast per-variant limits with a scalar.
packages/webrtc-client/src/tracks/bitrates.ts	Builds reported bitrate metadata. Moderate finding: configured audio bandwidth is not reported after updates.
packages/webrtc-client/src/index.ts	Exports bitrate utilities. Nit: fix export formatting.
packages/webrtc-client/src/bitrate.ts	Defines bitrate caps and resolution helpers.
packages/react-client/src/utils/bandwidth.ts	Applies capped bandwidth defaults.
packages/react-client/src/utils/bandwidth.test.ts	Tests React bandwidth defaults.
packages/react-client/src/types/public.ts	Allows partial simulcast limits.
packages/react-client/src/FishjamProvider.tsx	Updates bandwidth configuration documentation.

Review details

Suppressed comments (1)

packages/webrtc-client/src/tracks/bitrates.ts:13

• This early audio return ignores trackContext.maxBandwidth, so after setTrackBandwidth changes an audio sender, the server is still told the fixed 50,000 bps default rather than the configured bitrate. Since the setter updates both the sender and the context, report the configured audio limit when one exists (or reject audio bandwidth changes consistently).

  if (kind === 'audio') return [{ variant: Variant.VARIANT_UNSPECIFIED, bitrate: defaultBitrates.audio }];

• Files reviewed: 12/12 changed files
• Comments generated: 5
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Audio bitrate reporting and stale public addTrack documentation remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (2)

packages/ts-client/src/FishjamClient.ts:669

• The new bandwidth-cap behavior also changes the contract of this class's addTrack, but its public addTrack JSDoc still describes 0 as unlimited and says maxBandwidth has no effect for simulcast. Update that documentation alongside these setter docs so the ts-client API does not advertise the old behavior.

   * Single-stream video is clamped to `MAX_BANDWIDTH_LIMITS.singleStream`. For simulcast video each variant is
   * clamped to `MAX_BANDWIDTH_LIMITS.simulcast[variant]` after the split. 0 means "use the cap(s)".

packages/webrtc-client/src/webRTCEndpoint.ts:470

• The new resolver changes video 0 from unlimited to a cap and now uses simulcast limits passed to addTrack, but the public addTrack documentation immediately above still says 0 is unlimited and that maxBandwidth has no effect for simulcast (the same stale contract remains in packages/ts-client/src/FishjamClient.ts). This contradicts the breaking behavior implemented here; update the public docs/default comment to describe the cap and per-variant Map semantics.

   * Applies the video caps to the limit passed to {@link addTrack}. Audio limits are ignored (0).
   * For a simulcast track 0 means "every layer at its cap"; a positive number is kept as-is and
   * rejected later, when the transceiver is created.

• Files reviewed: 24/24 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Unresolved moderate issues affect API compatibility, bitrate resolution, documentation, and shared workspace configuration.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (2)

packages/ts-client/src/FishjamClient.ts:675

• The FishjamClient.addTrack JSDoc at lines 579–580 still says 0 means unlimited and that maxBandwidth has no effect for simulcast, while this new TrackBandwidthLimit API relies on those rules. Update the ts-client addTrack documentation so published docs describe the cap/default behavior.

  public async setTrackBandwidth(trackId: string, bandwidth: TrackBandwidthLimit): Promise<boolean> {

packages/webrtc-client/src/webRTCEndpoint.ts:431

• The public addTrack JSDoc immediately above still describes the old threshold/0-unlimited behavior and says maxBandwidth has no effect for simulcast, but this new code now caps video and applies simulcast defaults. The generated API docs will contradict runtime behavior; update the addTrack contract (and its matching wrapper documentation).

    const resolvedMaxBandwidth = this.resolveInitialBandwidth(track, simulcastConfig, maxBandwidth);

• Files reviewed: 27/27 changed files
• Comments generated: 3
• Review effort level: Lite