# 使用面部捕捉插件 (/zh-CN/realtime-media/rtc/build/extensions/face-capture/android) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文介绍如何使用面部捕捉插件驱动虚拟人。面部捕捉插件可以获取人脸面部特征点、头部旋转、头部平移量等量化数据,用于驱动人脸 3D 贴纸、头套、挂件应用或数字人,为虚拟形象注入更生动的表情元素。 本文适用于独立使用面部捕捉插件获取人脸数据,并使用第三方渲染引擎驱动虚拟人的场景。 ## 前提条件 [#前提条件] 在开始使用面部捕捉插件前,请确保开发环境满足以下要求: - 确保已集成 4.3.0 及以上版本 SDK,且包含面部捕捉插件动态库 `libagora_face_capture_extension.so`。 - 确保你已经在项目中实现了基本的实时音视频功能,详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。 - 已联系[声网技术支持](https://ticket.shengwang.cn/)获取面部捕捉鉴权参数:`authentication_information` 和 `company_id`。 ## 实现流程 [#实现流程] 本节介绍使用面部捕捉插件的基本流程。 ### 开启面部捕捉插件 [#开启面部捕捉插件] 调用 [`enableExtension`](/zh-CN/api-reference/rtc/android/extension#enableextension) 以启用面部捕捉插件。 :::info[信息] - 首次启用面部捕捉插件会产生一定的延迟,为保证频道内使用面部捕捉功能的流畅性,建议首次调用 [`enableExtension`](/zh-CN/api-reference/rtc/android/extension#enableextension) 的时机控制在加入频道前。 - 启用面部捕捉的媒体源(即参数 `sourceType`)仅支持设为 `PRIMARY_CAMERA_SOURCE`(默认)或 `CUSTOM_VIDEO_SOURCE`。 ::: ```java rtcEngine.enableExtension("agora_video_filters_face_capture", "face_capture", true, Constants.MediaSourceType.PRIMARY_CAMERA_SOURCE ); ``` ### 设置面部捕捉插件鉴权参数 [#设置面部捕捉插件鉴权参数] 调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/android/extension#setextensionproperty) 设置鉴权参数以确保插件正常运行。 ```java rtcEngine.setExtensionProperty( "agora_video_filters_face_capture", "face_capture", "authentication_information", "{\"company_id\":\"xxxxx\",\"license\":\"xxxxx\"}", Constants.MediaSourceType.PRIMARY_CAMERA_SOURCE ); ``` ### 获取面部信息 [#获取面部信息] 通过 [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/android/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 回调获取包含面部信息的原始视频数据。 :::warning[注意] 目前面部捕捉功能一次只输出一张人脸, 你需要在触发回调后,单独申请内存保存面部信息并在其他线程处理,否则可能会导致裸数据回调丢帧。 ::: ```java public boolean onCaptureVideoFrame(int sourceType, VideoFrame videoFrame) { if (null != videoFrame.metaInfo) { VideoFrameMetaInfo metaInfo = videoFrame.getMetaInfo(); SparseArray customMetaInfo = metaInfo.getCustomMetaInfo( "FaceCaptureInfo" ); if (null != customMetaInfo && customMetaInfo.size >= 1) { String face_info = ((FaceCaptureInfo) (customMetaInfo.get(0))).getInfoStr(); Log.d(TAG, "Face Info: " + face_info); } } return true; } ``` ### 使用面部信息驱动虚拟人 [#使用面部信息驱动虚拟人] 输出的面部信息为 JSON 格式,包含人脸面部特征点、头部旋转、头部平移量等量化数据。该面部信息为符合 ARKit 标准的 BS(Blend Shape)数据,你可以使用第三方 3D 渲染引擎对 BS 数据进一步处理。具体内容如下: - `faces`:Object 序列。包含识别到的面部信息,每一张人脸对应一个 object。 - `detected`:float。人脸识别的置信度,取值范围为 [0.0,1.0]。 - `blendshapes`:Object。面捕系数集,命名符合 ARKit 标准,内部的键值对为每一个 blendshape 系数。blendshape 系数为浮点,取值范围为 [0.0,1.0]。 - `rotation`:Object 序列。头部旋转量,包含以下三个键值对,取值为浮点数,范围为 [-180.0,180.0]: - `pitch`:头部俯仰角度。低头为正值,抬头为负值。 - `yaw`:头部偏转角度。左转为正值,右转为负值。 - `roll`:头部倾斜角度。右倾为正值,左倾为负值。 - `translation`:Object。头部平移量,包含 x,y,z 三个键值对,取值为浮点数,取值范围为 [0.0,1.0]。 - `faceState`:Int。用于表示当前的面捕控制状态,可能为以下值: - `0`:表示算法面捕控制中。 - `1`:表示算法控制回正中。 - `2`:表示已回正算法不控制。 - `timestamp`:String。输出结果的时间戳,单位为毫秒。 ```json { "faces":[{ "detected":0.98, "blendshapes":{ "eyeBlinkLeft":0.9, "eyeLookDownLeft":0.0, "eyeLookInLeft":0.0, "eyeLookOutLeft":0.0, "eyeLookUpLeft":0.0, "eyeSquintLeft":0.0, "eyeWideLeft":0.0, "eyeBlinkRight":0.0, "eyeLookDownRight":0.0, "eyeLookInRight":0.0, "eyeLookOutRight":0.0, "eyeLookUpRight":0.0, "eyeSquintRight":0.0, "eyeWideRight":0.0, "jawForward":0.0, "jawLeft":0.0, "jawRight":0.0, "jawOpen":0.0, "mouthClose":0.0, "mouthFunnel":0.0, "mouthPucker":0.0, "mouthLeft":0.0, "mouthRight":0.0, "mouthSmileLeft":0.0, "mouthSmileRight":0.0, "mouthFrownLeft":0.0, "mouthFrownRight":0.0, "mouthDimpleLeft":0.0, "mouthDimpleRight":0.0, "mouthStretchLeft":0.0, "mouthStretchRight":0.0, "mouthRollLower":0.0, "mouthRollUpper":0.0, "mouthShrugLower":0.0, "mouthShrugUpper":0.0, "mouthPressLeft":0.0, "mouthPressRight":0.0, "mouthLowerDownLeft":0.0, "mouthLowerDownRight":0.0, "mouthUpperUpLeft":0.0, "mouthUpperUpRight":0.0, "browDownLeft":0.0, "browDownRight":0.0, "browInnerUp":0.0, "browOuterUpLeft":0.0, "browOuterUpRight":0.0, "cheekPuff":0.0, "cheekSquintLeft":0.0, "cheekSquintRight":0.0, "noseSneerLeft":0.0, "noseSneerRight":0.0, "tongueOut":0.0 }, "rotation":{"pitch":30.0, "yaw":25.5, "roll":-15.5}, "rotationMatrix":[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0], "translation":{"x":0.5, "y":0.3,"z":0.5}, "faceState":1 }], "timestamp":"654879876546" } ``` ### 关闭面部捕捉插件 [#关闭面部捕捉插件] 调用 [`enableExtension`](/zh-CN/api-reference/rtc/android/extension#enableextension) 以关闭面部捕捉插件。 ```java rtcEngine.enableExtension("agora_video_filters_face_capture", "face_capture", false, Constants.MediaSourceType.PRIMARY_CAMERA_SOURCE ); ``` ## 参考信息 [#参考信息] ### 示例项目 [#示例项目] 声网在 Gitee、GitHub 上提供开源的示例项目 FaceCapture ([Gitee](https://gitee.com/agoraio-community/API-Examples/blob/main/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/FaceCapture.java), [GitHub](https://github.com/Shengwang-Community/API-Examples/blob/4.5.2/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/FaceCapture.java)) 供你参考,你可以前往下载或查看其中的源代码。 ### API 参考 [#api-参考] - [`addExtension`](/zh-CN/api-reference/rtc/android/extension#addextension) - [`registerExtension`](/zh-CN/api-reference/rtc/android/extension#registerextension) - [`enableExtension`](/zh-CN/api-reference/rtc/android/extension#enableextension) - [`setExtensionProperty`](/zh-CN/api-reference/rtc/android/extension#setextensionproperty) - [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/android/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe)