Video Device Management

getCameraMaxZoomFactor

Gets the maximum zoom factor supported by the camera.

public abstract float getCameraMaxZoomFactor();
Note: You must call this method after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1).

Return Values

If the method call succeeds, returns the maximum zoom factor supported by the camera.

isCameraAutoFocusFaceModeSupported

Checks whether the device supports face auto-focus.

public abstract boolean isCameraAutoFocusFaceModeSupported();
Note: You must call this method after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1).

Return Values

  • true: The device supports face auto-focus.
  • false: The device does not support face auto-focus.

isCameraExposurePositionSupported

Checks whether the device supports manual exposure.

public abstract boolean isCameraExposurePositionSupported();
Since
Available since v2.3.2.
Note: You must call this method after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1).

Return Values

  • true: The device supports manual exposure.
  • false: The device does not support manual exposure.

isCameraExposureSupported

Checks whether the current camera supports adjusting exposure.

public abstract boolean isCameraExposureSupported();
Since
Available since v4.2.2.
Note: You must call this method after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1). Before calling setCameraExposureFactor, it is recommended to call this method to check whether the current camera supports adjusting exposure. This method adjusts the exposure of the currently active camera, i.e., the one specified in setCameraCapturerConfiguration.

Return Values

  • true: The current camera supports adjusting exposure.
  • false: The current camera does not support adjusting exposure.

isCameraFaceDetectSupported

Checks whether the device camera supports face detection.

public abstract boolean isCameraFaceDetectSupported();

Return Values

  • true: The device camera supports face detection.
  • false: The device camera does not support face detection.

isCameraFocusSupported

Checks whether the device supports manual focus.

public abstract boolean isCameraFocusSupported();
Note: You must call this method after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1).

Return Values

  • true: The device supports manual focus.
  • false: The device does not support manual focus.

isCameraTorchSupported

Checks whether the device supports camera torch.

public abstract boolean isCameraTorchSupported();
Note: You must call this method after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1). The app uses the front camera by default. If the front camera does not support torch, this method returns false. To check whether the rear camera supports torch, call switchCamera before calling this method.

Return Values

  • true: The device supports camera torch.
  • false: The device does not support camera torch.

isCameraZoomSupported

Checks whether the device supports camera zoom.

public abstract boolean isCameraZoomSupported();

Timing

You must call this method after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1).

Return Values

  • true: The device supports camera zoom.
  • false: The device does not support camera zoom.

queryCameraFocalLengthCapability

Queries the focal length capabilities supported by the camera.

public abstract AgoraFocalLengthInfo[] queryCameraFocalLengthCapability();

It is recommended to call this method before enabling wide-angle or ultra-wide-angle mode for video capture to check whether the device supports the required focal length capabilities. Based on the query result, call setCameraCapturerConfiguration to adjust the camera's focal length configuration to ensure optimal video capture performance.

Return Values

  • If the method call succeeds, returns an array of AgoraFocalLengthInfo objects, containing the camera direction and focal length type.
  • If the method call fails, returns an empty array.

queryCodecCapability

Queries the SDK's video codec capabilities.

public abstract CodecCapInfo[] queryCodecCapability();

Return Values

If the method call succeeds, it returns an array of CodecCapInfo, indicating the device's video encoding capabilities. If the method call times out, please modify your logic to avoid calling this method on the main thread.

setCameraAutoFocusFaceModeEnabled

Enables or disables camera face auto-focus.

public abstract int setCameraAutoFocusFaceModeEnabled(boolean enabled);

Timing

You must call this method after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1).

Parameters

enabled
Whether to enable face auto-focus:
  • true: Enable camera face auto-focus.
  • false: Disable camera face auto-focus.

Return Values

  • 0: Success.
  • < 0: Failure.

setCameraCapturerConfiguration

Sets the camera capture configuration.

public abstract int setCameraCapturerConfiguration(CameraCapturerConfiguration config);

This method must be called before enabling local video capture, for example, before calling startPreview or joinChannel.

Note: To adjust the camera focal length configuration, it is recommended to first call queryCameraFocalLengthCapability to query the device's focal length capabilities and configure accordingly. Due to limitations on some Android devices, setting the focal length type based on the result of queryCameraFocalLengthCapability may not take effect.

Timing

This method must be called before enabling local video capture, for example, before calling startPreview or joinChannel.

Parameters

config
Camera capture configuration. See CameraCapturerConfiguration.

Return Values

  • 0: Success.
  • < 0: Failure.

setCameraExposureFactor

Sets the camera exposure value.

public abstract int setCameraExposureFactor(int factor);
Since
Available since v4.2.2.
Note:
  • You must call this method after calling enableVideo. The setting takes effect after the camera is successfully started, i.e., after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1).
  • Before calling this method, Agora recommends calling isCameraExposureSupported to check whether the current camera supports adjusting exposure.
  • By calling this method, you can adjust the exposure of the currently active camera, i.e., the one specified in setCameraCapturerConfiguration.

Parameters

factor
Camera exposure value. The default is 0, which means using the camera's default exposure. The higher the value, the stronger the exposure. If the video image is overexposed, you can reduce the exposure value; if the image is underexposed and lacks detail in dark areas, you can increase the exposure value. If the set value exceeds the supported range of the device, the SDK automatically adjusts it to the supported range. The valid range is [-20, 20].

Return Values

  • 0: Success.
  • < 0: Failure.

setCameraExposurePosition

Sets the camera exposure position.

public abstract int setCameraExposurePosition(float positionXinView, float positionYinView);
Since
Available since v2.3.2.
Note: You must call this method after calling enableVideo. The setting takes effect after the camera is successfully started, i.e., after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1). After successfully calling this method, the SDK triggers the onCameraExposureAreaChanged callback.

Parameters

positionXinView
The horizontal coordinate of the touch point in the view.
positionYinView
The vertical coordinate of the touch point in the view.

Return Values

  • 0: Success.
  • < 0: Failure.

setCameraFocusPositionInPreview

Sets the manual focus position of the camera.

public abstract int setCameraFocusPositionInPreview(float positionX, float positionY);
Note: You must call this method after calling enableVideo. The setting takes effect after the camera is successfully started, i.e., after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1). After successfully calling this method, the SDK triggers the onCameraFocusAreaChanged callback.

Parameters

positionX
The horizontal coordinate of the touch point in the view.
positionY
The vertical coordinate of the touch point in the view.

Return Values

  • 0: Success.
  • < 0: Failure.

setCameraTorchOn

Turns the camera flash on or off.

public abstract int setCameraTorchOn(boolean isOn);
Note: You must call this method after calling enableVideo. The setting takes effect after the camera is successfully started, i.e., after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1).

Parameters

isOn
Whether to turn on the camera flash:
  • true: Turn on the flash.
  • false: (default) Turn off the flash.

Return Values

  • 0: Success.
  • < 0: Failure.

setCameraZoomFactor

Sets the camera zoom factor.

public abstract int setCameraZoomFactor(float factor);
Note: You must call this method after calling enableVideo. This setting takes effect after the camera is successfully started, i.e., after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1).

Parameters

factor
Camera zoom factor. You can call getCameraMaxZoomFactor to get the maximum zoom factor supported by the device.

Return Values

  • If the method call succeeds, returns the value of the camera zoom factor factor.
  • If the method call fails, returns a value less than 0.

switchCamera [1/2]

Switches between front and rear cameras.

public abstract int switchCamera();

You can call this method during runtime to dynamically switch between front and rear cameras based on the available cameras, without restarting the video stream or reconfiguring the video source. This method and switchCamera(String cameraId) can both be used to switch cameras. The difference is that switchCamera(String cameraId) switches to a specific camera by specifying the camera ID, while this method switches the camera direction (front or rear).

Note: This method only switches the camera for the video stream captured by the primary camera, i.e., the video stream whose source is set to VIDEO_SOURCE_CAMERA_PRIMARY (0) when calling startCameraCapture.

Timing

You must call this method after the camera is successfully enabled, i.e., after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1).

Return Values

  • 0: Success.
  • < 0: Failure.

switchCamera [2/2]

Switches cameras by camera ID.

public abstract int switchCamera(String cameraId);

You can call this method during runtime to dynamically switch cameras based on the available ones, without restarting the video stream or reconfiguring the video source. This method is similar to switchCamera, but while switchCamera switches the camera direction (front or rear), this method switches to a specific camera by specifying the camera ID.

Note: This method only switches the camera for the video stream captured by the primary camera, i.e., the video stream whose source is set to VIDEO_SOURCE_CAMERA_PRIMARY (0) when calling startCameraCapture.

Timing

You must call this method after the camera is successfully enabled, i.e., after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1).

Parameters

cameraId
The camera ID. You can obtain the camera ID using Android native APIs such as Camera.open and CameraManager.getCameraIdList.

Return Values

  • 0: Success.
  • < 0: Failure.

onCameraExposureAreaChanged

Callback for when the camera exposure area changes.

public void onCameraExposureAreaChanged(Rect rect)

This callback is triggered when the local user calls setCameraExposurePosition to change the camera exposure position.

Trigger Timing

This callback is triggered when setCameraExposurePosition is called to change the camera exposure position.

Parameters

rect
The exposure rectangle area in the local preview. See [Rect](https://developer.android.google.cn/reference/android/graphics/Rect).

onCameraFocusAreaChanged

Callback for when the camera focus area changes.

public void onCameraFocusAreaChanged(Rect rect)

This callback is triggered when the local user calls setCameraFocusPositionInPreview to change the camera focus position.

Parameters

rect
The focus rectangle area in the local preview. See [Rect](https://developer.android.google.cn/reference/android/graphics/Rect).

onCameraReady

Callback triggered when the camera is turned on and ready to capture video.

public void onCameraReady() {}
Deprecated
This method is deprecated. Use onLocalVideoStateChanged instead.

Trigger Timing

This callback is triggered when the camera is successfully turned on and ready to capture video.