Best practices

These recommendations help you ship a reliable audio experience with the Video SDK for macOS.

Permissions

The SDK cannot capture from the microphone until the user has granted microphone access. Add an NSMicrophoneUsageDescription entry to your app's Info.plist and request permission before you call startAudio.

• Request microphone access when the user takes an action that needs audio (such as joining a session or clicking "Unmute"), not at app launch.
• If the user denies access, surface a clear message and a path to System Settings > Privacy & Security > Microphone.

For details, see Requesting Authorization for Media Capture on macOS.

Device selection

Desktop users frequently have multiple microphones and speakers (built-in, USB headset, external interface). Offer a settings UI built from getMicList and getSpeakerList so users can choose, and remember their selection between sessions. For more information, see Select an audio device.

Enable audio with a clear action

Connect audio in response to an explicit user action, and reflect the connection and mute state prominently in your UI. Connecting audio silently in the background can surprise users and trip permission prompts at unexpected times.

Show mute and talking status

Use the audio events to keep your UI in sync:

• Implement onUserAudioStatusChanged to show each user's current mute state.
• Implement onUserActiveAudioChanged to show a talking/active-speaker indicator.

Host controls

When you mute everyone with muteAllAudio, decide deliberately whether to allow users to unmute themselves, and communicate that state in your UI so participants understand why their unmute control is or isn't available.

Lifecycle

Stop audio when the user explicitly leaves the session. Keep audio connection and mute state in your view model so it survives view reloads.