# 使用面部捕捉插件 (/zh-CN/realtime-media/rtc/build/extensions/face-capture)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<_PlatformTabsGroup>
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="android" />
本文介绍如何使用面部捕捉插件驱动虚拟人。面部捕捉插件可以获取人脸面部特征点、头部旋转、头部平移量等量化数据，用于驱动人脸 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<IMetaInfo> 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)
<_PlatformProcessedMarker close="true" />

<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="ios" />
本文介绍如何使用面部捕捉插件驱动虚拟人。
面部捕捉插件可以获取人脸面部特征点、头部旋转、头部平移量等量化数据，用于驱动人脸 3D 贴纸、头套、挂件应用或数字人，为虚拟形象注入更生动的表情元素。

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



## 前提条件 [#前提条件-1]

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

- 确保已集成 4.3.0 及以上版本 SDK，且包含面部捕捉插件动态库 `AgoraFaceCaptureExtension.xcframework`。
- 确保你已经在项目中实现了基本的实时音视频功能，详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
- 已联系[声网技术支持](https://ticket.shengwang.cn/)获取面部捕捉鉴权参数：`authentication_information` 和 `company_id`。

## 实现流程 [#实现流程-1]

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

### 开启面部捕捉插件 [#开启面部捕捉插件-1]

调用 [`enableExtension`](/zh-CN/api-reference/rtc/ios/extension#api_irtcengine_enableextension) 以启用面部捕捉插件。

:::info[信息]
- 首次启用面部捕捉插件会产生一定的延迟，为保证频道内使用面部捕捉功能的流畅性，建议首次调用 [`enableExtension`](/zh-CN/api-reference/rtc/ios/extension#api_irtcengine_enableextension) 的时机控制在加入频道前。
- 启用面部捕捉的媒体源（即参数 `sourceType`）仅支持设为 `AgoraMediaSourceTypePrimaryCamera`（默认）或 `AgoraMediaSourceTypeCustomVideo`。
:::

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

### 设置面部捕捉插件鉴权参数 [#设置面部捕捉插件鉴权参数-1]

调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/ios/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)
```

### 获取面部信息 [#获取面部信息-1]

通过 [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/ios/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
}
```

### 使用面部信息驱动虚拟人 [#使用面部信息驱动虚拟人-1]

输出的面部信息为 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"
}
```

### 关闭面部捕捉插件 [#关闭面部捕捉插件-1]

调用 [`enableExtension`](/zh-CN/api-reference/rtc/ios/extension#api_irtcengine_enableextension) 以关闭面部捕捉插件。

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

## 参考信息 [#参考信息-1]

### 示例项目 [#示例项目-1]

声网在 Gitee、GitHub 上提供开源的示例项目 FaceCapture ([Gitee](https://gitee.com/agoraio-community/API-Examples/tree/main/iOS/APIExample/APIExample/Examples/Advanced/FaceCapture), [GitHub](https://github.com/Shengwang-Community/API-Examples/tree/4.5.2/iOS/APIExample/APIExample/Examples/Advanced/FaceCapture)) 供你参考，你可以前往下载或查看其中的源代码。

### API 参考 [#api-参考-1]

- [`registerExtension`](/zh-CN/api-reference/rtc/ios/extension#api_irtcengine_registerextension)
- [`enableExtension`](/zh-CN/api-reference/rtc/ios/extension#api_irtcengine_enableextension)
- [`setExtensionProperty`](/zh-CN/api-reference/rtc/ios/extension#api_irtcengine_setextensionproperty)
- [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/ios/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe)
<_PlatformProcessedMarker close="true" />

<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="macos" />
本文介绍如何使用面部捕捉插件驱动虚拟人。
面部捕捉插件可以获取人脸面部特征点、头部旋转、头部平移量等量化数据，用于驱动人脸 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)
<_PlatformProcessedMarker close="true" />

<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="windows" />
本文介绍如何使用面部捕捉插件驱动虚拟人。
面部捕捉插件可以获取人脸面部特征点、头部旋转、头部平移量等量化数据，用于驱动人脸 3D 贴纸、头套、挂件应用或数字人，为虚拟形象注入更生动的表情元素。

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



## 前提条件 [#前提条件-3]

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

- 确保已集成 4.3.0 及以上版本 SDK，且包含面部捕捉插件动态库 `libagora_face_capture_extension.dll`。
- 确保你已经在项目中实现了基本的实时音视频功能，详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
- 已联系[声网技术支持](https://ticket.shengwang.cn/)获取面部捕捉鉴权参数：`authentication_information` 和 `company_id`。

## 实现流程 [#实现流程-3]

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

### 开启面部捕捉插件 [#开启面部捕捉插件-3]

调用 [`enableExtension`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#enableextension) 以启用面部捕捉插件。

:::info[信息]
- 首次启用面部捕捉插件会产生一定的延迟，为保证频道内使用面部捕捉功能的流畅性，建议首次调用 [`enableExtension`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#enableextension) 的时机控制在加入频道前。
- 启用面部捕捉的媒体源（即参数 `type`）仅支持设为 `PRIMARY_CAMERA_SOURCE`（默认）或 `CUSTOM_VIDEO_SOURCE`。
:::

```cpp
m_rtcEngine.enableExtension(
    "agora_video_filters_face_capture", "face_capture", true,
    agora::media::MEDIA_SOURCE_TYPE::PRIMARY_CAMERA_SOURCE);
```

### 设置面部捕捉插件鉴权参数 [#设置面部捕捉插件鉴权参数-3]

调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#setextensionproperty) 设置鉴权参数以确保插件正常运行。

```cpp
m_rtcEngine.setExtensionProperty(
    "agora_video_filters_face_capture", "face_capture",
    "authentication_information",
    "{\"company_id\":\"xxxxx\", \"license\":\"xxxxx\"}",
    agora::media::MEDIA_SOURCE_TYPE::PRIMARY_CAMERA_SOURCE);
```

### 获取面部信息 [#获取面部信息-3]

通过 [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 回调获取包含面部信息的原始视频数据。

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

```cpp
bool onCaptureVideoFrame(agora::rtc::VIDEO_SOURCE_TYPE sourceType,
                         VideoFrame& videoFrame) {
  if (videoFrame.metaInfo != NULL) {
    const char* face_info = videoFrame.metaInfo->getMetaInfoStr(
        webrtc::VideoFrameMetaInfo::KEY_FACE_CAPTURE);
    if (face_info != NULL) {
      printf("Face Info: %s\n", face_info);
    }
  }
  return true;
}
```

### 使用面部信息驱动虚拟人 [#使用面部信息驱动虚拟人-3]

输出的面部信息为 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"
}
```

### 关闭面部捕捉插件 [#关闭面部捕捉插件-3]

调用 [`enableExtension`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#enableextension) 以关闭面部捕捉插件。

```cpp
m_rtcEngine.enableExtension(
    "agora_video_filters_face_capture", "face_capture", false,
    agora::media::MEDIA_SOURCE_TYPE::PRIMARY_CAMERA_SOURCE);
```

## 参考信息 [#参考信息-3]

### 示例项目 [#示例项目-3]

声网在 Gitee、GitHub 上提供开源的示例项目 FaceCapture ([Gitee](https://gitee.com/agoraio-community/API-Examples/tree/main/windows/APIExample/APIExample/Advanced/FaceCapture), [GitHub](https://github.com/Shengwang-Community/API-Examples/tree/4.5.2/windows/APIExample/APIExample/Advanced/FaceCapture)) 供你参考，你可以前往下载或查看其中的源代码。

### API 参考 [#api-参考-3]

- [`loadExtensionProvider`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#loadextensionprovider)
- [`registerExtension`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#registerextension)
- [`enableExtension`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#enableextension)
- [`setExtensionProperty`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#setextensionproperty)
- [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe)
<_PlatformProcessedMarker close="true" />
</_PlatformTabsGroup>