# 相芯美颜道具高级版键值说明 (/zh-CN/realtime-media/marketplace/reference/faceunity-ar-api)

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

<_PlatformTabsGroup>
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="android" />
在声网 SDK 提供的插件相关方法和回调中，`key` 和 `value` 参数取决于你使用的插件。本页提供相芯美颜道具高级版插件支持的 `key` 和 `value` 说明。

<a id="key-value"></a>
## 插件的 key 概览 [#插件的-key-概览]

:::info[信息]
`key` 对应相芯 API 的名称，`value` 对应相芯 API 的参数。在以下表格中，如果 `value` 与相芯 API 参数完全一致，链接会跳至相芯官方文档。如果 `value` 与相芯 API 参数不一致，本页会单独列出解释。
:::

### 方法 key [#方法-key]

本节列出调用声网 SDK 的 `setExtensionProperty` 方法时，支持传入的 `key` 及对应功能。

#### 初始化 [#初始化]

| setExtensionProperty 方法的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuSetup`](#fusetup) | 初始化并鉴权。必须在其他 `key` 之前执行，否则会引发崩溃。 |
| [`fuLoadAIModelFromPackage`](#fuloadaimodelfrompackage) | 预加载 AI 能力。 |
| [`fuReleaseAIModel`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 释放特定 AI 能力的资源。|

#### 加载道具包 [#加载道具包]

| setExtensionProperty 方法的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuCreateItemFromPackage`](#fucreateitemfrompackage) | 加载道具包。 |
| [`fuLoadTongueModel`](#fuloadtonguemodel) | 加载舌头检测数据。 |
| [`fuItemSetParam`](#fuitemsetparam) | 修改或设定道具包中变量的值。 |

#### 销毁 [#销毁]

| setExtensionProperty 方法的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuDestroyItem`](#fudestroyitem) | 销毁一个指定道具。 |
| [`fuDestroyAllItems`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 销毁系统加载的所有道具，并释放系统运行时占用的所有资源。 |
| [`fuOnDeviceLost`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 当 OpenGL context 被外部释放/破坏时调用，用于重置系统的 GL 状态。 |
| [`fuDestroyLibData`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 释放由 `fuSetup` 初始化所分配的人脸跟踪模块的内存。 |

#### 功能接口-系统 [#功能接口-系统]
| setExtensionProperty 方法的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuBindItems`](#fubinditems) | 将资源道具绑定到目标道具上。 |
| [`fuUnbindItems`](#fuunbinditems) | 将资源道具从目标道具上解绑。 |
| [`fuIsTracking`](#fuistracking) | 是否获取正在跟踪的人脸数量。 |
| [`fuSetMaxFaces`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置系统跟踪的最大人脸数。 |
| [`fuSetDefaultRotationMode`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置默认的人脸朝向。 |

#### 功能接口-算法 [#功能接口-算法]

| setExtensionProperty 方法的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuFaceProcessorSetMinFaceRatio`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置人脸检测距离。 |
| [`fuSetTrackFaceAIType`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置 fuTrackFace 算法运行类型。 |
| [`fuSetFaceProcessorFov`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置 `FaceProcessor` 人脸算法模块跟踪的 `fov`。 |
| [`fuHumanProcessorReset`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 重置 HumanProcessor 人体算法模块状态。 |
| [`fuHumanProcessorSetMaxHumans`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置 HumanProcessor 人体算法模块跟踪人体数。 |
| [`fuHumanProcessorGetNumResults`](#fuhumanprocessorgetnumresults) | 是否获取 HumanProcessor 人体算法模块跟踪的人体数。 |
| [`fuHumanProcessorSetFov`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置 HumanProcessor 人体算法模块跟踪人体 3D 关键点时使用的 fov。 |
| [`fuHandDetectorGetResultNumHands`](#fuhanddetectorgetresultnumhands) | 是否获取 HandGesture 手势算法模块跟踪的手势数量。需加载 `ai_gesture.bundle`。 |

<a id="onevent"></a>
### 回调 key [#回调-key]

本节列出声网 SDK 的 `onEvent` 回调返回的 `key`。

| onEvent 回调的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuIsTracking`](#fuIsTracking1) | 返回正在跟踪的人脸数量。 |
| [`fuHumanProcessorGetNumResults`](#fuHumanProcessorGetNumResults1) | 返回 HumanProcessor 人体算法模块跟踪的人体数。 |
| [`fuHandDetectorGetResultNumHands`](#fuHandDetectorGetResultNumHands1) | 返回 HandGesture 手势算法模块跟踪的手势数量。|
| [`fuDestroyLibData`](#fuDestroyLibData1) | 该回调表明已经释放由 `fuSetup` 初始化所分配的人脸跟踪模块的内存。|

##  方法 key 的 value 说明 [#方法-key-的-value-说明]
### fuSetup [#fusetup]
`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `authdata`| 指向证书文件 authpack 的路径。|

### fuLoadAIModelFromPackage [#fuloadaimodelfrompackage]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `data`| String 型，AI 能力模型文件 `ai_xxx.bundle` 的路径。该类文件位于资源包的 `assets/AI_Model` 目录。|
| `type` | Int 型，描述 bundle 对应的 AI 能力类型。具体取值详见 `enum FUAITYPE`，[点击下载查看](https://web-cdn.agora.io/docs-files/1681973849554)。|

### fuCreateItemFromPackage [#fucreateitemfrompackage]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `data`| String 型，要加载的道具包的路径。道具包通常以 `*.bundle` 结尾。|

### fuLoadTongueModel [#fuloadtonguemodel]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `data`| String 型，舌头模型数据 `tongue.bundle` 的路径。|

### fuItemSetParam [#fuitemsetparam]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `obj_handle`| String 型，调用 [`fuCreateItemFromPackage`](#fucreateitemfrompackage) 加载道具包时传入的道具包路径。|
| `name` | String 型，要设定的道具变量名。|
| `value` | Object 型，要设定的变量值。|

美颜支持的道具变量名和变量值详见[相芯美颜道具功能文档](https://github.com/Faceunity/FULiveDemoDroid/blob/master/doc/nama/%E7%BE%8E%E9%A2%9C%E9%81%93%E5%85%B7%E5%8A%9F%E8%83%BD%E6%96%87%E6%A1%A3.md)。

### fuDestroyItem [#fudestroyitem]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `item`| String 型，调用 [`fuCreateItemFromPackage`](#fucreateitemfrompackage) 加载道具包时传入的道具包路径。|

### fuBindItems [#fubinditems]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `obj_handle`| String 型，目标道具的路径。|
| `p_items` | String 型数组，需要绑定的资源道具对应的路径数组。|

### fuUnbindItems [#fuunbinditems]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `obj_handle`| String 型，目标道具的路径。|
| `p_items` | String 型数组，需要解绑的资源道具对应的路径数组。|

### fuIsTracking [#fuistracking]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `enable`| Bool 型，是否获取正在跟踪的人脸数量。设为 `true` 会触发 [`fuIsTracking`](#fuIsTracking1) 回调。|

### fuHumanProcessorGetNumResults [#fuhumanprocessorgetnumresults]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `enable`| Bool 型，是否获取 HumanProcessor 人体算法模块跟踪的人体数量。设为 `true` 会触发 [`fuHumanProcessorGetNumResults`](#fuHumanProcessorGetNumResults1) 回调。|

### fuHandDetectorGetResultNumHands [#fuhanddetectorgetresultnumhands]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `enable`| Bool 型，是否获取 HandGesture 手势算法模块跟踪的手势数量。设为 `true` 会触发 [`fuHandDetectorGetResultNumHands`](#fuHandDetectorGetResultNumHands1) 回调。|

<a id="fuIsTracking1"></a>
## 回调 key 的 value 说明 [#回调-key-的-value-说明]
### fuIsTracking [#fuistracking-1]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `faces`|  Int 型，正在跟踪的人脸数量。|

<a id="fuHumanProcessorGetNumResults1"></a>
### fuHumanProcessorGetNumResults [#fuhumanprocessorgetnumresults-1]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `people`|  Int 型，正在跟踪的人体数量。|

<a id="fuHandDetectorGetResultNumHands1"></a>
### fuHandDetectorGetResultNumHands [#fuhanddetectorgetresultnumhands-1]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `hands`|  Int 型，正在跟踪的手势数量。|

<a id="fuDestroyLibData1"></a>
### fuDestroyLibData [#fudestroylibdata]

value 不包含任何参数。

## 错误码 [#错误码]

本节介绍 API 调用失败时返回的错误码，包含以下两种：

- 声网 SDK 层的错误码：通过对应 API 的返回值查看。
- 插件层的错误码：通过 `agorasdk.log` 文件查看。例如：`fuSetup ret: -1` 表示调用 `setExtensionProperty` 并传入 `key` 为 `fuSetup` 时出错，错误码为 `-1`。

<DocsTable>
<thead>
<tr>
<th scope="col">API</th>
<th scope="col">错误码</th>
<th scope="col">说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>`enableExtension`</td>
<td>`-3`（SDK 层）</td>
<td>

SDK 找不到对应的插件动态库。可能的原因有：

  - 插件动态库没有正确导入工程。
  - 传入的插件名称有误。

</td>
</tr>
<tr>
<td rowSpan={4}>`setExtensionProperty`</td>
<td>`-1`（插件层）</td>
<td>

- `key` 为 `fuSetup`：重复调用，`fuSetup` 只需要调用一次。
- `key` 为 `fuLoadAIModelFromPackage` 或 `fuCreateItemFromPackage`：传入的 value 值有误。

</td>
</tr>
<tr>
<td>`-2`（SDK 层）</td>
<td>`enableExtension` 的调用时序错误或调用时机太晚。</td>
</tr>
<tr>
<td>`-2`（插件层）</td>
<td>

参数错误。可能的原因有：

  - 传入的 `key` 或 `value` 为空。
  - `value` 无法按照 JSON 规则解析，请参考文档中的规范传值。

</td>
</tr>
<tr>
<td>`-20`（插件层）</td>
<td>

- 传入的 `key` 暂不支持。
- `key` 为 `fuLoadAIModelFromPackage`：该 AI 能力已经加载过，无需重复加载。
- `key` 为 `fuDestroyItem` 时：该道具已经销毁，无需重复销毁。

</td>
</tr>
</tbody>
</DocsTable>
<_PlatformProcessedMarker close="true" />

<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="ios" />
在声网 SDK 提供的插件相关方法和回调中，`key` 和 `value` 参数取决于你使用的插件。本页提供相芯美颜道具高级版插件支持的 `key` 和 `value` 说明。

<a id="key-value"></a>
## 插件的 key 概览 [#插件的-key-概览-1]

:::info[信息]
`key` 对应相芯 API 的名称，`value` 对应相芯 API 的参数。在以下表格中，如果 `value` 与相芯 API 参数完全一致，链接会跳至相芯官方文档。如果 `value` 与相芯 API 参数不一致，本页会单独列出解释。
:::

### 方法 key [#方法-key-1]

本节列出调用声网 SDK 的 `setExtensionPropertyWithVendor` 方法时，支持传入的 `key` 及对应功能。

#### 初始化 [#初始化-1]

| setExtensionPropertyWithVendor 方法的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuSetup`](#fusetup-1) | 初始化并鉴权。必须在其他 `key` 之前执行，否则会引发崩溃。 |
| [`fuLoadAIModelFromPackage`](#fuloadaimodelfrompackage-1) | 预加载 AI 能力。 |
| [`fuReleaseAIModel`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 释放特定 AI 能力的资源。|

#### 加载道具包 [#加载道具包-1]

| setExtensionPropertyWithVendor 方法的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuCreateItemFromPackage`](#fucreateitemfrompackage-1) | 加载道具包。 |
| [`fuLoadTongueModel`](#fuloadtonguemodel-1) | 加载舌头检测数据。 |
| [`fuItemSetParam`](#fuitemsetparam-1) | 修改或设定道具包中变量的值。 |

#### 销毁 [#销毁-1]

| setExtensionPropertyWithVendor 方法的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuDestroyItem`](#fudestroyitem-1) | 销毁一个指定道具。 |
| [`fuDestroyAllItems`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 销毁系统加载的所有道具，并释放系统运行时占用的所有资源。 |
| [`fuOnDeviceLost`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 当 OpenGL context 被外部释放/破坏时调用，用于重置系统的 GL 状态。 |
| [`fuDestroyLibData`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 释放由 `fuSetup` 初始化所分配的人脸跟踪模块的内存。 |

#### 功能接口-系统 [#功能接口-系统-1]
| setExtensionPropertyWithVendor 方法的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuBindItems`](#fubinditems-1) | 将资源道具绑定到目标道具上。 |
| [`fuUnbindItems`](#fuunbinditems-1) | 将资源道具从目标道具上解绑。 |
| [`fuIsTracking`](#fuistracking-2) | 是否获取正在跟踪的人脸数量。 |
| [`fuSetMaxFaces`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置系统跟踪的最大人脸数。 |
| [`fuSetDefaultRotationMode`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置默认的人脸朝向。 |

#### 功能接口-算法 [#功能接口-算法-1]

| setExtensionPropertyWithVendor 方法的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuFaceProcessorSetMinFaceRatio`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置人脸检测距离。 |
| [`fuSetTrackFaceAIType`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置 fuTrackFace 算法运行类型。 |
| [`fuSetFaceProcessorFov`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置 `FaceProcessor` 人脸算法模块跟踪的 `fov`。 |
| [`fuHumanProcessorReset`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 重置 HumanProcessor 人体算法模块状态。 |
| [`fuHumanProcessorSetMaxHumans`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置 HumanProcessor 人体算法模块跟踪人体数。 |
| [`fuHumanProcessorGetNumResults`](#fuhumanprocessorgetnumresults-2) | 是否获取 HumanProcessor 人体算法模块跟踪的人体数。 |
| [`fuHumanProcessorSetFov`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置 HumanProcessor 人体算法模块跟踪人体 3D 关键点时使用的 fov。 |
| [`fuHandDetectorGetResultNumHands`](#fuhanddetectorgetresultnumhands-2) | 是否获取 HandGesture 手势算法模块跟踪的手势数量。需加载 `ai_gesture.bundle`。 |

<a id="onevent"></a>
### 回调 key [#回调-key-1]

本节列出声网 SDK 的 `onEvent` 回调返回的 `key`。

| onEvent 回调的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuIsTracking`](#fuIsTracking1) | 返回正在跟踪的人脸数量。 |
| [`fuHumanProcessorGetNumResults`](#fuHumanProcessorGetNumResults1) | 返回 HumanProcessor 人体算法模块跟踪的人体数。 |
| [`fuHandDetectorGetResultNumHands`](#fuHandDetectorGetResultNumHands1) | 返回 HandGesture 手势算法模块跟踪的手势数量。|
| [`fuDestroyLibData`](#fuDestroyLibData1) | 该回调表明已经释放由 `fuSetup` 初始化所分配的人脸跟踪模块的内存。|

##  方法 key 的 value 说明 [#方法-key-的-value-说明-1]
### fuSetup [#fusetup-1]
`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `authdata`| 指向证书文件 authpack 的路径。|

### fuLoadAIModelFromPackage [#fuloadaimodelfrompackage-1]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `data`| String 型，AI 能力模型文件 `ai_xxx.bundle` 的路径。该类文件位于资源包的 `assets/AI_Model` 目录。|
| `type` | Int 型，描述 bundle 对应的 AI 能力类型。具体取值详见 `enum FUAITYPE`，[点击下载查看](https://web-cdn.agora.io/docs-files/1681973849554)。|

### fuCreateItemFromPackage [#fucreateitemfrompackage-1]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `data`| String 型，要加载的道具包的路径。道具包通常以 `*.bundle` 结尾。|

### fuLoadTongueModel [#fuloadtonguemodel-1]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `data`| String 型，舌头模型数据 `tongue.bundle` 的路径。|

### fuItemSetParam [#fuitemsetparam-1]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `obj_handle`| String 型，调用 [`fuCreateItemFromPackage`](#fucreateitemfrompackage-1) 加载道具包时传入的道具包路径。|
| `name` | String 型，要设定的道具变量名。|
| `value` | Object 型，要设定的变量值。|

美颜支持的道具变量名和变量值详见[相芯美颜道具功能文档](https://github.com/Faceunity/FULiveDemoDroid/blob/master/doc/nama/%E7%BE%8E%E9%A2%9C%E9%81%93%E5%85%B7%E5%8A%9F%E8%83%BD%E6%96%87%E6%A1%A3.md)。

### fuDestroyItem [#fudestroyitem-1]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `item`| String 型，调用 [`fuCreateItemFromPackage`](#fucreateitemfrompackage-1) 加载道具包时传入的道具包路径。|

### fuBindItems [#fubinditems-1]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `obj_handle`| String 型，目标道具的路径。|
| `p_items` | String 型数组，需要绑定的资源道具对应的路径数组。|

### fuUnbindItems [#fuunbinditems-1]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `obj_handle`| String 型，目标道具的路径。|
| `p_items` | String 型数组，需要解绑的资源道具对应的路径数组。|

### fuIsTracking [#fuistracking-2]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `enable`| Bool 型，是否获取正在跟踪的人脸数量。设为 `true` 会触发 [`fuIsTracking`](#fuIsTracking1) 回调。|

### fuHumanProcessorGetNumResults [#fuhumanprocessorgetnumresults-2]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `enable`| Bool 型，是否获取 HumanProcessor 人体算法模块跟踪的人体数量。设为 `true` 会触发 [`fuHumanProcessorGetNumResults`](#fuHumanProcessorGetNumResults1) 回调。|

### fuHandDetectorGetResultNumHands [#fuhanddetectorgetresultnumhands-2]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `enable`| Bool 型，是否获取 HandGesture 手势算法模块跟踪的手势数量。设为 `true` 会触发 [`fuHandDetectorGetResultNumHands`](#fuHandDetectorGetResultNumHands1) 回调。|

<a id="fuIsTracking1"></a>
## 回调 key 的 value 说明 [#回调-key-的-value-说明-1]
### fuIsTracking [#fuistracking-3]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `faces`|  Int 型，正在跟踪的人脸数量。|

<a id="fuHumanProcessorGetNumResults1"></a>
### fuHumanProcessorGetNumResults [#fuhumanprocessorgetnumresults-3]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `people`|  Int 型，正在跟踪的人体数量。|

<a id="fuHandDetectorGetResultNumHands1"></a>
### fuHandDetectorGetResultNumHands [#fuhanddetectorgetresultnumhands-3]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `hands`|  Int 型，正在跟踪的手势数量。|

<a id="fuDestroyLibData1"></a>
### fuDestroyLibData [#fudestroylibdata-1]

value 不包含任何参数。

## 错误码 [#错误码-1]

本节介绍 API 调用失败时返回的错误码，包含以下两种：

- 声网 SDK 层的错误码：通过对应 API 的返回值查看。
- 插件层的错误码：通过 `agorasdk.log` 文件查看。例如：`fuSetup ret: -1` 表示调用 `setExtensionPropertyWithVendor` 并传入 `key` 为 `fuSetup` 时出错，错误码为 `-1`。

<DocsTable>
<thead>
<tr>
<th scope="col">API</th>
<th scope="col">错误码</th>
<th scope="col">说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>`enableExtensionWithVendor`</td>
<td>`-3`（SDK 层）</td>
<td>

SDK 找不到对应的插件动态库。可能的原因有：

  - 插件动态库没有正确导入工程。
  - 传入的插件名称有误。

</td>
</tr>
<tr>
<td rowSpan={4}>`setExtensionPropertyWithVendor`</td>
<td>`-1`（插件层）</td>
<td>

- `key` 为 `fuSetup`：重复调用，`fuSetup` 只需要调用一次。
- `key` 为 `fuLoadAIModelFromPackage` 或 `fuCreateItemFromPackage`：传入的 value 值有误。

</td>
</tr>
<tr>
<td>`-2`（SDK 层）</td>
<td>`enableExtension` 的调用时序错误或调用时机太晚。</td>
</tr>
<tr>
<td>`-2`（插件层）</td>
<td>

参数错误。可能的原因有：

  - 传入的 `key` 或 `value` 为空。
  - `value` 无法按照 JSON 规则解析，请参考文档中的规范传值。

</td>
</tr>
<tr>
<td>`-20`（插件层）</td>
<td>

- 传入的 `key` 暂不支持。
- `key` 为 `fuLoadAIModelFromPackage`：该 AI 能力已经加载过，无需重复加载。
- `key` 为 `fuDestroyItem` 时：该道具已经销毁，无需重复销毁。

</td>
</tr>
</tbody>
</DocsTable>
<_PlatformProcessedMarker close="true" />

<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="flutter" />
在声网 SDK 提供的插件相关方法和回调中，`key` 和 `value` 参数取决于你使用的插件。本页提供相芯美颜道具高级版插件支持的 `key` 和 `value` 说明。

<a id="key-value"></a>
## 插件的 key 概览 [#插件的-key-概览-2]

:::info[信息]
`key` 对应相芯 API 的名称，`value` 对应相芯 API 的参数。在以下表格中，如果 `value` 与相芯 API 参数完全一致，链接会跳至相芯官方文档。如果 `value` 与相芯 API 参数不一致，本页会单独列出解释。
:::

### 方法 key [#方法-key-2]

本节列出调用声网 SDK 的 `setExtensionProperty` 方法时，支持传入的 `key` 及对应功能。

#### 初始化 [#初始化-2]

| setExtensionProperty 方法的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuSetup`](#fusetup-2) | 初始化并鉴权。必须在其他 `key` 之前执行，否则会引发崩溃。 |
| [`fuLoadAIModelFromPackage`](#fuloadaimodelfrompackage-2) | 预加载 AI 能力。 |
| [`fuReleaseAIModel`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 释放特定 AI 能力的资源。|

#### 加载道具包 [#加载道具包-2]

| setExtensionProperty 方法的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuCreateItemFromPackage`](#fucreateitemfrompackage-2) | 加载道具包。 |
| [`fuLoadTongueModel`](#fuloadtonguemodel-2) | 加载舌头检测数据。 |
| [`fuItemSetParam`](#fuitemsetparam-2) | 修改或设定道具包中变量的值。 |

#### 销毁 [#销毁-2]

| setExtensionProperty 方法的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuDestroyItem`](#fudestroyitem-2) | 销毁一个指定道具。 |
| [`fuDestroyAllItems`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 销毁系统加载的所有道具，并释放系统运行时占用的所有资源。 |
| [`fuOnDeviceLost`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 当 OpenGL context 被外部释放/破坏时调用，用于重置系统的 GL 状态。 |
| [`fuDestroyLibData`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 释放由 `fuSetup` 初始化所分配的人脸跟踪模块的内存。 |

#### 功能接口-系统 [#功能接口-系统-2]
| setExtensionProperty 方法的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuBindItems`](#fubinditems-2) | 将资源道具绑定到目标道具上。 |
| [`fuUnbindItems`](#fuunbinditems-2) | 将资源道具从目标道具上解绑。 |
| [`fuIsTracking`](#fuistracking-4) | 是否获取正在跟踪的人脸数量。 |
| [`fuSetMaxFaces`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置系统跟踪的最大人脸数。 |
| [`fuSetDefaultRotationMode`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置默认的人脸朝向。 |

#### 功能接口-算法 [#功能接口-算法-2]

| setExtensionProperty 方法的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuFaceProcessorSetMinFaceRatio`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置人脸检测距离。 |
| [`fuSetTrackFaceAIType`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置 fuTrackFace 算法运行类型。 |
| [`fuSetFaceProcessorFov`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置 `FaceProcessor` 人脸算法模块跟踪的 `fov`。 |
| [`fuHumanProcessorReset`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 重置 HumanProcessor 人体算法模块状态。 |
| [`fuHumanProcessorSetMaxHumans`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置 HumanProcessor 人体算法模块跟踪人体数。 |
| [`fuHumanProcessorGetNumResults`](#fuhumanprocessorgetnumresults-4) | 是否获取 HumanProcessor 人体算法模块跟踪的人体数。 |
| [`fuHumanProcessorSetFov`](https://k2i32i19ow.feishu.cn/wiki/Zi70wz3EaiXEH7kuFUjcTnBYn5f) | 设置 HumanProcessor 人体算法模块跟踪人体 3D 关键点时使用的 fov。 |
| [`fuHandDetectorGetResultNumHands`](#fuhanddetectorgetresultnumhands-4) | 是否获取 HandGesture 手势算法模块跟踪的手势数量。需加载 `ai_gesture.bundle`。 |

<a id="onevent"></a>
### 回调 key [#回调-key-2]

本节列出声网 SDK 的 `onEvent` 回调返回的 `key`。

| onEvent 回调的 key| 描述 |
| ------------------------------------ | -------- |
| [`fuIsTracking`](#fuIsTracking1) | 返回正在跟踪的人脸数量。 |
| [`fuHumanProcessorGetNumResults`](#fuHumanProcessorGetNumResults1) | 返回 HumanProcessor 人体算法模块跟踪的人体数。 |
| [`fuHandDetectorGetResultNumHands`](#fuHandDetectorGetResultNumHands1) | 返回 HandGesture 手势算法模块跟踪的手势数量。|
| [`fuDestroyLibData`](#fuDestroyLibData1) | 该回调表明已经释放由 `fuSetup` 初始化所分配的人脸跟踪模块的内存。|

##  方法 key 的 value 说明 [#方法-key-的-value-说明-2]
### fuSetup [#fusetup-2]
`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `authdata`| 指向证书文件 authpack 的路径。|

### fuLoadAIModelFromPackage [#fuloadaimodelfrompackage-2]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `data`| String 型，AI 能力模型文件 `ai_xxx.bundle` 的路径。该类文件位于资源包的 `assets/AI_Model` 目录。|
| `type` | Int 型，描述 bundle 对应的 AI 能力类型。具体取值详见 `enum FUAITYPE`，[点击下载查看](https://web-cdn.agora.io/docs-files/1681973849554)。|

### fuCreateItemFromPackage [#fucreateitemfrompackage-2]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `data`| String 型，要加载的道具包的路径。道具包通常以 `*.bundle` 结尾。|

### fuLoadTongueModel [#fuloadtonguemodel-2]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `data`| String 型，舌头模型数据 `tongue.bundle` 的路径。|

### fuItemSetParam [#fuitemsetparam-2]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `obj_handle`| String 型，调用 [`fuCreateItemFromPackage`](#fucreateitemfrompackage-2) 加载道具包时传入的道具包路径。|
| `name` | String 型，要设定的道具变量名。|
| `value` | Object 型，要设定的变量值。|

美颜支持的道具变量名和变量值详见[相芯美颜道具功能文档](https://github.com/Faceunity/FULiveDemoDroid/blob/master/doc/nama/%E7%BE%8E%E9%A2%9C%E9%81%93%E5%85%B7%E5%8A%9F%E8%83%BD%E6%96%87%E6%A1%A3.md)。

### fuDestroyItem [#fudestroyitem-2]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `item`| String 型，调用 [`fuCreateItemFromPackage`](#fucreateitemfrompackage-2) 加载道具包时传入的道具包路径。|

### fuBindItems [#fubinditems-2]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `obj_handle`| String 型，目标道具的路径。|
| `p_items` | String 型数组，需要绑定的资源道具对应的路径数组。|

### fuUnbindItems [#fuunbinditems-2]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `obj_handle`| String 型，目标道具的路径。|
| `p_items` | String 型数组，需要解绑的资源道具对应的路径数组。|

### fuIsTracking [#fuistracking-4]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `enable`| Bool 型，是否获取正在跟踪的人脸数量。设为 `true` 会触发 [`fuIsTracking`](#fuIsTracking1) 回调。|

### fuHumanProcessorGetNumResults [#fuhumanprocessorgetnumresults-4]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `enable`| Bool 型，是否获取 HumanProcessor 人体算法模块跟踪的人体数量。设为 `true` 会触发 [`fuHumanProcessorGetNumResults`](#fuHumanProcessorGetNumResults1) 回调。|

### fuHandDetectorGetResultNumHands [#fuhanddetectorgetresultnumhands-4]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `enable`| Bool 型，是否获取 HandGesture 手势算法模块跟踪的手势数量。设为 `true` 会触发 [`fuHandDetectorGetResultNumHands`](#fuHandDetectorGetResultNumHands1) 回调。|

<a id="fuIsTracking1"></a>
## 回调 key 的 value 说明 [#回调-key-的-value-说明-2]
### fuIsTracking [#fuistracking-5]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `faces`|  Int 型，正在跟踪的人脸数量。|

<a id="fuHumanProcessorGetNumResults1"></a>
### fuHumanProcessorGetNumResults [#fuhumanprocessorgetnumresults-5]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `people`|  Int 型，正在跟踪的人体数量。|

<a id="fuHandDetectorGetResultNumHands1"></a>
### fuHandDetectorGetResultNumHands [#fuhanddetectorgetresultnumhands-5]

`value` 包含以下参数：

| value 参数| 描述 |
| ----------- | ---------------------- |
| `hands`|  Int 型，正在跟踪的手势数量。|

<a id="fuDestroyLibData1"></a>
### fuDestroyLibData [#fudestroylibdata-2]

value 不包含任何参数。

## 错误码 [#错误码-2]

本节介绍 API 调用失败时返回的错误码，包含以下两种：

- 声网 SDK 层的错误码：通过对应 API 的返回值查看。
- 插件层的错误码：通过 `agorasdk.log` 文件查看。例如：`fuSetup ret: -1` 表示调用 `setExtensionProperty` 并传入 `key` 为 `fuSetup` 时出错，错误码为 `-1`。

<DocsTable>
<thead>
<tr>
<th scope="col">API</th>
<th scope="col">错误码</th>
<th scope="col">说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>`enableExtension`</td>
<td>`-3`（SDK 层）</td>
<td>

SDK 找不到对应的插件动态库。可能的原因有：

  - 插件动态库没有正确导入工程。
  - 传入的插件名称有误。

</td>
</tr>
<tr>
<td rowSpan={4}>`setExtensionProperty`</td>
<td>`-1`（插件层）</td>
<td>

- `key` 为 `fuSetup`：重复调用，`fuSetup` 只需要调用一次。
- `key` 为 `fuLoadAIModelFromPackage` 或 `fuCreateItemFromPackage`：传入的 value 值有误。

</td>
</tr>
<tr>
<td>`-2`（SDK 层）</td>
<td>`enableExtension` 的调用时序错误或调用时机太晚。</td>
</tr>
<tr>
<td>`-2`（插件层）</td>
<td>

参数错误。可能的原因有：

  - 传入的 `key` 或 `value` 为空。
  - `value` 无法按照 JSON 规则解析，请参考文档中的规范传值。

</td>
</tr>
<tr>
<td>`-20`（插件层）</td>
<td>

- 传入的 `key` 暂不支持。
- `key` 为 `fuLoadAIModelFromPackage`：该 AI 能力已经加载过，无需重复加载。
- `key` 为 `fuDestroyItem` 时：该道具已经销毁，无需重复销毁。

</td>
</tr>
</tbody>
</DocsTable>
<_PlatformProcessedMarker close="true" />
</_PlatformTabsGroup>