Fix initial video quality blurriness for all codecs by xianshijing-lk · Pull Request #1987 · livekit/client-sdk-js

xianshijing-lk · 2026-06-29T08:21:05Z

Summary

Improve initial video quality by:

Capping x-google-start-bitrate at 1 Mbps to prevent BWE from starting too aggressively on high bitrate tracks
Setting source-based degradationPreference defaults for optimal quality per use case

Changes

PCTransport.ts

Added 1 Mbps cap on x-google-start-bitrate: min(target * 0.9, 1000 kbps)
Prevents bandwidth estimator from overwhelming the network on high bitrate tracks (e.g., 4K video)

publishUtils.ts

Updated getDefaultDegradationPreference() to return defaults based on track source:
- Camera: maintain-framerate (smoother video for real-time communication)
- Screen share: maintain-resolution (clarity is critical for text/UI)
- Other/unknown: balanced

options.ts

Updated documentation for degradationPreference option

Behavior
│ Setting │ Before │ After │
│ x-google-start-bitrate │ 90% of target (unbounded) │ min(90% of target, 1 Mbps) │
│ Camera degradationPreference │ maintain-resolution │ maintain-framerate │
│ Screen share degradationPreference │ maintain-resolution │ maintain-resolution │
│ Other degradationPreference │ maintain-resolution │ balanced │

await element to be attached before calling .play on it #1197 - Fix initial video quality blurriness for all codecs
Ensure SVC layers are starting from LOW quality #1226 - fix x-google-start-bitrate and make it adaptive to network

See Rust PR: livekit/rust-sdks#1197

changeset-bot · 2026-06-29T08:21:14Z

⚠️ No Changeset found

Latest commit: 7029ee9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2026-06-29T08:22:57Z

size-limit report 📦

Path	Size
dist/livekit-client.esm.mjs	101.49 KB (+0.01% 🔺)
dist/livekit-client.umd.js	110.44 KB (+0.07% 🔺)

lukasIO · 2026-07-16T08:30:23Z

-          });
+        } else if (track.codec && isVideoCodec(track.codec)) {
+          // Apply start bitrate for all video codecs to prevent initial blurriness.
+          // Sum all encoding bitrates for simulcast (BWE needs to handle all layers combined).


don't we need to differentiate between SVC and non SVC here? (i.e. keeping it with first encoding only for SVC and summing for the others?)

Theoretically yes, technically no.

For modern SVC ((Chrome M113+), they are single encoding with scalability mode, so it is fine.
for legacy SVC (Safari/RN/older Chrome): they have multiple encodings describing SVC layers. Summing the value might go beyond the target max bitrate. But given

1 Mbps cap - We cap at 1 Mbps anyway, so overcounting is limited

Higher is safer - Starting slightly high is better than too low (which causes blurriness)

Legacy SVC is rare - Modern Chrome uses single encoding; mainly Safari/RN use legacy

I fixed the code anyway.

…-bitrate libwebrtc starts every new video send stream at roughly 300 kbps and ramps up from there regardless of the encodings' maxBitrate, so the first seconds of a published track are visibly blurry (measured: QP 39-42 for ~12 s, the 2.3 Mbps ceiling reached only after ~30 s on a healthy network). Match what client-sdk-js (livekit/client-sdk-js#1987) and rust-sdks (livekit/rust-sdks#1197, #1226) already do: when a video sender is added, derive a start bitrate from its encodings — the sum of the active layers' maxBitrate, times 0.9, capped at 1 Mbps unless the track is a screen share, and no hint under 300 kbps — and declare `x-google-start-bitrate=<kbps>` on every video codec's fmtp (VP8/VP9/AV1/H264/H265) of that sender's section in the publisher's offer, matched through the `a=msid` track id. Not opt-in and no public API, as in the sibling SDKs. - `SDPMediaSection.setFmtpParameter(_:value:forPayload:)`: replaces an existing value, appends to an existing fmtp line, or inserts one for payloads that have none (VP8), keeping every other parameter verbatim. - `Transport.startBitrateKbps(targetBps:isScreenShare:)` / `startBitrateKbps(for:isScreenShare:)`: the shared formula. - `Transport.mungeVideoStartBitrate(_:kbpsBySenderId:)`, appended as the last (optional) munge of `set(localDescription:munging:)` (livekit#1068) in both single- and dual-PC negotiation, on the SDP module from livekit#1078. - `Transport.addTransceiver(with:transceiverInit:startBitrateKbps:)` records the hint against the new sender before returning, so the offer libwebrtc requests in response cannot be created without it; `remove(track:)` clears it. Both `LocalParticipant` video publish paths (primary and backup codec) pass the derived value. Tests: the formula, the encodings sum, the per-sender munge (codec case, replace/append/insert, rtx/audio/unmapped sections untouched, no-op identity), `setFmtpParameter`, and — against the shipped libwebrtc — that a send-only video section's msid carries the sender id and that the munged offer is accepted by `setLocalDescription` rather than rejected as disallowed munging. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…-bitrate libwebrtc starts every new video send stream at roughly 300 kbps and ramps up from there regardless of the encodings' maxBitrate, so the first seconds of a published track are visibly blurry (measured: QP 39-42 for ~12 s, the 2.3 Mbps ceiling reached only after ~30 s on a healthy network). Match what client-sdk-js (livekit/client-sdk-js#1987) and rust-sdks (livekit/rust-sdks#1197, #1226) already do: when a video sender is added, derive a start bitrate from its encodings — the sum of the active layers' maxBitrate, times 0.9, capped at 1 Mbps unless the track is a screen share, and no hint under 300 kbps — and declare `x-google-start-bitrate=<kbps>` on every video codec's fmtp (VP8/VP9/AV1/H264/H265) of that sender's section in the publisher's offer, matched through the `a=msid` track id. Not opt-in and no public API, as in the sibling SDKs. - `SDPMediaSection.setFmtpParameter(_:value:forPayload:)`: replaces an existing value, appends to an existing fmtp line, or inserts one for payloads that have none (VP8), keeping every other parameter verbatim. - `Transport.startBitrateKbps(targetBps:isScreenShare:)` / `startBitrateKbps(for:isScreenShare:)`: the shared formula. - `Transport.mungeVideoStartBitrate(_:kbpsBySenderId:)`, appended as the last (optional) munge of `set(localDescription:munging:)` (livekit#1068) in both single- and dual-PC negotiation, on the SDP module from livekit#1078. - `Transport.addTransceiver(with:transceiverInit:startBitrateKbps:)` records the hint against the new sender before returning, so the offer libwebrtc requests in response cannot be created without it; `remove(track:)` clears it. Both `LocalParticipant` video publish paths (primary and backup codec) pass the derived value. - The backup-codec publish path now computes its encodings with `isScreenShare`, as the primary path does; it had defaulted to the camera encoding since livekit#275, which the screen-share branch of the new formula made visible. Tests: the formula, the encodings sum, the per-sender munge (codec case, replace/append/insert, rtx/audio/unmapped sections untouched, no-op identity), `setFmtpParameter`, the backup codec's screen-share encodings, and — against the shipped libwebrtc — that a send-only video section's msid carries the sender id and that the munged offer is accepted by `setLocalDescription` rather than rejected as disallowed munging. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Fix initial video quality blurriness for all codecs

4618499

xianshijing-lk requested review from 1egoman and lukasIO as code owners June 29, 2026 08:21

lukasIO reviewed Jun 29, 2026

View reviewed changes

Comment thread src/room/PCTransport.ts Outdated

cloudwebrtc mentioned this pull request Jun 29, 2026

chore: Set default video degradation preference to maintain-resolution. #1986

Closed

update the start bitrate multiplier to 0.9 and added comment

ec093c1

lukasIO approved these changes Jun 30, 2026

View reviewed changes

update the PR to match Rust behaviors

279a137

This comment was marked as resolved.

Sign in to view

use the sum of target maxBitrate of all the codec layers

d1403cb

lukasIO reviewed Jul 16, 2026

View reviewed changes

xianshijing-lk added 4 commits July 17, 2026 16:53

addressed the comment

3e563c7

fix the style

f931f79

added fmtp fix

315ab09

remove the 1mbps cap for screen sharing

7029ee9

xianshijing-lk merged commit 5db17af into main Jul 18, 2026
9 checks passed

xianshijing-lk deleted the sxian/CLT-3068/fix-initial-video-quality-blurriness-by-setting-x-google-start-bitrate branch July 18, 2026 01:34

adrian-niculescu mentioned this pull request Jul 21, 2026

fix: improve initial video quality by setting x-google-start-bitrate for all video codecs livekit/client-sdk-android#973

Open

5 tasks

xianshijing-lk mentioned this pull request Aug 21, 2026

H.264 excluded from x-google-start-bitrate SDP fix (PR #1740) #1816

Open

xianshijing-lk mentioned this pull request Sep 12, 2026

Start published video at 90% of its target bitrate (x-google-start-bitrate) livekit/client-sdk-swift#1121

Open

xianshijing-lk mentioned this pull request Sep 14, 2026

Write the video start bitrate hint as one connection-level value, once #2102

Open

Navigation Menu

Uh oh!

Fix initial video quality blurriness for all codecs - #1987

Fix initial video quality blurriness for all codecs#1987
xianshijing-lk merged 8 commits into
mainfrom
sxian/CLT-3068/fix-initial-video-quality-blurriness-by-setting-x-google-start-bitrate

xianshijing-lk commented Jun 29, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jun 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 29, 2026 •

edited

Loading

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

lukasIO Jul 16, 2026

Uh oh!

xianshijing-lk Jul 17, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

xianshijing-lk commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

size-limit report 📦

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

lukasIO Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

xianshijing-lk Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

xianshijing-lk commented Jun 29, 2026 •

edited

Loading

changeset-bot Bot commented Jun 29, 2026 •

edited

Loading

github-actions Bot commented Jun 29, 2026 •

edited

Loading