Device Management

Audio Route

isSpeakerphoneEnabled

Checks whether the speaker is enabled.

virtual bool isSpeakerphoneEnabled() = 0;
Note: This method applies to Android and iOS only.

Timing

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

Return Values

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

setDefaultAudioRouteToSpeakerphone

Sets the default audio playback route.

virtual int setDefaultAudioRouteToSpeakerphone(bool defaultToSpeaker) = 0;
Most phones have two audio routes: the earpiece at the top and the speaker at the bottom. The earpiece has lower volume, while the speaker has higher volume. You can use this method to set whether to use the earpiece or speaker by default when no external audio device is connected. Default audio routes for different scenarios:
  • Voice call: Earpiece.
  • Audio live streaming: Speaker.
  • Video call: Speaker.
  • Video live streaming: Speaker.
Note: This method applies to Android and iOS only.

Timing

Call this method before joining a channel. To change the audio route after joining a channel, call setEnableSpeakerphone.

Related Callbacks

After this method is successfully called, the SDK triggers the onAudioRoutingChanged callback to report the current audio route.

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.

virtual int setEnableSpeakerphone(bool speakerOn) = 0;
Note: setEnableSpeakerphone only sets the audio route in 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 is used. If the user uses external audio playback devices such as Bluetooth or wired headsets, this method does not take effect. The SDK plays audio through the external device. When multiple external devices are connected, the SDK plays audio through the last connected device. This method applies to Android and iOS only.

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 this method is successfully called, the SDK triggers the onAudioRoutingChanged callback to report the current audio route.

Parameters

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

Return Values

  • 0: Success.
  • < 0: Failure.

setRouteInCommunicationMode

Sets the audio playback route in communication mode.

virtual int setRouteInCommunicationMode(int route) = 0;
Note: Using this method together with setEnableSpeakerphone may cause conflicts. It is recommended to use setRouteInCommunicationMode only. This method applies to Android only.

Timing

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

Related Callbacks

After this method is successfully called, the SDK triggers the onAudioRoutingChanged 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.

onAudioRoutingChanged

Callback triggered when the local audio routing changes.

virtual void onAudioRoutingChanged(int routing) { (void)routing; }
Note: This callback applies to Android, iOS, and macOS only.

Parameters

routing
Current audio routing. See AudioRoute.

Video Device Management

enableMultiCamera

Enables or disables multi-camera capture.

virtual int enableMultiCamera(bool enabled, const CameraCapturerConfiguration& config) = 0;
Agora recommends the following steps to use multiple cameras for video capture and publishing when a camera is already in use:
  1. Call this method to enable multi-camera capture.
  2. Call startPreview to start the local video preview.
  3. Call startCameraCapture and set sourceType to start capturing with the second camera.
  4. Call joinChannelEx and set publishSecondaryCameraTrack to true to publish the video stream captured by the second camera.
To disable multi-camera capture:
  1. Call stopCameraCapture.
  2. Call this method and set enabled to false.
This method is only available on iOS.Ensure the system version is 13.0 or later when using this feature.The minimum supported iOS device models for multi-camera capture are:
  • iPhone XR
  • iPhone XS
  • iPhone XS Max
  • iPad Pro (3rd generation and later)
Note: You can call this method to enable multi-camera capture either before or after calling startPreview:
  • If enabled before startPreview, the local preview displays the views from both cameras.
  • If enabled after startPreview, the SDK stops the current camera capture, then enables both the main and secondary cameras. The preview briefly turns black and then recovers automatically.

Parameters

enabled
Whether to enable multi-camera video capture mode:
  • true: Enable multi-camera capture. The SDK uses multiple cameras for video capture.
  • false: Disable multi-camera capture. The SDK uses a single camera for video capture.
config
Capture configuration for the second camera. See CameraCapturerConfiguration.

Return Values

  • 0: Success.
  • < 0: Failure.

enumerateVideoDevices

Enumerates video devices in the system.

virtual IVideoDeviceCollection* enumerateVideoDevices() = 0;

This method returns an IVideoDeviceCollection object that contains all available video devices in the system. You can use this object to enumerate video devices. After use, you must call the release method to free the resources.

Note: This method applies to Windows and macOS platforms only.

Return Values

getCameraMaxZoomFactor

Gets the maximum zoom factor supported by the camera.

virtual float getCameraMaxZoomFactor() = 0;
Note: This method applies to Android and iOS only. 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

Returns the maximum zoom factor supported by the camera if the method call succeeds.

getCapability

Retrieves frame information of the video capture device under the specified video format.

virtual int getCapability(const char* deviceIdUTF8, const uint32_t deviceCapabilityNumber, VideoFormat& capability) = 0;

After calling numberOfCapabilities to get the number of video formats supported by the video capture device, you can call this method to get the video frame information corresponding to the specified index.

Note: This method is only applicable on Windows and macOS platforms.

Parameters

deviceIdUTF8
ID of the video capture device.
deviceCapabilityNumber
Index of the video format. If the return value of numberOfCapabilities is i, the value range of this parameter is [0, i).
capability
An output parameter. Detailed information of the specified video format, including width (px), height (px), and frame rate (fps). See VideoFormat.

Return Values

  • 0: Success.
  • < 0: Failure.

getCount

Gets the total number of indexed video capture devices in the system.

virtual int getCount() = 0;

Return Values

If the method call succeeds, returns the total number of indexed video capture devices in the system.

getDevice

Gets information of the video device at the specified index.

virtual int getDevice(int index, char deviceNameUTF8[MAX_DEVICE_ID_LENGTH], char deviceIdUTF8[MAX_DEVICE_ID_LENGTH]) = 0;

Parameters

index
Index of the video device. This value must be less than the value returned by getCount.
deviceNameUTF8
Output parameter. The name of the device. Maximum length is MAX_DEVICE_ID_LENGTH.
deviceIdUTF8
Output parameter. The device ID of the video device. Maximum length is MAX_DEVICE_ID_LENGTH.

Return Values

  • 0: Success.
  • < 0: Failure.

getDevice

Gets the current video capture device.

virtual int getDevice(char deviceIdUTF8[MAX_DEVICE_ID_LENGTH]) = 0;
Note: This method applies to Windows and macOS platforms only.

Parameters

deviceIdUTF8
Output parameter. The device ID of the current video capture device.

Return Values

  • 0: Success.
  • < 0: Failure.

isCameraAutoFocusFaceModeSupported

Checks whether the device supports face auto-focus.

virtual bool isCameraAutoFocusFaceModeSupported() = 0;
Note: isCameraAutoFocusFaceModeSupported is only applicable to Android and iOS platforms. 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.

virtual bool isCameraExposurePositionSupported() = 0;
Since
Added since v2.3.2.
Note: isCameraExposurePositionSupported applies to Android and iOS only. 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 exposure adjustment.

virtual bool isCameraExposureSupported() = 0;
Since
Added since v4.2.2.
Note:
  • This method applies to Android and iOS only.
  • 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 exposure adjustment.
  • This method is used to adjust the exposure of the currently active camera, which is the one specified when calling setCameraCapturerConfiguration.

Return Values

  • true: Query succeeds.
  • false: Query fails.

isCameraFaceDetectSupported

Checks whether the device camera supports face detection.

virtual bool isCameraFaceDetectSupported() = 0;
Note: isCameraFaceDetectSupported is only applicable to Android and iOS platforms. 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 camera supports face detection. false: The device camera does not support face detection.

isCameraFocusSupported

Checks whether the device supports manual focus.

virtual bool isCameraFocusSupported() = 0;
Note: isCameraFocusSupported is only applicable to Android and iOS platforms. 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.

virtual bool isCameraTorchSupported() = 0;
Note: isCameraTorchSupported is only applicable to Android and iOS platforms. 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. If you want to check whether the rear camera supports torch, call switchCamera before calling this method. On iPads running iOS 15, even if isCameraTorchSupported returns true, due to system issues, calling setCameraTorchOn may fail to turn on the torch.

Return Values

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

isCameraZoomSupported

Checks whether the device supports camera zoom.

virtual bool isCameraZoomSupported() = 0;
Note: The isCameraZoomSupported method is only applicable to Android and iOS platforms.

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.

numberOfCapabilities

Gets the number of video formats supported by the specified video capture device.

virtual int numberOfCapabilities(const char* deviceIdUTF8) = 0;

You can call this method to get the number of video formats supported by the specified video capture device, and then call getCapability to get the corresponding video frame information. The video capture device may support multiple video formats, each with different combinations of frame width, height, and frame rate.

Note: This method applies to Windows and macOS platforms only.

Parameters

deviceIdUTF8
ID of the video capture device.

Return Values

  • > 0: Method call succeeds and returns the number of video formats supported by the device. For example, if the specified camera supports 10 different video formats, the return value is 10.
  • ≤ 0: Method call fails.

queryCameraFocalLengthCapability

Queries the focal length capabilities supported by the camera.

virtual int queryCameraFocalLengthCapability(agora::rtc::FocalLengthInfo* focalLengthInfos, int& size) = 0;

If you want to enable wide-angle or ultra-wide-angle mode during video capture, it is recommended to call this method first to check whether the device supports the required focal length capability. Then, based on the query result, call the setCameraCapturerConfiguration method to adjust the camera's focal length configuration for optimal video capture performance.

Note: This method is only available on Android and iOS platforms.

Parameters

focalLengthInfos
Input and output parameter. A pointer to an array of FocalLengthInfo objects. After the method is executed, it is filled with the queried focal length information. See FocalLengthInfo.
size
Input and output parameter. Indicates the number of focal length info items. On input, specify the maximum number of focal length info items that focalLengthInfos can hold. This value should be no less than 8. On output, returns the actual number of focal length info items retrieved.

Return Values

  • 0: Success.
  • < 0: Failure.

queryCodecCapability

Queries the video codec capabilities supported by the SDK.

virtual int queryCodecCapability(CodecCapInfo* codecInfo, int& size) = 0;

Parameters

codecInfo
Input and output parameter representing the array of video codec capabilities supported by the SDK. You pass a CodecCapInfo array when calling this method to indicate the video codec capabilities to query. After execution, the array is filled with the actual video codec capabilities supported by the SDK. See CodecCapInfo.
size
Input and output parameter representing the size of the codecInfo array. You pass in the size of codecInfo when calling this method. After execution, this value is updated to the actual size of the returned codecInfo array.

Return Values

  • 0: Success.
  • < 0: Failure.

release

Releases all resources occupied by the IVideoDeviceManager object.

virtual void release() = 0;
Note: This method is only applicable on Windows and macOS platforms.

setCameraAutoExposureFaceModeEnabled

Sets whether to enable auto exposure.

virtual int setCameraAutoExposureFaceModeEnabled(bool enabled) = 0;
Note: This method applies to iOS only. You must call this method after calling enableVideo. The setting takes effect after the camera is successfully started, that is, when the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1).

Parameters

enabled
Whether to enable auto exposure:
  • true: Enable auto exposure.
  • false: Disable auto exposure.

Return Values

  • 0: Success.
  • < 0: Failure.

setCameraAutoFocusFaceModeEnabled

Enables the camera auto-face focus function.

virtual int setCameraAutoFocusFaceModeEnabled(bool enabled) = 0;

By default, the SDK disables auto-face focus on Android and enables it on iOS. You can call this method to enable or disable the auto-face focus function.

Note: This method applies to Android and iOS only.

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 auto-face focus:
  • true: Enable auto-face focus.
  • false: Disable auto-face focus.

Return Values

  • 0: Success.
  • < 0: Failure.

setCameraCapturerConfiguration

Sets the camera capture configuration.

virtual int setCameraCapturerConfiguration(const CameraCapturerConfiguration& config) = 0;

Call this method before enabling local camera capture, for example, before calling startPreview or joinChannel.

Note: To adjust the camera focal length configuration, it is recommended to call queryCameraFocalLengthCapability to query the focal length capability of the device and configure it accordingly. Due to limitations on some Android devices, the configuration may not take effect even if the focal length type is set based on the result returned by queryCameraFocalLengthCapability.

Timing

Call this method before enabling local camera capture, for example, before calling startPreview or joinChannel.

Parameters

config
Camera capture configuration. See CameraCapturerConfiguration.
Note: You do not need to set the deviceId parameter in this method.

Return Values

  • 0: Success.
  • < 0: Failure.

setCameraDeviceOrientation

Sets the rotation angle of captured video.

virtual int setCameraDeviceOrientation(VIDEO_SOURCE_TYPE type, VIDEO_ORIENTATION orientation) = 0;
Note: This method is for Windows only. 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). When the video capture device does not support gravity sensing, you can call this method to manually adjust the rotation angle of the captured video.

Parameters

type
Type of video source. See VIDEO_SOURCE_TYPE.
orientation
Clockwise rotation angle. See VIDEO_ORIENTATION.

Return Values

  • 0: Success.
  • < 0: Failure.

setCameraExposureFactor

Sets the camera exposure value.

virtual int setCameraExposureFactor(float factor) = 0;
Since
Added since v4.2.2.
Note:
  • This method applies to Android and iOS only.
  • You must call this method after calling enableVideo. The setting takes effect after the camera is successfully started, that is, when 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 exposure adjustment.
  • This method is used to adjust the exposure value of the currently active camera, which is the one specified when calling setCameraCapturerConfiguration.

Parameters

factor
The camera exposure value. The default value is 0, which means using the camera's default exposure. The higher the value, the stronger the exposure. Lower the value when the image is overexposed; increase when underexposed and details in dark areas are lost. If the value exceeds the supported range, the SDK automatically adjusts it to a valid range.
Note:
  • On Android, the range is [-20.0, 20.0].
  • On iOS, the range is [-8.0, 8.0].

Return Values

  • 0: Success.
  • < 0: Failure.

setCameraExposurePosition

Sets the camera exposure position.

virtual int setCameraExposurePosition(float positionXinView, float positionYinView) = 0;
Since
Added since v2.3.2.
Note:
  • setCameraExposurePosition applies to Android and iOS only.
  • You must call this method after calling enableVideo.
  • The setting takes effect after the camera is successfully started, that is, when the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1).

Related Callbacks

After this method is successfully called, 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.

virtual int setCameraFocusPositionInPreview(float positionX, float positionY) = 0;

You must call this method after calling enableVideo. The setting takes effect after the camera is successfully started, that is, when the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1). After a successful call, the SDK triggers the onCameraFocusAreaChanged callback.

Note: This method applies to Android and iOS only.

Related Callbacks

After this method is successfully called, 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.

virtual int setCameraTorchOn(bool isOn) = 0;
Note: setCameraTorchOn applies to Android and iOS only. You must call this method after calling enableVideo. The setting takes effect after the camera is successfully started, that is, when 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.

virtual int setCameraZoomFactor(float factor) = 0;

For iOS devices with multiple rear cameras, such as dual (wide and ultra-wide) or triple (wide, ultra-wide, and telephoto) cameras, you can first call setCameraCapturerConfiguration and set cameraFocalLengthType to CAMERA_FOCAL_LENGTH_DEFAULT (0) (standard lens), then set the zoom factor to a value less than 1.0 to achieve ultra-wide-angle video capture.

Note:
  • This method is only applicable to Android and iOS platforms.
  • You must call this method after calling enableVideo. The setting takes effect after the camera is successfully enabled, that is, after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LOCAL_VIDEO_STREAM_STATE_CAPTURING (1).

Parameters

factor
The camera zoom factor. You can call getCameraMaxZoomFactor to get the maximum zoom factor supported by the device.
Note: For devices that do not support ultra-wide-angle, the value ranges from 1.0 to the maximum zoom factor supported by the device; for devices that support ultra-wide-angle, the value ranges from 0.5 to the maximum zoom factor supported by the device.

Return Values

  • 0: Success. Returns the set camera zoom factor.
  • < 0: Failure.

setDevice

Specifies the device corresponding to the device ID.

virtual int setDevice(const char deviceIdUTF8[MAX_DEVICE_ID_LENGTH]) = 0;

Parameters

deviceIdUTF8
Device ID. Plugging or unplugging audio devices does not change this value.

Return Values

  • 0: Success.
  • < 0: Failure.

setDevice

Specifies the device ID of the video capture device.

virtual int setDevice(const char deviceIdUTF8[MAX_DEVICE_ID_LENGTH]) = 0;

Parameters

deviceIdUTF8
Device ID. You can get this value by calling enumerateVideoDevices. Maximum length is MAX_DEVICE_ID_LENGTH.

Return Values

  • 0: Success.
  • < 0: Failure.

switchCamera

Switches between front and rear cameras.

virtual int switchCamera() = 0;

You can call this method to dynamically switch between the front and rear cameras based on the available cameras during app runtime, without restarting the video stream or reconfiguring the video source.

Note:
  • This method only switches the camera for the video stream captured by the first camera, that is, the video stream whose source is set to VIDEO_SOURCE_CAMERA (0) when calling startCameraCapture.
  • This method is only applicable to Android and iOS platforms.

Timing

You must call this method after the camera is successfully enabled, that is, 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.

onCameraExposureAreaChanged

Callback for changes in camera exposure area.

virtual void onCameraExposureAreaChanged(int x, int y, int width, int height)

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

Note: This callback is only applicable to Android and iOS platforms.

Parameters

x
The x coordinate of the new exposure area.
y
The y coordinate of the new exposure area.
width
The width of the new exposure area.
height
The height of the new exposure area.

onCameraFocusAreaChanged

onCameraFocusAreaChanged callback. Triggered when the camera focus area changes.

virtual void onCameraFocusAreaChanged(int x, int y, int width, int height)
Note: This callback is only applicable to Android and iOS platforms.

Parameters

x
The x coordinate of the new focus area.
y
The y coordinate of the new focus area.
width
The width of the new focus area.
height
The height of the new focus area.

onCameraReady

onCameraReady callback: Triggered when the camera is turned on and ready to capture video.

virtual void onCameraReady() __deprecated {}
Deprecated
This method is deprecated. Use LOCAL_VIDEO_STREAM_STATE_CAPTURING in onLocalVideoStateChanged instead.

onVideoDeviceStateChanged

Callback for video device state changes.

virtual void onVideoDeviceStateChanged(const char* deviceId, int deviceType, int deviceState)

This callback reports changes in the system video device state, such as when a device is unplugged or removed. On Windows devices, if an external camera is used for video capture and is unplugged, the video function will be disabled.

Note: This callback applies to Windows and macOS only.

Parameters

deviceId
Device ID.
deviceType
Media device type. See MEDIA_DEVICE_TYPE.
deviceState
Media device state. See MEDIA_DEVICE_STATE_TYPE.

Audio Device Management

enumeratePlaybackDevices

Enumerates audio playback devices in the system.

virtual IAudioDeviceCollection *enumeratePlaybackDevices() = 0;

This method returns an IAudioDeviceCollection object that contains all audio playback devices in the system. After using the object, you must call the release method to free the resources.

Note: This method is only applicable to Windows and macOS platforms.

Return Values

enumerateRecordingDevices

Enumerates audio recording devices.

virtual IAudioDeviceCollection *enumerateRecordingDevices() = 0;

This method returns an IAudioDeviceCollection object that contains all audio recording devices in the system. After using the object, you must call the release method to free the resources.

Note: This method is only applicable to Windows and macOS platforms.

Return Values

followSystemLoopbackDevice

Sets whether to follow the system default audio playback device.

virtual int followSystemLoopbackDevice(bool enable) = 0;

This method is only applicable on Windows and macOS platforms.

Parameters

enable
Whether to follow the system default audio playback device:
  • true: Follow the system default audio playback device. When the system default playback device changes, the SDK immediately switches to the corresponding sound card capture device.
  • false: Do not follow the system default audio playback device. The SDK switches the sound card capture device to the system default audio playback device only when the current audio playback device is disconnected.

Return Values

  • 0: Success.
  • < 0: Failure.

followSystemPlaybackDevice

Sets whether the SDK follows the system default audio playback device.

virtual int followSystemPlaybackDevice(bool enable) = 0;
Note: This method is only applicable to Windows and macOS platforms.

Parameters

enable
Whether to follow the system default audio playback device:
  • true: Follow the system default audio playback device. When the system default playback device changes, the SDK immediately switches the playback device.
  • false: Do not follow the system default audio playback device. The SDK only switches to the system default playback device when the current one is disconnected.

Return Values

  • 0: The method call succeeds.
  • < 0: The method call fails.

followSystemRecordingDevice

Sets whether the SDK follows the system default audio recording device.

virtual int followSystemRecordingDevice(bool enable) = 0;
Note: This method is only applicable to Windows and macOS platforms.

Parameters

enable
Whether to follow the system default audio recording device:
  • true: Follow the system default audio recording device. When the system default device changes, the SDK immediately switches.
  • false: Do not follow the system default audio recording device. The SDK only switches to the system default device when the current one is disconnected.

Return Values

  • 0: The method call succeeds.
  • < 0: The method call fails.

getApplicationVolume

Retrieves the app volume.

virtual int getApplicationVolume(int &volume) = 0;

Parameters

volume
Output parameter. Indicates the app volume, in the range [0, 255].

Return Values

  • 0: Success.
  • < 0: Failure.

getAudioDeviceInfo

Retrieves audio device information.

virtual int getAudioDeviceInfo(DeviceInfo& deviceInfo) = 0;

Call this method to check whether the audio device supports ultra-low latency capture and playback.

Note:
  • This method is only applicable to Android.
  • You can call this method either before or after joining a channel.

Parameters

deviceInfo
Input and output parameter representing the audio device information. See DeviceInfo.

Return Values

  • 0: Success.
  • < 0: Failure.

getCount

Gets the total number of audio playback or audio capture devices.

virtual int getCount() = 0;

If you call enumeratePlaybackDevices before this method, the SDK returns the number of audio playback devices; if you call enumerateRecordingDevices before this method, the SDK returns the number of audio capture devices.

Return Values

Returns the total number of audio playback or audio capture devices if the method call succeeds.

getDefaultDevice [2/2]

Retrieves the system default audio device and its type.

virtual int getDefaultDevice(char deviceName[MAX_DEVICE_ID_LENGTH], char deviceTypeName[MAX_DEVICE_ID_LENGTH], char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

This method is applicable to macOS only. Before calling this method, you need to call enumeratePlaybackDevices or enumerateRecordingDevices to retrieve the device list.

Parameters

deviceName
Output parameter. The name of the system default audio device.
deviceTypeName
Output parameter. The type of the audio device, such as built-in, USB, or HDMI.
deviceId
Output parameter. The device ID of the system default audio device.

Return Values

  • 0: Success.
  • < 0: Failure.

getDefaultDevice [1/2]

Retrieves the system default audio device.

virtual int getDefaultDevice(char deviceName[MAX_DEVICE_ID_LENGTH], char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

Parameters

deviceName
Output parameter. The name of the system default audio device.
deviceId
Output parameter. The device ID of the system default audio device.

Return Values

  • 0: Success.
  • < 0: Failure.

getDevice [2/2]

Gets the name, type, and ID of the audio device by index.

virtual int getDevice(int index, char deviceName[MAX_DEVICE_ID_LENGTH], char deviceTypeName[MAX_DEVICE_ID_LENGTH], char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
Note: This method is for macOS only.

Parameters

index
The index of the device.
deviceName
Output parameter. The name of the device.
deviceTypeName
Output parameter. The type of the audio device, such as built-in, USB, or HDMI.
deviceId
Output parameter. The ID of the device.

Return Values

  • 0: Success.
  • < 0: Failure.

getDevice [1/2]

Gets the information of the video device at the specified index.

virtual int getDevice(int index, char deviceName[MAX_DEVICE_ID_LENGTH], char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

Parameters

index
The index of the video device. This value must be less than the number of devices returned by getCount.
deviceName
Output parameter. The name of the device. Maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
deviceId
Output parameter. The device ID of the video device. Maximum length is MAX_DEVICE_ID_LENGTH_TYPE.

Return Values

  • 0: Success.
  • < 0: Failure.

getLoopbackDevice

Gets the current loopback capture device.

virtual int getLoopbackDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

This method is for Windows and macOS only.

Parameters

deviceId
Output parameter. The ID of the current loopback capture device.

Return Values

  • 0: Success.
  • < 0: Failure.

getPlaybackDevice

Retrieves the audio playback device associated with the device ID.

virtual int getPlaybackDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
Note: This method is applicable to Windows and macOS only.

Parameters

deviceId
Output parameter. The device ID of the audio playback device.

Return Values

  • 0: Success.
  • < 0: Failure.

getPlaybackDeviceInfo [1/2]

Retrieves information of the audio playback device.

virtual int getPlaybackDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH]) = 0;
Note: This method is applicable to Windows and macOS only.

Parameters

deviceId
The ID of the audio playback device. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
deviceName
Output parameter. The name of the playback device. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.

Return Values

  • 0: Success.
  • < 0: Failure.

getPlaybackDeviceInfo [2/2]

Retrieves the information and type of the audio playback device.

virtual int getPlaybackDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH], char deviceTypeName[MAX_DEVICE_ID_LENGTH]) = 0;

This method is applicable to macOS only.

Parameters

deviceId
The ID of the audio playback device.
deviceName
Output parameter. The name of the playback device.
deviceTypeName
Output parameter. The type of the audio playback device, such as built-in, USB, and HDMI.

Return Values

  • 0: Success.
  • < 0: Failure.

getPlaybackDeviceMute

Gets the mute status of the audio playback device.

virtual int getPlaybackDeviceMute(bool *mute) = 0;

Parameters

mute
Output parameter. Indicates whether the audio playback device is muted.
  • true: The audio playback device is muted.
  • false: The audio playback device is not muted.

Return Values

  • 0: Success.
  • < 0: Failure.

getPlaybackDeviceVolume

Retrieves the volume of the audio playback device.

virtual int getPlaybackDeviceVolume(int *volume) = 0;

Parameters

volume
Output parameter. The volume of the audio playback device, ranging from [0, 255].

Return Values

  • 0: Success.
  • < 0: Failure.

getRecordingDevice

Gets the device ID of the current audio recording device.

virtual int getRecordingDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
Note: This method is applicable to Windows and macOS only.

Parameters

deviceId
Output parameter. The device ID of the current audio recording device.

Return Values

  • 0: Success.
  • < 0: Failure.

getRecordingDeviceInfo [1/2]

Gets information about the audio recording device.

virtual int getRecordingDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH]) = 0;
Note: This method is applicable to Windows and macOS only.

Parameters

deviceId
The ID of the audio recording device.
deviceName
Output parameter. The name of the recording device.

Return Values

  • 0: Success.
  • < 0: Failure.

getRecordingDeviceInfo [2/2]

Gets the information and type of the audio recording device.

virtual int getRecordingDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH], char deviceTypeName[MAX_DEVICE_ID_LENGTH]) = 0;

This method is applicable to macOS only.

Parameters

deviceId
The ID of the audio playback device, with a maximum length of MAX_DEVICE_ID_LENGTH_TYPE.
deviceName
Output parameter. The name of the playback device, with a maximum length of MAX_DEVICE_ID_LENGTH_TYPE.
deviceTypeName
Output parameter. The type of the audio recording device, such as built-in, USB, or HDMI, with a maximum length of MAX_DEVICE_ID_LENGTH_TYPE.

Return Values

  • 0: Success.
  • < 0: Failure.

getRecordingDeviceMute

Gets the mute state of the audio recording device.

virtual int getRecordingDeviceMute(bool *mute) = 0;

Parameters

mute
Output parameter that indicates whether the audio recording device is muted. The default value is false.
  • true: The microphone is muted.
  • false: The microphone is not muted.

Return Values

  • 0: Success.
  • < 0: Failure.

getRecordingDeviceVolume

Gets the volume of the audio recording device.

virtual int getRecordingDeviceVolume(int *volume) = 0;
Note: This method is for Windows only.

Parameters

volume
Output parameter. Indicates the volume of the audio recording device, ranging from [0, 255].

Return Values

  • 0: Success.
  • < 0: Failure.

isApplicationMute

Checks whether the app is muted.

virtual int isApplicationMute(bool &mute) = 0;

Parameters

mute
An output parameter. Indicates whether the app is muted:
  • true: The app is muted.
  • false: The app is not muted.

Return Values

  • 0: Success.
  • < 0: Failure.

setApplicationMute

Sets whether the app is muted.

virtual int setApplicationMute(bool mute) = 0;

Parameters

mute
Whether to mute the app:
  • true: Mute the app.
  • false: Unmute the app.

Return Values

  • 0: Success.
  • < 0: Failure.

setApplicationVolume

Sets the application volume.

virtual int setApplicationVolume(int volume) = 0;

Parameters

volume
The application volume. The range is [0, 255].

Return Values

  • 0: Success.
  • < 0: Failure.

setDevice

Specifies the device ID of the video capture device.

virtual int setDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
Note:
  • Plugging or unplugging a device does not change its device ID.
  • This method is for Windows and macOS only.

Parameters

deviceId
The device ID. You can get it by calling enumerateVideoDevices.
Note: Maximum length is MAX_DEVICE_ID_LENGTH_TYPE.

Return Values

  • 0: Success.
  • < 0: Failure.

setLoopbackDevice

Sets the SDK's loopback capture device.

virtual int setLoopbackDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

By default, the SDK uses the current playback device as the loopback capture device. If you want to specify another audio device as the loopback capture device, you can call this method and set deviceId to the target device. You can use this method to change the current audio routing without changing the default audio routing. For example, if the default audio routing is the microphone, and you call this method to set the audio routing to the loopback device and start device testing before joining a channel, the SDK will perform the test on the loopback device. After the test is complete and you join the channel, the SDK will still use the microphone for audio capture.

Note: This method is for Windows and macOS only.

Scenario

Typical scenarios for using this method include: App A plays music via Bluetooth headset while App B makes a video call and plays audio through the speaker:
  • If the loopback capture device is set to the Bluetooth headset, the SDK will publish the music played by App A to the remote end.
  • If the loopback capture device is set to the speaker, the SDK will not publish the music played by App A to the remote end.
  • If the loopback capture device is first set to the Bluetooth headset, and then App A switches to a wired headset for music playback, you need to call this method again to set the loopback capture device to the wired headset so that the SDK continues to publish the music to the remote end.

Parameters

deviceId
Specifies the SDK's loopback capture device. You can get the device ID by calling enumeratePlaybackDevices. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.

Return Values

  • 0: Success.
  • < 0: Failure.

setPlaybackDevice

Sets the audio playback device.

virtual int setPlaybackDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

You can call this method to change the currently used audio route, but it does not change the default audio route. For example, if the default audio route is speaker 1, and you call this method before joining a channel to set the audio route to speaker 2 and start the device test, the SDK performs the device test on speaker 2. After the device test is completed and you join the channel, the SDK still uses the default audio route speaker 1.

Note: This method is only applicable to Windows and macOS platforms.

Parameters

deviceId
The ID of the audio playback device. You can get the device ID by calling enumeratePlaybackDevices. Connecting or disconnecting an audio device does not change the value of deviceId.
Note: Maximum length is MAX_DEVICE_ID_LENGTH_TYPE.

Return Values

  • 0: Success.
  • < 0: Failure.

setPlaybackDeviceMute

Sets whether to mute the audio playback device.

virtual int setPlaybackDeviceMute(bool mute) = 0;

Parameters

mute
Whether to mute the audio playback device:
  • true: Mute the audio playback device.
  • false: Unmute the audio playback device.

Return Values

  • 0: Success.
  • < 0: Failure.

setPlaybackDeviceVolume

Sets the volume of the audio playback device.

virtual int setPlaybackDeviceVolume(int volume) = 0;
Note: This method is applicable to Windows only.

Parameters

volume
The volume of the audio playback device, ranging from [0,255].

Return Values

  • 0: Success.
  • < 0: Failure.

setRecordingDevice

Sets the audio recording device.

virtual int setRecordingDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;

You can call this method to change the currently used audio route, but it does not change the default audio route. For example, if the default audio route is the microphone, calling this method before joining a channel to set the audio route to a Bluetooth headset and starting a device test will cause the SDK to perform the test on the Bluetooth headset. After the test is completed and the channel is joined, the SDK will still use the microphone for audio capture.

Note: This method is applicable to Windows and macOS only.

Parameters

deviceId
The ID of the audio recording device. You can get the device ID by calling enumerateRecordingDevices. Connecting or disconnecting audio devices does not change the value of deviceId.

Return Values

  • 0: Success.
  • < 0: Failure.

setRecordingDeviceMute

Sets the mute state of the audio recording device.

virtual int setRecordingDeviceMute(bool mute) = 0;

Parameters

mute
Whether to mute the audio recording device:
  • true: Mute the audio recording device.
  • false: Unmute the audio recording device.

Return Values

  • 0: Success.
  • < 0: Failure.

setRecordingDeviceVolume

Sets the volume of the audio recording device.

virtual int setRecordingDeviceVolume(int volume) = 0;

This method is applicable to Windows and macOS only.

Parameters

volume
The volume of the audio recording device, ranging from [0, 255]. 0 means mute, and 255 means maximum volume.

Return Values

  • 0: Success.
  • < 0: Failure.

startAudioDeviceLoopbackTest

Starts the audio device loopback test.

virtual int startAudioDeviceLoopbackTest(int indicationInterval) = 0;

This method tests whether the local audio capturing and playback devices are working properly. After calling this method, the audio capturing device collects local audio, and the playback device plays the captured audio. The SDK triggers two separate onAudioVolumeIndication callbacks at the specified time interval, reporting the volume information of the capturing device (uid = 0) and the playback device (uid = 1).

Note:
  • This method is only applicable to Windows and macOS platforms.
  • You can call this method before or after joining a channel.
  • This method only takes effect when called by a host.
  • This method only tests local audio devices and does not involve network conditions.
  • After the test is complete, call stopAudioDeviceLoopbackTest to stop the audio device loopback test.

Parameters

indicationInterval
The time interval (ms) at which the SDK triggers the onAudioVolumeIndication callback. It is recommended to set this value to greater than 200 ms. This value cannot be less than 10 ms; otherwise, you will not receive the onAudioVolumeIndication callback.

Return Values

  • 0: The method call succeeds.
  • < 0: The method call fails.

startPlaybackDeviceTest

Starts a local audio playback device test.

virtual int startPlaybackDeviceTest(const char *testAudioFilePath) = 0;

This method tests whether the local audio playback device is working properly. After you call this method, the SDK plays the specified audio file. If you can hear the sound, the playback device is working properly. After this method is called, the SDK triggers the onAudioVolumeIndication callback every 100 ms, reporting the volume information of uid = 1 and the playback device. 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 to stop the test before joining a channel.

Parameters

testAudioFilePath
The path of the audio file, a UTF-8 encoded string. Supported file formats include wav, mp3, m4a, and aac. Supported sampling rates include 8000, 16000, 32000, 44100, and 48000 Hz.

Return Values

  • 0: Success.
  • < 0: Failure.

startRecordingDeviceTest

Starts an audio recording device test.

virtual int startRecordingDeviceTest(int indicationInterval) = 0;

Call this method to test whether the local audio recording device is working properly. After the call, the SDK triggers the onAudioVolumeIndication callback at the specified interval, reporting the volume information of the recording device with uid 0. This method only tests the local audio recording device, while the startEchoTest method can also test audio/video devices and network conditions.

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

Parameters

indicationInterval
The time interval (ms) for triggering the onAudioVolumeIndication callback. This value must be greater than 10. Otherwise, the onAudioVolumeIndication callback will not be received and the SDK returns error code -2. A value of 100 is recommended.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameter. Please check the parameter settings.

stopAudioDeviceLoopbackTest

Stops the audio device loopback test.

virtual int stopAudioDeviceLoopbackTest() = 0;
Note: The stopAudioDeviceLoopbackTest method is only applicable to Windows and macOS platforms. You can call this method before or after joining a channel. This method only takes effect when called by a host. After calling the startAudioDeviceLoopbackTest method to start the loopback test, make sure to call this method to stop the loopback test.

Return Values

  • 0: The method call succeeds.
  • < 0: The method call fails.

stopPlaybackDeviceTest

Stops the audio playback device test.

virtual int stopPlaybackDeviceTest() = 0;

After calling startPlaybackDeviceTest to start the test, you must call this method to stop the test.

Note: Call this method before joining a channel.

Return Values

  • 0: Success.
  • < 0: Failure.

stopRecordingDeviceTest

Stops the audio capturing device test.

virtual int stopRecordingDeviceTest() = 0;

After calling startRecordingDeviceTest to start the audio capturing device test, you must call this method to stop the test.

Note: Call this method before joining a channel.

Return Values

  • 0: The method call succeeds.
  • < 0: The method call fails.

onAudioDeviceStateChanged

Callback when the audio device state changes.

virtual void onAudioDeviceStateChanged(const char* deviceId, int deviceType, int deviceState)

This callback notifies when the state of an audio device changes, for example, when a headset is unplugged from the device.

Note: This method is available on Windows and macOS only.

Parameters

deviceId
Device ID.
deviceType
Device type. See MEDIA_DEVICE_TYPE.
deviceState
Device state. See MEDIA_DEVICE_STATE_TYPE.

onAudioDeviceVolumeChanged

Callback triggered when the audio device or app volume changes.

virtual void onAudioDeviceVolumeChanged(MEDIA_DEVICE_TYPE deviceType, int volume, bool muted)
Note: This callback applies to Windows and macOS only.

Parameters

deviceType
Type of device. See MEDIA_DEVICE_TYPE.
volume
Volume value, range [0, 255].
muted
Whether the audio device is muted:
  • true: The audio device is muted.
  • false: The audio device is not muted.