Best practices

These recommendations help you ship a polished video experience with the Video SDK for macOS.

Permissions

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

  • Request camera access at the moment the user takes an action that needs video (such as clicking a "Start camera" button), not at app launch. This makes the prompt feel justified.
  • If the user denies access, surface a clear message and a path to retry by opening System Settings > Privacy & Security > Camera.
  • If you also need audio, add an NSMicrophoneUsageDescription entry and request microphone access at the same time.

For the macOS permission flow, see Requesting Authorization for Media Capture on macOS.

Camera selection

  • Offer a chooser. Use getCameraList to populate a settings UI so users can pick their preferred camera. Many desktop setups have multiple cameras attached.
  • Mirror the preview. Call mirrorMyVideo(true) so users see themselves the way they would in a mirror. Toggle the mirror when the user switches cameras.
  • Persist the choice. Remember the user's selected camera between sessions and re-apply it with selectCamera.

Layout and density

The SDK doesn't enforce a maximum number of rendered videos, but performance and screen real estate do. On macOS, where window sizes vary widely, base your grid on the current window size rather than a fixed count, and paginate when the user count exceeds your grid. When video tiles are too small, the content is no longer useful.

Show video status in your UI

When a user has their camera off, render a placeholder (an avatar, initials, or a "camera off" icon) instead of a blank tile. Implement onUserVideoStatusChanged so you can switch between the rendered video and the placeholder as users toggle their cameras.

Lifecycle

  • Subscribe to a user's video pipe when its view appears and unsubscribe when the view is removed or the window closes, to avoid leaking renderers.
  • Stop video when the user explicitly leaves the session. Keep video-related state in your view model so it survives view reloads.

Network resilience

Use setVideoQualityPreference to bias the SDK toward smoothness or sharpness depending on your use case. For most video conferencing scenarios, the default Balance mode is appropriate; switch to Sharpness for content where image detail matters (medical imaging, document cameras) and Smoothness for motion-heavy content (sports, demos).

Hardware

Check isDeviceSupportAlphaChannelMode before exposing alpha-channel video features, since not all devices support them.