使用面部捕捉插件

本文介绍如何使用面捕捕捉插件驱动虚拟人。

面部捕捉插件可以获取人脸面部特征点、头部旋转、头部平移量等量化数据，用于驱动人脸 3D 贴纸、头套、挂件应用或数字人，为虚拟形象注入更生动的表情元素。

本文适用于独立使用面部捕捉插件获取人脸数据，并使用第三方渲染引擎驱动虚拟人的场景。

信息

你也可以配合声网提供的 MetaKit 插件实现面部捕捉，从而省去通过回调获取面部信息等步骤、无需自行搭建采集、编码和传输的框架。

前提条件

在开始使用面部捕捉插件前，请确保开发环境满足以下要求：

• 确保已集成 4.3.0 及以上版本 SDK，且包含面部捕捉插件动态库 AgoraFaceCaptureExtension.xcframework。
• 确保你已经在项目中实现了基本的实时音视频功能，详见实现音视频互动。
• 已联系声网技术支持获取面部捕捉鉴权参数：authentication_information 和 company_id。

实现流程

本节介绍使用面部捕捉插件的基本流程。

开启面部捕捉插件

调用 enableExtension 以启用面部捕捉插件。

信息

• 首次启用面部捕捉插件会产生一定的延迟，为保证频道内使用面部捕捉功能的流畅性，建议首次调用 enableExtension 的时机控制在加入频道前。
• 启用面部捕捉的媒体源（即参数 sourceType）仅支持设为 AgoraMediaSourceTypePrimaryCamera（默认）或 AgoraMediaSourceTypeCustomVideo。

Swift

agoraKit.enableExtension(
    withVendor: "agora_video_filters_face_capture", extension: "face_capture", enabled: true,
    sourceType: AgoraMediaSourceType.primaryCamera)

设置面部捕捉插件鉴权参数

调用 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)

获取面部信息

通过 onCaptureVideoFrame 回调获取包含面部信息的原始视频数据。

注意

目前面部捕捉功能一次只输出一张人脸, 你需要在触发回调后，单独申请内存保存面部信息并在其他线程处理，否则可能会导致裸数据回调丢帧。

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
}

使用面部信息驱动虚拟人

输出的面部信息为 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 以关闭面部捕捉插件。

Swift

agoraKit.enableExtension(
    withVendor: "agora_video_filters_face_capture", extension: "face_capture", enabled: false,
    sourceType: AgoraMediaSourceType.primaryCamera)

参考信息

示例项目

声网在 Gitee、GitHub 上提供开源的实现人声效果示例项目 FaceCapture 供你参考，你可以前往下载或查看其中的源代码。

API 参考

• registerExtension
• enableExtension
• setExtensionProperty
• onCaptureVideoFrame