feat(realtime): add playRemoteAudio connect option to gate audio playback

[nagar-decart]

Summary

• Add opt-in playRemoteAudio: boolean to both client.realtime.connect() and client.realtime.subscribe(). Default false.
• When false, audio tracks the model emits are dropped on the client: no playback element is attached, and the track is not added to the stream passed to onRemoteStream.
• When true, current behavior is preserved (auto-attach + included in remoteStream).
• Video tracks are untouched.

Why

livekit-client's track.attach() creates a hidden, un-muted <audio> element per subscribed audio track and plays it. That element is independent of any <video muted> an app wires up via onRemoteStream — muting the app's video element does not silence the audio playback.

Apps that previously assumed "no audio output unless I unmute my own <video>" started hearing unexpected playback when the upstream service began publishing audio tracks (e.g. for models that echo input audio or generate speech). The right gate is in the SDK: only the SDK knows the difference between "an audio track was delivered" and "the app actually wants to play it." Apps that do want audio opt in.

Behavior matrix

	playRemoteAudio unset / false	playRemoteAudio: true
track.attach() for audio	skipped	called (default LK behavior)
Audio in MediaStream from onRemoteStream	omitted	included
Video handling	unchanged	unchanged

Default rationale

Default is false — audio is an explicit opt-in. Defaulting to true would be a silent breaking change for apps that already exist: they'd start hearing audio they never asked for and that they tried to silence with <video muted>. False matches the implicit "audio is off unless I ask for it" behavior most existing apps already rely on.

Test plan

• Added unit tests in tests/realtime.unit.test.ts:
  • drops remote audio tracks by default — no attach, not added to remoteStream (and verifies video still flows through in the same session)
  • plays remote audio tracks when playRemoteAudio is true
• pnpm test — 208/208 pass
• pnpm typecheck — clean
• pnpm build — clean

Notes / follow-ups

• The audio track is still subscribed by livekit-client and consumes bandwidth even when playRemoteAudio: false. A future optimization could unsubscribe at the publication level (publication.setSubscribed(false) on RoomEvent.TrackPublished) to also save bandwidth, but that's a larger change and orthogonal to silencing.
• The same gate is applied to both realtime.connect() (publisher) and realtime.subscribe() (viewer) so audio behavior is consistent across both API surfaces.

🤖 Generated with Claude Code

---

Note

Low Risk
Client-side media gating with safe default false; no auth or server contract changes beyond optional connect/subscribe options and documented behavior.

Overview
Adds an opt-in playRemoteAudio flag (default false) on client.realtime.connect() and subscribe(), threaded through StreamSession into MediaChannel (and the subscribe LiveKit handler).

When playRemoteAudio is unset or false, subscribed remote audio from the inference server is ignored: track.attach() is not called and the audio MediaStreamTrack is not added to the stream delivered via onRemoteStream, so LiveKit’s hidden playback element does not play model/mic echo audio. true restores prior behavior (attach + audio in the remote stream). Video handling is unchanged.

Unit tests cover default-off audio dropping vs video still flowing, and playRemoteAudio: true enabling audio attach and stream inclusion.

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

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@decartai/sdk@147

commit: c89a1c1