Overview
There are two operations of different granularity for controlling local audio and video publishing. Picking the wrong one causes unnecessary resource waste or broken behavior:
enableLocalTrack / disableLocalTrack
These two methods only control sending of media data; the underlying WebRTC connection stays up. They suit scenarios where you need to toggle mute/unmute quickly.
Note: After disableLocalTrack, microphone capture continues (the indicator stays on); it just stops pushing data to the channel.
If you want to stop capture entirely to release the microphone, use unpublishLocalTrack + stopCapture.
unpublishLocalTrack / publishLocalTrack
Stops/restarts publishing entirely, which fires the USER_TRACK_REMOVE / USER_TRACK_ADD events on the remote side. Suitable for scenarios such as a user leaving the stage or “Stop sharing” during a call.
Before publishing again, make sure the previous track with the same desc has finished unpublishLocalTrack—within one channel only one track per desc may be published, and publishing the same desc again with a different track throws.In particular, don’t let “microphone off” and “microphone on” actions interleave: if another “microphone on” is started during the await window of the previous publishLocalTrack, two microphone tracks publish at the same time, and you only keep a reference to the one created later. The one published first can’t be unpublished and its capture can’t be stopped, so the remote side keeps hearing audio. Add a serial queue or a button loading state to such entry points.
Recommendations
- Microphone mute button in a call → use
disableLocalTrack / enableLocalTrack for fast response and a smooth experience
- Stop screen sharing → use
unpublishLocalTrack + stopCapture to release resources entirely
- Temporarily turn off the camera (video goes black) → use
disableLocalTrack
- Turn off the camera entirely (release the device) → use
unpublishLocalTrack + stopCapture
