Skip to content

fix: use prepared publications during Session startup (CLT-3610) - #1523

Open
xianshijing-lk wants to merge 3 commits into
mainfrom
sxian/CLT-3610/fast-track-publication-session-api
Open

xianshijing-lk wants to merge 3 commits into
mainfrom
sxian/CLT-3610/fast-track-publication-session-api

Conversation

@xianshijing-lk

@xianshijing-lk xianshijing-lk commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

What and why

CLT-3610. Use the device-free publication preparation API from livekit/client-sdk-js#2292 during useSession().start(), so credential acquisition and JOIN proceed independently of microphone/camera initialization. Late capture can attach to a sender already negotiated in JOIN.

The public Session API and startup options remain unchanged. The helper derives microphone publication intent from existing publish options, and camera dimensions/frame rate from the room's configured capture resolution. Codec, encoding, simulcast and audio settings continue to come from existing publication/room defaults. It never opens a device to discover publication configuration before JOIN.

  • Invoke connection work first, then acquire requested media in parallel and bind each prepared handle. Existing microphone preconnect-buffer behavior is handled by the SDK reservation.
  • Detect the optional SDK method at runtime: existing supported SDK versions keep their ordinary enable-track path, without raising the peer dependency floor before the companion API is released. The SDK owns single-PC/browser/server fallback decisions.
  • Preserve the existing screen-share gesture path and any caller-supplied initial publication handles.
  • Own startup cancellation across end(), abort, unmount and disconnection; stop media that arrives after cancellation and cancel unused reservations. Remove startup/disconnect listeners on their lifecycle boundaries. Failed startup disconnects and cleans up acquired media.

Validation

  • React suite: 46 tests passed against both the workspace's current SDK dependency and the locally built companion SDK. New tests cover join-before-capture ordering, microphone publication options, declared camera configuration, cancellation, late capture after join failure, permission/publication errors, disabled sources, and older SDK fallback, and late credentials after a failed startup.
  • TypeScript passed with both SDKs; React build and API Extractor compatibility checks passed. Lint completed with warnings and no errors.
  • Real Chrome 158 and LiveKit server 1.13.10, using this production helper and an agent peer: JOIN completes before delayed capture; the agent receives real microphone audio and decoded camera video. When capture completes before JOIN, the agent also receives 4,884 bytes of preconnect audio and the buffer stream closes on subscription. Attachment emits no AddTrack/offer once capture and connection are ready; initial transport setup can independently negotiate before then.

Reproduce the real-browser cases with scripts/test-session-publication.mjs; prerequisites and commands are in scripts/README.md. The companion SDK PR contains the signaling-latency benchmark (roughly 150 ms to 2–4 ms after capture with 100 ms injected signaling RTT) and the real dual-PC/server-codec fallback matrix.

This can be reviewed independently and continues to work with older SDK releases. The startup performance improvement becomes available when applications adopt the companion SDK release.

Session UX benchmark

A separate feature A/B measures the actual React Session hook and UI with a real SFU. Across 100 measured runs (ten per variant per scenario, plus ten excluded warmups), the user's signaling and ICE/DTLS/media pass through latency relays. The warm fixture agent connects directly to the SFU. Both variants use the same SDK build, isolating the old versus prepared Session flow.

P50 seconds from the Connect click, existing → prepared, at 150 ms network RTT:

Case Connected UI Microphone-ready UI First greeting audio ready
Fast capture 0.446 → 0.445 0.468 → 0.453 0.523 → 0.530
+800 ms capture 0.443 → 0.442 1.114 → 0.908 1.161 → 0.538
+2 s capture/permission 0.451 → 0.451 2.320 → 2.112 2.368 → 0.528

The first response proxy improves 1.265 → 1.138 s in the 800 ms case and 2.472 → 2.310 s in the two-second case. Fast capture and one-second credentials show little meaningful median gain: normal publication overlaps transport setup. The credential stage remains 1.004 s in both variants.

The main perceived benefit is an early welcome while device access is pending. JOIN publisher intent can make the remote participant visible before capture, interacting with the SFU's subscriber-only update batching. This greeting gain is not purely a two-RTT saving and depends on the agent's greeting policy. The existing session.isConnected state can render Connected early; an app awaiting all of start() still waits for its devices.

Full report, reproduction, p95s and all 100 raw samples. Audio measurements use real decoded waveforms as a playout proxy; these are controlled Chrome/warm-agent results, with no production authentication, page-load, agent cold-start, STT/LLM/TTS or physical-speaker measurement.

AI assistance: Codex.

@vercel

vercel Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
components-js-storybook-5kld Ready Ready Preview Nov 21, 2026 12:36am UTC

Request Review

@github-actions

Copy link
Copy Markdown
Contributor

This PR bumps

  • @livekit/components-react: patch

Also bumped

  • @livekit/agents-ui: depends on @livekit/components-react
  • @livekit/components-js-docs: depends on @livekit/components-react

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

size-limit report 📦

Path Size
LiveKitRoom only 7.88 KB (0%)
LiveKitRoom with VideoConference 32.63 KB (+0.01% 🔺)
All exports 44.99 KB (+1.34% 🔺)

This branch was successfully deployed

1 active deployment
Preview — 3ca94eba Deployed Nov 21, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant