Repository navigation
Description
Describe the bug
While investigating recovery after an audio device disconnects and returns, we reproduced SDK-level gaps in livekit-client@2.24.0 and found the same paths on current main (f1941c89):
- With
webAudioMix: true,switchActiveDevice('audiooutput', ...)invokesAudioContext.setSinkId()without awaiting it. The switch can resolve and emitActiveDeviceChangedwhile routing is still pending. A routing rejection then becomes an unhandled rejection, with the requested output still reported as active. - A microphone enable can outlive a later disable. In particular, the first capture can remain pending longer than the ten-second pending-publication lookup. The disable then resolves without a track, but granting capture afterward publishes an enabled microphone.
- Replacement capture and failed ended-track fallback also need to respect newer mute/unmute requests while capture, processor restart, sender adoption, or republishing is pending.
The microphone case is visible in an application's Deafen flow because Deafen calls setMicrophoneEnabled(false). Deafen itself is application behavior; the proposed SDK change concerns the ordering of microphone enable/disable requests.
Reproduction
Late first capture
- Start with no published microphone and let the first capture remain pending (a permission prompt or a controlled
getUserMediapromise). - Call
participant.setMicrophoneEnabled(true)without awaiting completion. - Call
participant.setMicrophoneEnabled(false)while capture remains pending. - Keep capture pending beyond the current ten-second lookup timeout, then allow capture to complete.
- Observe that disable already resolved, but an enabled microphone is subsequently published.
Expected: the later disable remains authoritative; cancelled capture must not be published enabled. A subsequent explicit enable should still work.
Mixed output routing
- Connect a room with
webAudioMix: trueand a supported selectable audio output. - Delay or reject
AudioContext.setSinkId()in a controlled browser fixture. - Call
room.switchActiveDevice('audiooutput', targetDeviceId). - Observe successful completion/device-change notification before the context route finishes, or successful completion followed by an unhandled rejection.
Expected: the switch waits for the actual route, propagates rejection, and retains the previous confirmed selection on failure.
Proposed change
Await mixed-context output routing before confirming the switch. Track microphone intent across pending first capture/publication and republish gaps; keep replacement raw capture disabled during asynchronous adoption; invalidate obsolete unmute and emergency-mute continuations when newer explicit intent arrives. Keep processor output usable for later unmute and preserve existing stopped-track and cleanup guards.
The source-only implementation and native Vitest regressions are available on a fork for review. The tests cover deferred/rejected output routes, first capture, pending publication, processed audio adoption, fallback races, rapid mute/unmute, engine closure, and republishing. No generated bundle changes are needed in the upstream PR. Please confirm whether this approach is suitable and mark this issue accepted if you would like the PR, as required by CONTRIBUTING.md.
Verification and environment
- Published SDK:
livekit-client@2.24.0; current main inspected atf1941c89. - Controlled tests reproduced premature output success and late enabled publication in both published ESM and UMD builds.
- Browser API simulation was exercised in Brave on Windows 11; physical headset routing and remote speech were not measured.
- Native source regression tests use controlled capture, processor, sender, and publication promises. Node.js 24.22.1; Windows 11 build 26300.
Validation of the proposed source branch: 1,120 tests passed, 1 skipped; TypeScript, targeted ESLint/Prettier, the Linux build, and core import/type checks passed. The Windows core packaging failure also reproduces on pristine upstream main.
Additional information
AI assistance: OpenAI Codex helped investigate, implement, and test the proposed change and draft this report.
Activity
1egoman commentedon Nov 16, 2026
Thanks for the report!
Output routing (part 1)
Yes, confirmed. I've split it into #2275 and fixed it in #2276.
Microphone enable/disable ordering (part 2)
This is a real bug, and probably a more common one than I think your 10-second timeframe suggests -
waitForPendingPublicationOfSourceonly looks atpendingPublishPromises, and nothing is added there untilpublishTrackis called, which is aftergetUserMediaresolves. So while a permission prompt is open, a disable just polls for 10s and gives up. A grant after that publishes an enabled track.A second concurrent enable has the same problem: it waits out the timeout and resolves to undefined.
I think it makes sense to fix this differently from your draft PR (which I have closed for now), though. Nothing in
setTrackEnabledis specific to the microphone, so the camera has exactly the same race. I think it makes a lot more sense to fix it across every source insidesetTrackEnabledrather than add microphone-specific state.How about something like:
pendingPublishing: Set<Track.Source>and the 10s polling loop with aMap<Track.Source, Promise<LocalTrackPublication | null>>. The entry is added before capture starts, so anyone waiting gets the real result instead of a timeout.setTrackEnabled, so it still waits for a republish in progress the way it does today.There are a few things in the branch that would be good to specifically avoid:
unmute()fromrestart(undefined, true)torestart(), which brings back the extra mute/unmute round-trip that isUnmuting exists to preventenabled = falseon every replacement mic track in setMediaStreamTrackIf you want to pick this up along those lines, please close this issue / open a new issue (or update this issue and ping me) so it is scoped to the
setTrackEnabledordering bug and I can mark it accepted. Tests like the ones on your WIP branch (capture still pending, publication still pending, disable during capture, then enable again) would I think carry over well. Please include a camera case as well!In regards to Replacement capture, processor restart, ended-track fallback, republish: please file each of these as its own issue with a minimal repro. Right now they're described rather than demonstrated. I think it's important for us to evaluate each against real behavior, ideally on a real device and not only simulated browser APIs, before considering changes to
LocalTrack/LocalAudioTrack.