fix: prevent mute cycling when restarting tracks during unmute

[mfairley]

When unmuting audio/video tracks that require reacquisition (e.g., due to
stopOnMute, ended track state, or device changes), the track restart would
cause a mute cycle (enabled=false then immediately enabled=true).

This happened because:

1. restartTrack() creates a new MediaStreamTrack
2. setMediaStreamTrack() syncs enabled state with !this.isMuted
3. But isMuted is still true at this point (super.unmute() hasn't run yet)
4. So the new track starts with enabled=false
5. Then super.unmute() sets enabled=true

On iOS, this causes audible mute/unmute sounds for the microphone and can
trigger system callbacks multiple times as the system detects the rapid
enabled state changes.

The fix adds a targetEnabled parameter that flows through:

• unmute() -> restartTrack(undefined, true)
• restartTrack() -> restart(constraints, targetEnabled)
• restart() -> setMediaStreamTrack(newTrack, false, targetEnabled)

When targetEnabled is provided, setMediaStreamTrack uses it instead of
deriving the enabled state from isMuted, ensuring the new track starts
with the correct enabled state.

Related issues

• iOS: unmuting audio triggers unmute -> mute -> unmute in rapid succession react-native-webrtc#66
• iOS/Expo: Weird behavior with setMicrophoneEnabled(true) client-sdk-react-native#287

This partially addresses the above issues but does not fix the possibly unnecessary restarts caused by device ID mismatches.

Test plan

• Tested muting and unmuting microphone on iOS
• Tested muting and unmuting video on iOS
• Verified no mute cycling occurs during unmute with track restart

Summary by CodeRabbit

• Bug Fixes
  • Prevented mute–unmute cycling when re-acquiring microphones by preserving the intended enabled state during restarts.
  • Ensured camera restarts refresh simulcast encodings and rebind sender tracks so video continuity and quality are maintained.
  • Improved unmute behavior so devices come back enabled predictably after restart, avoiding unexpected muted states.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 83f3f62

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
livekit-client	Patch

Not sure what this means? Click here to learn what changesets are.

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

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

📝 Walkthrough

Walkthrough

Propagates a new optional targetEnabled flag through restart paths in LocalTrack, LocalAudioTrack, and LocalVideoTrack so reacquired MediaStreamTracks can be set to the intended enabled state; LocalVideoTrack also rebinds simulcast encodings after restart.

Changes

Cohort / File(s)	Summary
Core restart propagation src/room/track/LocalTrack.ts	Added targetEnabled?: boolean to restart(...); added private async setMediaStreamTrack(newTrack, force?, targetEnabled?); propagate targetEnabled to control MediaStreamTrack.enabled during track swaps to avoid mute cycling.
Audio restart and unmute flow src/room/track/LocalAudioTrack.ts	restartTrack(options?: AudioCaptureOptions, targetEnabled?: boolean) and restart(..., targetEnabled?) signatures updated; unmute path calls restartTrack(undefined, true) so the reacquired mic honors enabled state.
Video restart, unmute, and simulcast refresh src/room/track/LocalVideoTrack.ts	restartTrack(options?: VideoCaptureOptions, targetEnabled?: boolean) added and forwarded; unmute passes targetEnabled=true. After restart, iterates simulcast encodings and clones/replaces each simulcast MediaStreamTrack on active RTCRtpSenders to rebind streams.
Changelog .changeset/gold-pens-fly.md	Adds a changeset noting a patch: prevents unmute→mute→unmute cycling for track restarts occurring during unmute.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐇 I nudged the stream and gave a twitch,

Tracks restart without the glitch,
Enabled flags now hop in line,
Simulcast hums, rebinding fine,
A tiny hop — the code's just rich!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix: prevent mute cycling when restarting tracks during unmute' directly and clearly describes the main change: preventing mute cycling during unmute with track restarts by adding a targetEnabled parameter.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f62a223 and 83f3f62.

📒 Files selected for processing (4)

• .changeset/gold-pens-fly.md
• src/room/track/LocalAudioTrack.ts
• src/room/track/LocalTrack.ts
• src/room/track/LocalVideoTrack.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• .changeset/gold-pens-fly.md

🧰 Additional context used

🧬 Code graph analysis (2)

src/room/track/LocalVideoTrack.ts (3)

src/room/track/options.ts (1)

• VideoCaptureOptions (169-192)

src/room/track/LocalTrack.ts (1)

• constraints (38-40)

src/room/track/utils.ts (1)

• constraintsForOptions (64-103)

src/room/track/LocalAudioTrack.ts (3)

src/room/track/options.ts (1)

• AudioCaptureOptions (244-298)

src/room/track/LocalTrack.ts (1)

• constraints (38-40)

src/room/track/utils.ts (1)

• constraintsForOptions (64-103)

🔇 Additional comments (7)

src/room/track/LocalTrack.ts (2)

148-210: Good: targetEnabled prevents transient mute cycling on restart.
Clear, minimal change, and the fallback to !this.isMuted preserves existing behavior when the flag isn’t provided.

---

328-372: LGTM: restart now propagates targetEnabled correctly.
Forwarding the flag to setMediaStreamTrack keeps the enabled state consistent through reacquisition.

src/room/track/LocalVideoTrack.ts (2)

161-172: Nice: unmute reacquisition explicitly targets enabled state.
This matches the PR goal and avoids the mute/unmute oscillation on iOS.

---

249-268: LGTM: restartTrack forwards targetEnabled and keeps post-restart logic intact.
The propagation is clean, and the restart flow remains coherent.

src/room/track/LocalAudioTrack.ts (3)

69-90: Good: mic reacquisition on unmute sets explicit enabled target.
Aligns with the new enabled-state contract and prevents cycling.

---

98-107: LGTM: restartTrack signature and forwarding are consistent.
Optional targetEnabled keeps existing call sites compatible.

---

109-114: LGTM: restart override forwards targetEnabled and preserves silence check.
No regression risk spotted here.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@src/room/track/LocalAudioTrack.ts`:
- Around line 109-110: The method signature for LocalAudioTrack.restart is not
formatted to match Prettier; re-run the project's Prettier auto-fixer or
manually reformat the signature of the restart method (protected async
restart(constraints?: MediaTrackConstraints, targetEnabled?: boolean):
Promise<typeof this>) to match the repository's style (e.g., adjust spacing or
break parameters onto separate lines) and ensure the body (including the
super.restart call) remains unchanged so the CI Prettier check passes.

In `@src/room/track/LocalTrack.ts`:
- Line 148: Reformat the LocalTrack class method signature setMediaStreamTrack
so it matches the project's Prettier rules: break the parameter list onto
multiple lines (one parameter per line) and ensure consistent spacing around the
commas and optional parameter markers (e.g., force?: boolean, targetEnabled?:
boolean) and the opening brace; update the signature of private async
setMediaStreamTrack(newTrack: MediaStreamTrack, force?: boolean, targetEnabled?:
boolean) accordingly so the line no longer violates Prettier.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1744ee4 and c447e8d.

📒 Files selected for processing (3)

• src/room/track/LocalAudioTrack.ts
• src/room/track/LocalTrack.ts
• src/room/track/LocalVideoTrack.ts

🧰 Additional context used

🧬 Code graph analysis (1)

src/room/track/LocalVideoTrack.ts (3)

src/room/track/options.ts (1)

• VideoCaptureOptions (169-192)

src/room/track/LocalTrack.ts (1)

• constraints (38-40)

src/room/track/utils.ts (1)

• constraintsForOptions (64-103)

🪛 ESLint

src/room/track/LocalAudioTrack.ts

[error] 109-109: Replace constraints?:·MediaTrackConstraints,·targetEnabled?:·boolean with ⏎····constraints?:·MediaTrackConstraints,⏎····targetEnabled?:·boolean,⏎··

(prettier/prettier)

src/room/track/LocalTrack.ts

[error] 148-148: Replace newTrack:·MediaStreamTrack,·force?:·boolean,·targetEnabled?:·boolean with ⏎····newTrack:·MediaStreamTrack,⏎····force?:·boolean,⏎····targetEnabled?:·boolean,⏎··

(prettier/prettier)

🪛 GitHub Actions: Test

src/room/track/LocalAudioTrack.ts

[error] 109-109: prettier/prettier formatting issue in LocalAudioTrack.ts: Replace 'constraints?: MediaTrackConstraints, targetEnabled?: boolean' with proper formatting.

🪛 GitHub Check: test

src/room/track/LocalAudioTrack.ts

[failure] 109-109:
Replace constraints?:·MediaTrackConstraints,·targetEnabled?:·boolean with ⏎····constraints?:·MediaTrackConstraints,⏎····targetEnabled?:·boolean,⏎··

src/room/track/LocalTrack.ts

[failure] 148-148:
Replace newTrack:·MediaStreamTrack,·force?:·boolean,·targetEnabled?:·boolean with ⏎····newTrack:·MediaStreamTrack,⏎····force?:·boolean,⏎····targetEnabled?:·boolean,⏎··

🔇 Additional comments (6)

src/room/track/LocalTrack.ts (2)

204-206: Enabled state now deterministic during restart.

Using targetEnabled avoids transient mute cycling in the unmute-restart path.

---

324-367: Restart path cleanly propagates targetEnabled.

The forwarding into setMediaStreamTrack keeps restart behavior consistent with the new unmute flow.

src/room/track/LocalAudioTrack.ts (2)

77-89: Reacquire on unmute now forces enabled state.

Passing true avoids the mute-cycle regression during track restart.

---

98-107: Restart propagation looks good.

The new optional targetEnabled cleanly flows into the base restart.

src/room/track/LocalVideoTrack.ts (2)

161-172: Unmute now restarts with explicit enabled state.

This mirrors the audio fix and should avoid the mute-cycle during camera reacquisition.

---

249-268: Restart now refreshes simulcast tracks appropriately.

Cloning and replacing simulcast tracks after restart keeps encodings in sync with the new MediaStreamTrack.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

[mfairley]

@xianshijing-lk could you please review this PR?

[davidliu]

LGTM, @lukasIO is there anything here that could affect web? Should be an isolated change.

[lukasIO]

restarts would always cause a track to be enabled afterwards, so I believe we can get rid of passing the targetEnabled prop in the other methods and only keep it here

[mfairley]

Could you explain a bit more? We are triggering the restart from the unmute method so I think we need to pass the argument from unmute to where it's needed, which requires going through a few methods.

[lukasIO]

my thinking was that for restartTrack it's implicit that targetEnabled = true.
But looking at it again that seems like a misconception on my side, sorry about that!

Just wanted to ensure the public API stays as lean as possible and ideally it would be preferable to not expose the targetEnabled param on restartTrack

[mfairley]

Yeah, I understand wanting to keep the public API as lean as possible. Some alternative approaches include introducing a class variable such as isPendingUnmute, but then that introduces additional state to manage and is less explicit. Another is using the current approach but having a better name e.g. targetEnabled -> isUnmuting since this is probably the only case when you don't want to immediately sync the mute state. Another is adding this parameter to VideoCaptureOptions/AudioCaptureOptions but it doesn't seem to quite fit with the intention of that. Let me know if you have any preferences.