Device Management

Audio Route

isSpeakerphoneEnabled

Checks whether the speaker is enabled for audio playback.

public abstract boolean isSpeakerphoneEnabled();

Timing

You can call this method before or after joining a channel.

Return Values

  • true: The speaker is enabled, and audio will play through the speaker.
  • false: The speaker is not enabled, and audio will play through other devices such as a headset or earpiece.

setDefaultAudioRoutetoSpeakerphone

Sets the default audio playback route.

public abstract int setDefaultAudioRoutetoSpeakerphone(boolean defaultToSpeaker);
Most phones have two audio routes: the earpiece at the top and the speaker at the bottom. You can call this method to set the default audio route, determining whether audio plays through the earpiece or speaker when no external audio device is connected. In different scenarios, the system's default audio routes are:
  • Voice call: Earpiece.
  • Audio live streaming: Speaker.
  • Video call: Speaker.
  • Video live streaming: Speaker.
Note: After setting the default audio route with this method, the actual audio route will automatically switch based on the connection status of external audio devices (e.g., wired or Bluetooth headsets).

Timing

Call this method before joining a channel. If you need to change the audio route after joining a channel, call setEnableSpeakerphone.

Parameters

defaultToSpeaker
Whether to set the speaker as the default audio route:
  • true: Set the speaker as the default audio route.
  • false: Set the earpiece as the default audio route.

Return Values

  • 0: Success.
  • < 0: Failure.

setEnableSpeakerphone

Sets whether to switch the audio route to the speaker.

public abstract int setEnableSpeakerphone(boolean enabled);
Note: This method only sets the audio route for the current channel and does not affect the default audio route. If the user leaves the current channel and joins another, the default audio route will be used. If the user uses external audio playback devices such as Bluetooth or wired headsets, this method has no effect. The SDK plays audio through the external device. When multiple external devices are connected, the SDK plays audio through the last connected device.

Scenario

If the SDK's default audio route or the setting from setDefaultAudioRoutetoSpeakerphone does not meet your needs, you can call this method to switch the current audio route.

Timing

Call this method after joining a channel.

Related Callbacks

After successfully calling this method, the SDK triggers the onAudioRouteChanged callback to report the current audio route.

Parameters

enabled
Whether to enable the speaker:
  • true: Enable device state monitoring, audio route is speaker.
  • false: Disable device state monitoring, audio route is earpiece.

Return Values

  • 0: Success.
  • < 0: Failure.

setRouteInCommunicationMode

Sets the audio playback route in communication audio mode.

public abstract int setRouteInCommunicationMode(int route);

This method switches the audio route from a Bluetooth headset to the earpiece, wired headset, or speaker.

Note: Using this method together with setEnableSpeakerphone may cause conflicts. It is recommended to use only setRouteInCommunicationMode.

Timing

You can call this method before or after joining a channel.

Related Callbacks

After successfully calling this method, the SDK triggers the onAudioRouteChanged callback to report the current audio route.

Parameters

route
The audio playback route you want to use:
  • -1: Default audio route.
  • 0: Headset with microphone.
  • 1: Earpiece.
  • 2: Headset without microphone.
  • 3: Built-in speaker.
  • 4: (Not supported) External speaker.
  • 5: Bluetooth headset.
  • 6: USB device.

Return Values

  • 0: Success.
  • < 0: Failure.

onAudioRouteChanged

Callback when the local audio route changes.

public void onAudioRouteChanged(int routing) {}

Trigger Timing

This callback is triggered when the local audio route changes.

Parameters

routing
The current audio route.
  • AUDIO_ROUTE_DEFAULT (-1): Default audio route.
  • AUDIO_ROUTE_HEADSET (0): Headset with microphone.
  • AUDIO_ROUTE_EARPIECE (1): Earpiece.
  • AUDIO_ROUTE_HEADSETNOMIC (2): Headset without microphone.
  • AUDIO_ROUTE_SPEAKERPHONE (3): Built-in speaker.
  • AUDIO_ROUTE_LOUDSPEAKER (4): External speaker (reserved).
  • AUDIO_ROUTE_BLUETOOTH_DEVICE_HFP (5): Bluetooth device using HFP protocol.
  • AUDIO_ROUTE_BLUETOOTH_DEVICE_A2DP (10): Bluetooth device using A2DP protocol.

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.

Audio Device Management

getAudioDeviceInfo

Gets audio device information.

public abstract DeviceInfo getAudioDeviceInfo();
Note: You can call this method before or after joining a channel.

Return Values

If the method call succeeds, returns a DeviceInfo object. If the method call fails, returns null.

startPlaybackDeviceTest

Starts local audio playback device test.

public abstract int startPlaybackDeviceTest(String audioFileName);

After calling this method, the SDK plays the specified audio file. If you can hear the audio, it indicates that the playback device is working properly. After the call, the SDK triggers the onAudioVolumeIndication callback every 100 ms to report the volume information of the playback device with uid 1. The difference between this method and startEchoTest is that startPlaybackDeviceTest only tests the local audio playback device, while startEchoTest tests both audio/video devices and network conditions.

Note: Call this method before joining a channel. After the test is complete, call stopPlaybackDeviceTest before joining the channel to stop the test.

Parameters

audioFileName
Path to the audio file, a UTF-8 encoded string. Supported formats: wav, mp3, m4a, and aac. Supported sample rates: 8000, 16000, 32000, 44100, and 48000 Hz.

Return Values

  • 0: Success.
  • < 0: Failure.

startRecordingDeviceTest

Starts the audio recording device test.

public abstract int startRecordingDeviceTest(int indicationInterval);

After calling this method, the SDK triggers the onAudioVolumeIndication callback at the set interval, reporting uid = 0 and the volume of the recording device. This differs from startEchoTest in that startRecordingDeviceTest only checks the local recording device, while startEchoTest also checks video devices and network.

Note: Call this method before joining a channel. After the test, call stopRecordingDeviceTest before joining a channel to stop the test.

Parameters

indicationInterval
Interval (ms) for triggering onAudioVolumeIndication. Must be greater than 10, otherwise the callback won't be triggered and the SDK returns error -2. Recommended: 100.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameter. Check parameter settings.

stopPlaybackDeviceTest

Stops audio playback device test.

public abstract int stopPlaybackDeviceTest();

You need to call this method after calling startPlaybackDeviceTest to stop the test.

Note: Call this method before joining a channel.

Return Values

  • 0: Success.
  • < 0: Failure.

stopRecordingDeviceTest

Stops the audio recording device test.

public abstract int stopRecordingDeviceTest();

You must call this method after calling startRecordingDeviceTest to stop the audio recording device test.

Note: Call this method before joining a channel.

Return Values

  • 0: Success.
  • < 0: Failure.