Video Device Management
Introduces methods and callbacks related to video device management.
enumerateVideoDevices
Enumerates the video devices.
virtual IVideoDeviceCollection* enumerateVideoDevices() = 0;
This method returns a IVideoDeviceCollection object including all video devices in the system. With the IVideoDeviceCollection object, the application can enumerate video devices. The application must call the release method to release the returned object after using it.
Returns
- Success: A IVideoDeviceCollection object including all video devices in the system.
- Failure: NULL.
getCameraMaxZoomFactor
Gets the maximum zoom ratio supported by the camera.
virtual float getCameraMaxZoomFactor() = 0;
- This method is for Android and iOS only.
- Call this method after enabling the local camera, for example, by calling joinChannel [2/2], enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.
Returns
The maximum zoom factor.
getCapability
Gets the detailed video frame information of the video capture device in 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 specific video frame information supported by the specified index number.
Parameters
- deviceIdUTF8
- The ID of the video capture device.
- deviceCapabilityNumber
- The index number of the video format. If the return value of numberOfCapabilities is i, the value range of this parameter is [0,i).
- capability
- Output parameter. Indicates the specific information of the specified video format, including width (px), height (px), and frame rate (fps). See VideoFormat.
Returns
- 0: Success.
- < 0: Failure.
getCount
Gets the total number of the indexed video devices in the system.
virtual int getCount() = 0;
Returns
The total number of the indexed video devices in the system.
getDevice
Gets a specified piece of information about an indexed video device.
virtual int getDevice(int index,
char deviceName[MAX_DEVICE_ID_LENGTH],
char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
Parameters
- index
- The index value of the video device. The value of this parameter must be less than the value returned in getCount.
- deviceName
- The device name. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
- deviceId
- The device ID of the video device. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
Returns
- 0: Success.
- < 0: Failure.
getDevice
Retrieves the current video capture device.
virtual int getDevice(char deviceIdUTF8[MAX_DEVICE_ID_LENGTH]) = 0;
Parameters
- deviceIdUTF8
- Output parameter. The device ID. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
Returns
- 0: Success.
- < 0: Failure.
isCameraAutoExposureFaceModeSupported
Checks whether the device supports auto exposure.
virtual bool isCameraAutoExposureFaceModeSupported() = 0;
- This method applies to iOS only.
- Call this method after enabling the local camera, for example, by calling joinChannel [2/2], enableVideo, or enableLocalVideo,depending on which method you use to turn on your local camera.
Returns
true
: The device supports auto exposure.false
: The device does not support auto exposure.
isCameraAutoFocusFaceModeSupported
Checks whether the device supports the face auto-focus function.
virtual bool isCameraAutoFocusFaceModeSupported() = 0;
- This method is for Android and iOS only.
- Call this method after enabling the local camera, for example, by calling joinChannel [2/2], enableVideo, or enableLocalVideo,depending on which method you use to turn on your local camera.
Returns
true
: The device supports the face auto-focus function.false
: The device does not support the face auto-focus function.
isCameraExposurePositionSupported
Checks whether the device supports manual exposure.
virtual bool isCameraExposurePositionSupported() = 0;
- This method is for Android and iOS only.
- Call this method after enabling the local camera, for example, by calling joinChannel [2/2], enableVideo, or enableLocalVideo,depending on which method you use to turn on your local camera.
Returns
true
: The device supports manual exposure.false
: The device does not support manual exposure.
isCameraFaceDetectSupported
Checks whether the device camera supports face detection.
virtual bool isCameraFaceDetectSupported() = 0;
- This method is for Android and iOS only.
- Call this method after enabling the local camera, for example, by calling joinChannel [2/2], enableVideo, or enableLocalVideo,depending on which method you use to turn on your local camera.
Returns
true
: The device camera supports face detection.false
: The device camera does not support face detection.
isCameraFocusSupported
Check whether the device supports the manual focus function.
virtual bool isCameraFocusSupported() = 0;
- This method is for Android and iOS only.
- Call this method after enabling the local camera, for example, by calling joinChannel [2/2], enableVideo, or enableLocalVideo,depending on which method you use to turn on your local camera.
Returns
true
: The device supports the manual focus function.false
: The device does not support the manual focus function.
isCameraTorchSupported
Checks whether the device supports camera flash.
virtual bool isCameraTorchSupported() = 0;
- This method is for Android and iOS only.
- Call this method after enabling the local camera, for example, by calling joinChannel [2/2], enableVideo, or enableLocalVideo,depending on which method you use to turn on your local camera.
- The app enables the front camera by default. If your front camera does not support enabling the flash, this method returns false. If you want to check whether the rear camera supports the flash function, call switchCamera before this method.
- On iPads with system version 15, even if isCameraTorchSupported returns
true
, you might fail to successfully enable the flash by calling setCameraTorchOn due to system issues.
Returns
true
: The device supports enabling the flash.false
: The device does not support enabling the flash.
isCameraZoomSupported
Checks whether the device supports camera zoom.
virtual bool isCameraZoomSupported() = 0;
- This method is for Android and iOS only.
- Call this method after enabling the local camera, for example, by calling joinChannel [2/2], enableVideo, or enableLocalVideo,depending on which method you use to turn on your local camera.
Returns
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;
Video capture devices may support multiple video formats, and each format supports different combinations of video frame width, video frame height, and frame rate.
You can call this method to get how many video formats the specified video capture device can support, and then call getCapability to get the specific video frame information in the specified video format.
Parameters
- deviceIdUTF8
- The ID of the video capture device.
Returns
- 0: Success. Returns the number of video formats supported by this device. For example: If the specified camera supports 10 different video formats, the return value is 10.
- < 0: Failure.
release
Releases all the resources occupied by the IVideoDeviceCollection object.
virtual void release() = 0;
release
Releases all the resources occupied by the IVideoDeviceManager object.
virtual void release() = 0;
setCameraAutoExposureFaceModeEnabled
Sets whether to enable auto exposure.
virtual int setCameraAutoExposureFaceModeEnabled(bool enabled) = 0;
- This method applies to iOS only.
- Call this method before calling joinChannel [2/2], enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.
Parameters
- enabled
-
Whether to enable auto exposure:
true
: Enable auto exposure.false
: Disable auto exposure.
Returns
- 0: Success.
- < 0: Failure.
setCameraAutoFocusFaceModeEnabled
Sets whether to enable face autofocus.
virtual int setCameraAutoFocusFaceModeEnabled(bool enabled) = 0;
- This method is for Android and iOS only.
- Call this method after the camera is started, such as after joinChannel [2/2], enableVideo, or enableLocalVideo.
Parameters
- enabled
-
Whether to enable face autofocus:
true
: Enable face autofocus.false
: Disable face autofocus.
Returns
- 0: Success.
- < 0: Failure.
setCameraCapturerConfiguration
Sets the camera capture configuration.
virtual int setCameraCapturerConfiguration(const CameraCapturerConfiguration& config) = 0;
- This method is for Android and iOS only.
- Call this method before calling joinChannel [2/2], enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.
Parameters
- config
- The camera capturer configuration. See CameraCapturerConfiguration.
Returns
- 0: Success.
- < 0: Failure.
setCameraDeviceOrientation
Sets the rotation angle of the captured video.
virtual int setCameraDeviceOrientation(VIDEO_SOURCE_TYPE type, VIDEO_ORIENTATION orientation) = 0;
When the video capture device does not have the gravity sensing function, you can call this method to manually adjust the rotation angle of the captured video.
Parameters
- type
- The video source type. See VIDEO_SOURCE_TYPE.
- orientation
- The clockwise rotation angle. See VIDEO_ORIENTATION.
Returns
- 0: Success.
- < 0: Failure.
setCameraExposurePosition
Sets the camera exposure position.
virtual int setCameraExposurePosition(float positionXinView, float positionYinView) = 0;
This method needs to be called after the camera is started (for example, by calling startPreview [1/2] or joinChannel [2/2]).
After a successful method call, the SDK triggers the onCameraExposureAreaChanged callback.
Parameters
- positionXinView
- The horizontal coordinate of the touchpoint in the view.
- positionYinView
- The vertical coordinate of the touchpoint in the view.
Returns
- 0: Success.
- < 0: Failure.
setCameraFocusPositionInPreview
Sets the camera manual focus position.
virtual int setCameraFocusPositionInPreview(float positionX, float positionY) = 0;
This method needs to be called after the camera is started (for example, by calling startPreview [1/2] or joinChannel [2/2]). After a successful method call, the SDK triggers the onCameraFocusAreaChanged callback.
Parameters
- positionX
- The horizontal coordinate of the touchpoint in the view.
- positionY
- The vertical coordinate of the touchpoint in the view.
Returns
- 0: Success.
- < 0: Failure.
setCameraTorchOn
Enables the camera flash.
virtual int setCameraTorchOn(bool isOn) = 0;
- This method is for Android and iOS only.
- Call this method before calling joinChannel [2/2], enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.
Parameters
- isOn
-
Whether to turn on the camera flash:
true
: Turn on the flash.false
: (Default) Turn off the flash.
Returns
- 0: Success.
- < 0: Failure.
setCameraZoomFactor
Sets the camera zoom ratio.
virtual int setCameraZoomFactor(float factor) = 0;
- This method is for Android and iOS only.
- Call this method before calling joinChannel [2/2], enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.
Parameters
- The camera zoom ratio. The value ranges between 1.0 and the maximum zoom supported by the device. You can get the maximum zoom ratio supported by the device by calling the getCameraMaxZoomFactor method.
Returns
- The camera zoom factor value, if successful.
- < 0: Failure.
setDevice
Specifies a device with the device ID.
virtual int setDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
Parameters
- deviceId
- The device ID. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE. Plugging or unplugging the audio device does not change the value of deviceId.
Returns
- 0: Success.
- < 0: Failure.
setDevice
Specifies the video capture device with the device ID.
virtual int setDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
Parameters
- deviceId
-
The device ID. You can get the device ID by calling enumerateVideoDevices.
The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
Returns
- 0: Success.
- < 0: Failure.
switchCamera
Switches between front and rear cameras.
virtual int switchCamera() = 0;
This method needs to be called after the camera is started (for example, by calling startPreview [1/2] or joinChannel [2/2]).
Returns
- 0: Success.
- < 0: Failure.
onCameraExposureAreaChanged
Occurs when the camera exposure area changes.
virtual void onCameraExposureAreaChanged(int x, int y, int width, int height) { (void)x; (void)y; (void)width; (void)height; }
The SDK triggers this callback when the local user changes the camera exposure position by calling setCameraExposurePosition.
Parameters
- x
- The x coordinate of the changed camera exposure area.
- y
- The y coordinate of the changed camera exposure area.
- width
- The width of the changed camera exposure area.
- height
- The height of the changed exposure area.
onCameraFocusAreaChanged
Occurs when the camera focus area changes.
virtual void onCameraFocusAreaChanged(int x, int y, int width, int height) { (void)x; (void)y; (void)width; (void)height; }
Parameters
- x
- The x-coordinate of the changed camera focus area.
- y
- The y-coordinate of the changed camera focus area.
- width
- The width of the changed camera focus area.
- height
- The height of the changed camera focus area.
onCameraReady
Occurs when the camera turns on and is ready to capture the video.
virtual void onCameraReady()
- Deprecated:
-
Please use LOCAL_VIDEO_STREAM_STATE_CAPTURING(1) in onLocalVideoStateChanged instead.
This callback indicates that the camera has been successfully turned on and you can start to capture video.