Face Detection

enableFaceDetection

Enables or disables face detection for the local user.

virtual int enableFaceDetection(bool enabled) = 0;
Note: This method is only applicable to Android and iOS platforms.

Timing

Call this method after calling startPreview or enableVideo to enable the camera.

Related Callbacks

After successfully calling this method, the SDK triggers the onFacePositionChanged callback to report the local user's face information, including:
  • Width and height of the local video.
  • Position of the face in the local view.
  • Distance between the face and the screen.

Parameters

enabled
Whether to enable face detection for the local user:
  • true: Enable face detection.
  • false: (Default) Disable face detection.

Return Values

  • 0: Success.
  • < 0: Failure.

onFacePositionChanged

Reports the local user's face detection results.

virtual void onFacePositionChanged(int imageWidth, int imageHeight, const Rectangle* vecRectangle, const int* vecDistance, int numFaces)
After calling enableFaceDetection to enable face detection, you can get the following information about the local user in real time:
  • Width and height of the local video.
  • Position of the face in the local view.
  • Distance between the face and the screen.
This distance is calculated based on the fitting of the local video size and face position.
Note:
  • This callback is only applicable to Android and iOS platforms.
  • This callback is triggered immediately when the face in front of the camera disappears. When no face is detected, the callback frequency is reduced to save local device power.
  • When the face is close to the screen, the SDK stops triggering this callback.
  • On Android, the distance value reported in this callback may differ from the actual distance. Therefore, Agora does not recommend using it for precise calculations.

Trigger Timing

Triggered when a change in face position is detected.

Parameters

imageWidth
The width (in pixels) of the video image captured by the local camera.
imageHeight
The height (in pixels) of the video image captured by the local camera.
vecRectangle
An array of length numFaces, representing detected face information:
  • x: The x coordinate (in pixels) of the face in the local view, with the top-left corner as the origin, indicating the horizontal position relative to the origin.
  • y: The y coordinate (in pixels) of the face in the local view, with the top-left corner as the origin, indicating the vertical position relative to the origin.
  • width: The width (in pixels) of the face in the capture view.
  • height: The height (in pixels) of the face in the capture view. See Rectangle.
vecDistance
An array of length numFaces, representing the distance (in centimeters) between each face and the device screen.
numFaces
The number of detected faces. A value of 0 indicates no face detected.