# 使用面部捕捉插件 (/zh-CN/realtime-media/rtc/build/extensions/face-capture/macos) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文介绍如何使用面部捕捉插件驱动虚拟人。 面部捕捉插件可以获取人脸面部特征点、头部旋转、头部平移量等量化数据,用于驱动人脸 3D 贴纸、头套、挂件应用或数字人,为虚拟形象注入更生动的表情元素。 本文适用于独立使用面部捕捉插件获取人脸数据,并使用第三方渲染引擎驱动虚拟人的场景。 ## 前提条件 [#前提条件-2] 在开始使用面部捕捉插件前,请确保开发环境满足以下要求: - 确保已集成 4.3.0 及以上版本 SDK,且包含面部捕捉插件动态库 `AgoraFaceCaptureExtension.xcframework`。 - 确保你已经在项目中实现了基本的实时音视频功能,详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。 - 已联系[声网技术支持](https://ticket.shengwang.cn/)获取面部捕捉鉴权参数:`authentication_information` 和 `company_id`。 ## 实现流程 [#实现流程-2] 本节介绍使用面部捕捉插件的基本流程。 ### 开启面部捕捉插件 [#开启面部捕捉插件-2] 调用 [`enableExtension`](/zh-CN/api-reference/rtc/macos/extension#api_irtcengine_enableextension) 以启用面部捕捉插件。 :::info[信息] - 首次启用面部捕捉插件会产生一定的延迟,为保证频道内使用面部捕捉功能的流畅性,建议首次调用 [`enableExtension`](/zh-CN/api-reference/rtc/macos/extension#api_irtcengine_enableextension) 的时机控制在加入频道前。 - 启用面部捕捉的媒体源(即参数 `sourceType`)仅支持设为 `AgoraMediaSourceTypePrimaryCamera`(默认)或 `AgoraMediaSourceTypeCustomVideo`。 ::: ```swift agoraKit.enableExtension( withVendor: "agora_video_filters_face_capture", extension: "face_capture", enabled: true, sourceType: AgoraMediaSourceType.primaryCamera) ``` ### 设置面部捕捉插件鉴权参数 [#设置面部捕捉插件鉴权参数-2] 调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/macos/extension#api_irtcengine_setextensionproperty) 设置鉴权参数以确保插件正常运行。 ```swift agoraKit.setExtensionProperty( withVendor: "agora_video_filters_face_capture", extension: "face_capture", key: "authentication_information", value: "{\"company_id\":\"xxxxx\", \"license\":\"xxxxx\"}", sourceType: AgoraMediaSourceType.primaryCamera) ``` ### 获取面部信息 [#获取面部信息-2] 通过 [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/macos/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 回调获取包含面部信息的原始视频数据。 :::warning[注意] 目前面部捕捉功能一次只输出一张人脸, 你需要在触发回调后,单独申请内存保存面部信息并在其他线程处理,否则可能会导致裸数据回调丢帧。 ::: ```swift func onCapture(_ videoFrame: AgoraOutputVideoFrame, sourceType: AgoraVideoSourceType) -> Bool { if !videoFrame.metaInfo.isEmpty { if videoFrame.metaInfo.contains(where: { $0.key as! String == "KEY_FACE_CAPTURE" }) { if let face_info = videoFrame.metaInfo["KEY_FACE_CAPTURE"] as? String { print("Face Info: \(face_info)") } } } return true } ``` ### 使用面部信息驱动虚拟人 [#使用面部信息驱动虚拟人-2] 输出的面部信息为 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" } ``` ### 关闭面部捕捉插件 [#关闭面部捕捉插件-2] 调用 [`enableExtension`](/zh-CN/api-reference/rtc/macos/extension#api_irtcengine_enableextension) 以关闭面部捕捉插件。 ```swift agoraKit.enableExtension( withVendor: "agora_video_filters_face_capture", extension: "face_capture", enabled: false, sourceType: AgoraMediaSourceType.primaryCamera) ``` ## 参考信息 [#参考信息-2] ### 示例项目 [#示例项目-2] 声网在 Gitee、GitHub 上提供开源的面部捕捉示例项目 FaceCapture ([Gitee](https://gitee.com/agoraio-community/API-Examples/tree/main/macOS/APIExample/Examples/Advanced/FaceCapture), [GitHub](https://github.com/Shengwang-Community/API-Examples/tree/4.5.2/macOS/APIExample/Examples/Advanced/FaceCapture)) 供你参考,你可以前往下载或查看其中的源代码。 ### API 参考 [#api-参考-2] - [`registerExtension`](/zh-CN/api-reference/rtc/macos/extension#api_irtcengine_registerextension) - [`enableExtension`](/zh-CN/api-reference/rtc/macos/extension#api_irtcengine_enableextension) - [`setExtensionProperty`](/zh-CN/api-reference/rtc/macos/extension#api_irtcengine_setextensionproperty) - [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/macos/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe)