Best practices

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

Permissions

The SDK cannot capture from the camera until the user has granted the CAMERA runtime permission. Request the permission before you call startVideo().

  • Request CAMERA at the moment the user takes an action that needs video (such as tapping a "Start camera" button), not at app launch. This makes the prompt feel justified.
  • If the user denies the permission, surface a clear message and a path to retry. For example, link them to Android settings using Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS) so they can grant the permission outside the app.
  • If you also need audio, request RECORD_AUDIO at the same time.

See the Android permissions overview for the runtime-permission flow.

Camera selection

  • Offer a chooser: Use getCameraList() to populate a settings UI so users can pick their preferred camera.
  • Default to the front camera: Most users joining a video call expect the front camera initially.
  • Mirror the front camera preview: Call mirrorMyVideo(true) on front-facing cameras so users see themselves the way they would in a mirror. Don't mirror back-camera video. Toggle the mirror when the user switches cameras.
  • React to device changes: Watch for cameras being attached or removed (for example, USB cameras on tablets) and refresh your camera list.

Layout and density

The SDK doesn't enforce a maximum number of rendered videos, but performance and screen real estate do. For a balance of clarity and performance, the following layouts work well on most Android devices:

  • Phones (portrait): 2x2 grid (4 videos per page)
  • Phones (landscape) and small tablets: 3x2 grid (6 videos per page)
  • Larger tablets: 3x3 grid (9 videos per page)

When the number of users exceeds your grid size, paginate rather than scaling videos down further. When video tiles are too small, the content is no longer useful.

Aspect ratio and orientation

  • Use CSS-like layout constraints (ConstraintLayout, aspectRatio) on the parent of each ZoomVideoSDKVideoView so videos resize predictably with the container.
  • When the device rotates, call rotateMyVideo with the new orientation so remote users see your video in the correct orientation. Override onConfigurationChanged (or use OrientationEventListener) to detect rotation.
  • The ZoomVideoSDKVideoAspect_Original aspect mode is the safest default. It never crops or distorts. Use Full_Filled only when you control the source aspect ratio.

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. Subscribe to onUserVideoStatusChanged so you can switch between the rendered video and the placeholder as users toggle their cameras.

Lifecycle

Android Activities are destroyed and recreated on configuration changes (rotation, theme change, etc.). To avoid disrupting the user's video:

  • Either keep your video-related state in a ViewModel (recommended), or declare android:configChanges="orientation|screenSize|keyboardHidden" in your Activity manifest so the OS doesn't recreate the Activity on rotation.
  • Unsubscribe ZoomVideoSDKVideoView instances from their canvases in onDestroy() to avoid leaks.
  • Android restricts camera access while your app is in the background, so video capture stops on its own. You generally don't need to call stopVideo() in onPause(). Stop video when the user explicitly leaves the session.

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