key-value 说明

通过声网 SDK v4.x 提供的 setExtensionProperty 方法，传入指定的 key 和 value，即可快速实现 MetaKit 插件的能力。其中：

• key 对应 MetaKit 插件的不同接口。
• value 以 JSON 格式包装接口的部分或全部参数。

本文介绍如何通过配置不同的 key-value 键值对实现 MetaKit 插件的虚拟人、Animoji、Sticker、灯光特效、360 背景功能模块。

基础功能

该小节介绍如何实现 MetaKit 插件的基础功能，如初始化引擎、加载场景资源、卸载场景资源、销毁引擎等，帮助你快速加载并体验 MetaKit 插件的效果。

设置安卓活动上下文

• key：setActivityContext
• value：Object。包含以下字段：
  • activityContext：String。活动上下文地址。

初始化引擎

• key：initialize
• value：{}

加载场景资源

加载场景资源后，引擎会自动请求场景纹理。

• key：loadMaterial
• value：Object。包含以下字段：
  • path：String。场景资源素材包的路径，如 "/sdcard/metaAssets/material_avatar_girl/"。
  • view：Int64。场景纹理的地址句柄，当前仅支持设置为 0。

开启场景视图的画面捕获

使用该接口开启场景视图的画面捕获后，调用 joinChannel[2/2] 加入频道，即可将场景视图的视频流发布到频道中。

• key：enableSceneVideo
• value：Object。包含以下字段：
  • view：Int64。视图的地址句柄。
  • enable：（可选）Boolean。是否开启场景视图的画面捕获。true：开启；false：（默认）不开启。

卸载场景资源

• key：unloadMaterial
• value：Object。包含以下字段：
  • path：（可选）String。当前场景资源素材包的路径，如 "/sdcard/metaAssets/material_avatar_girl/"。

销毁引擎

• key：destroy
• value：{}

进阶用法

在实现基础功能后，你可以参考本小节进一步体验开启纹理请求、切换纹理的场景模式和虚拟形象等进阶用法。

加载场景

• key：loadScene
• value：Object。包含以下字段：
  • sceneInfo：Object。包含以下字段：
    • scenePath：String。场景资源包的路径，如 "/sdcard/metaAssets/15"。
  • extraCustomInfo：Object。包含以下字段：
    • sceneIndex：Int。场景的索引，当前仅支持设置为 0。

开启纹理请求

请求一个纹理，并在纹理上渲染指定的场景内容，场景内容包括虚拟人、Animoji、Sticker、灯光特效和 360 背景。

• key：requestTexture
• value：
  • index：Int。纹理索引，当前仅支持设置为 0。
  • enable：Boolean。是否开启纹理请求。true：开启；false：（默认）不开启。
  • config：Object。包含以下字段：
    • width：Int。视图的宽度 (px)。将该参数设置为当前摄像头采集分辨率、画面布局的宽高，或者常见的分辨率，如 720 × 1280 等。
    • height：Int。视图的高度 (px)。将该参数设置为当前摄像头采集分辨率、画面布局的宽高，或者常见的分辨率，如 720 × 1280 等。
    • extraInfo：Object。包含以下字段：
      • sceneIndex：（可选）Int。场景索引，当前仅支持设置为 0。
      • avatarMode：（可选）Int。场景模式。0：（默认）虚拟人；1：Animoji、Sticker；2：灯光或背景。
      • avatar：（可选）String。虚拟人形象、Animoji 形象或 Sticker 挂件贴纸。avatarMode 为 0（虚拟人），则 avatar 可以设置为 girl 和 huamulan，默认为 girl；avatarMode 为 1 (Animoji、Sticker) ，则 avatar 可以设置为 dog、girlhead、arkit、ahhat01（龙头帽）、sm_facemask（口罩）、sm_3dglasses01（眼镜）和 sm_veil（面纱），默认为 dog。

信息

requestTexture 和 addSceneView 均可用于在 TextureView 上渲染指定场景，声网推荐你使用渲染性能更优、渲染延迟更低的 requestTexture。二者具体区别如下：

• requestTexture 无需向 MetaKit 插件传递渲染目标的 TextureView，MetaKit 插件会自动生成并回送纹理数据；addSceneView 则需要手动创建和管理 TextureView。
• 使用 requestTexture 后，所得纹理直接通过 SDK 进行渲染、预览以及编码后传输至远端；addSceneView 需要额外调用 enableSceneVideo 来开启场景画面捕获。
• requestTexture 当前仅支持单个视图，addSceneView 支持多个视图。
• 切换场景模式或虚拟形象时，使用 requestTexture 请求纹理，应搭配 switchTextureAvatarMode 实现场景切换；采用 addSceneView 添加场景视图，则应通过 switchAvatarMode 完成场景切换。
• 释放场景资源时，通过 requestTexture 请求纹理，可以通过再次调用该接口并将 enable 设为 false 来停止纹理请求；通过 addSceneView 添加场景视图，则应使用 removeSceneView 移除场景视图。

切换纹理场景

开启纹理请求后，你可以切换纹理视图的场景模式或场景中的虚拟人、Animoji 形象和 Sticker 挂件贴纸。

• key：switchTextureAvatarMode
• value：
  • index：Int。纹理索引，当前仅支持设置为 0。
  • mode：（可选）Int。指定你想切换的场景模式。0：虚拟人；1：Animoji、Sticker；2：视频采集画面。
  • avatar：（可选）String。指定你想切换的虚拟人形象、Animoji 形象或 Sticker 挂件贴纸。avatarMode 为 0（虚拟人），则 avatar 可以设置为 girl 和 huamulan；avatarMode 为 1 (Animoji、Sticker) ，则 avatar 可以设置为 dog、girlhead、arkit、ahhat01（龙头帽）、sm_facemask（口罩）、sm_3dglasses01（眼镜）和 sm_veil（面纱）。

添加场景视图

在一个原生 view 上添加 MetaKit 场景，并渲染指定的场景内容。场景内容包括虚拟人、Animoji、Sticker、灯光特效和 360 背景。

注意

• 最多支持添加 8 个场景视图。
• 目前仅支持对视频采集画面开启灯光和背景效果。如需指定 backgroundEffect 为 true，则 avatarMode 需设置为 2。

• key：addSceneView
• value：Object。包含以下字段：
  • view：Int64。视图的地址句柄。
  • config：Object。包含以下字段：
    • width：（可选）Int。视图的宽度 (px)。如不指定，则默认全屏。
    • height：（可选）Int。视图的高度 (px)。如不指定，则默认全屏。
    • extraInfo：Object。包含以下字段：
      • sceneIndex：Int。场景索引，当前仅支持设置为 0。
      • avatarMode：（可选）Int。场景模式。0：（默认）虚拟人；1：Animoji、Sticker；2：视频采集画面。
      • avatar：（可选）String。虚拟人形象、Animoji 形象或 Sticker 挂件贴纸。avatarMode 为 0（虚拟人），则 avatar 可以设置为 girl 和 huamulan，默认为 girl；avatarMode 为 1 (Animoji、Sticker) ，则 avatar 可以设置为 dog、girlhead、arkit、ahhat01（龙头帽）、sm_facemask（口罩）、sm_3dglasses01（眼镜）和 sm_veil（面纱），默认为 dog。
      • backgroundEffect：（可选）Boolean。是否启用灯光特效和 360 背景功能。true：开启；false：（默认）不开启。

切换视图场景

添加场景视图后，你可以切换指定视图的场景模式或场景中的虚拟人、Animoji 形象和 Sticker 挂件贴纸。

• key：switchAvatarMode
• value：Object。包含以下字段：
  • viewAddress：Int64。视图的地址句柄。
  • mode：（可选）Int。指定你想切换的场景模式。0：虚拟人；1：Animoji、Sticker；2：视频采集画面。
  • avatar：（可选）String。指定你想切换的虚拟人形象、Animoji 形象或 Sticker 挂件贴纸。avatarMode 为 0（虚拟人），则 avatar 可以设置为 girl 和 huamulan；avatarMode 为 1 (Animoji、Sticker) ，则 avatar 可以设置为 dog、girlhead、arkit、ahhat01（龙头帽）、sm_facemask（口罩）、sm_3dglasses01（眼镜）和 sm_veil（面纱）。

移除场景视图

从 view 上移除 MetaKit 场景视图。

• key：removeSceneView
• value：Object。包含以下字段：
  • view：Int64。视图的地址句柄。

卸载场景

• key：unloadScene
• value：{}

虚拟人

MetaKit 插件支持你对虚拟人进行形象切换、视角切换、捏脸和换装操作。体验虚拟人相关功能，需要在开启纹理请求或添加场景视图时将 avatarMode 设置为 0。

信息

除 girl、boy 和 huamulan 三个插件中已有的虚拟形象外，声网 MetaKit 插件提供开放的美术生态，支持一键导入按声网的美术标准制作的虚拟人模型，为用户提供更灵活的创作和集成选项。联系声网技术支持使用该功能。

切换虚拟人视角

• key：setCamera
• value：Object。包含以下字段：
  • viewMode：Int。虚拟人相机视角。0：显示虚拟形象全身；1：（默认）聚焦虚拟形象的上半身；2：聚焦虚拟形象的面部。

虚拟人捏脸

MetaKit 插件为虚拟形象提供了一套捏脸资源。

注意

当前仅 girl 和 boy 虚拟人形象支持捏脸操作。

• key：updateFace
• value：Object。包含以下字段：

  • key：String。资源 ID，例如 MC_updown_1（嘴角上弯曲）和 MC_updown_2（嘴角下弯曲）。详见捏脸资源。

  • value：Int。调节幅度，范围为 [0,100]，默认值为 50。支持传入多组捏脸部位的资源 ID (key) 及对应的调节幅度 (value)，以实现最终的捏脸效果。将 MC_updown_1 和 MC_updown_2 分别设为 100 的示例图如下：

    

虚拟人换装

MetaKit 插件为虚拟形象提供了一套换装资源。

注意

当前仅 girl 虚拟人形象支持换装操作。

• key：updateDress

• value：Object。包含以下字段：

  • id：Int[]。由多个换装部位的资源 ID 组成的 Int 数组。支持对头发、上衣外套、裤子等多个部位进行换装操作，且每个部位提供了多种换装资源可供选择，即每个部位对应多个换装资源 ID。需要注意的是每个部位每次只能指定一个资源。详见换装资源。

  推荐的套装搭配如下：

  套装一

  JSON

  {
      // 以下资源 ID 依次对应换装部位 [头发, 眉毛, 腮红, 头饰, 上衣外套, 裤子, 鞋子]
      "id": [10001, 10101, 10401, 10801, 12101, 14101, 15001]
  }

  

  套装二

  JSON

  {
      // 以下资源 ID 依次对应换装部位 [头发, 眉毛, 腮红, 上衣外套, 手套, 裤子, 鞋子]
      "id": [10002, 10102, 10402, 12102, 12501, 14102, 15002]
  }

  

Animoji 和 Sticker

MetaKit 插件支持你对 Animoji、Sticker 进行形象切换。体验 Animoji 和 Sticker 相关功能，需要在开启纹理请求或添加场景视图时将 avatarMode 设置为 1。

信息

• 除 dog、girlhead 和 arkit 三个插件中已有的 Animoji 外，声网 MetaKit 插件提供开放的美术生态，支持一键导入按声网的美术标准制作的 Animoji 形象，为用户提供更灵活的创作和集成选项。联系声网技术支持使用该功能。
• 除 veil、glass、facemask 和 dragonhat 四个插件中已有的 Sticker 外，声网 MetaKit 插件提供开放的美术生态，支持一键导入按声网的美术标准制作的 Sticker 形象，为用户提供更灵活的创作和集成选项。联系声网技术支持使用该功能。

调节渲染等级

MetaKit 插件提供低配、中配和高配三种渲染等级，你可以根据设备性能选择相应的渲染等级，以实现设备性能和渲染效果的最佳匹配。

注意

目前仅 dog 的 Animoji 形象支持调节渲染等级。

• key：setRenderQuality
• value：Object。包含以下字段：
  • general：Int。0：低配；1：（默认）中配；2：高配。

灯光特效

MetaKit 插件提供 3D 打光、屏幕波纹、极光特效、人像边缘火焰等灯光特效，并支持对灯光效果的颜色、强度、范围等参数进行精细化配置。体验灯光特效相关功能，需要在开启纹理请求时将 avatarMode 设置为 2 或在添加场景视图时将 backgroundEffect 设置为 true。

设置特效素材

• key：setEffectVideo
• value：Object。包含以下字段：
  • id：Int。特效素材 ID。
  • enable：Boolean。是否启用特效。true：启用；false：不启用。
  • param：（可选）Object。每个特效素材 ID 对应一组配置参数，支持你对灯光效果的颜色、强度、范围等进行精细化配置。如不填用参数，则使用默认的参数配置。

特效素材 ID 和配置参数的映射关系如下：

特效素材 ID (id)	特效名称	配置参数 (param)
1001	3D 打光	color (Int64)：打光颜色，传参时需要将 16 进制颜色换算成 Int64 值。例如，红色，16 进制颜色为 #FF0000，换算为 Int64 值为 16711680。 intensity (Float)：打光强度。推荐的取值范围是 [1.0, 2.0]，默认值为 1.6。 scale (Float)：打光范围。推荐的取值范围是 [0.3, 0.6]，默认值为 0.4。
1002	屏幕波纹	color (Int64)：波纹颜色。传参时需要将 16 进制颜色换算成 Int64 值。例如，红色，16 进制颜色为 #FF0000，换算为 Int64 值为 16711680。 speed (Float)：波动速度。建议的取值范围是 [-0.2, 0.2]，默认值为 -0.12。 scale (Float)：波纹大小。推荐的取值范围是 [3.0, 6.0]，默认值为 4.0。
1003	极光	color (Int64)：极光颜色。传参时需要将 16 进制颜色换算成 Int64 值。例如，红色，16 进制颜色为 #FF0000，换算为 Int64 值为 16711680。 intensity (Float)：极光强度。推荐的取值范围是 [0.8, 1.5]，默认值为 1.0。
2001	人像边缘火焰	color (Int64)：火焰颜色。传参时需要将 16 进制颜色换算成 Int64 值。例如，红色，16 进制颜色为 #FF0000，换算为 Int64 值为 16711680。 intensity (Float)：火焰强度。推荐的取值范围是 [0.2, 1.5]，默认值为 0.2。
2002	人像边缘光线	N/A
3001	氛围灯光组	N/A
3002	广告灯	startColor (Int64)：广告灯初始颜色。传参时需要将 16 进制颜色换算成 Int64 值。例如，红色，16 进制颜色为 #FF0000，换算为 Int64 值为 16711680。 endColor (Int64)：广告灯结束颜色。传参时需要将 16 进制颜色换算成 Int64 值。配置起始颜色后，会创建从初始颜色到结束颜色的渐变效果。 size (Float)：广告灯纹理大小。推荐的取值范围是 [8, 15]，默认值为 10。 intensity (Float)：广告灯强度。推荐的取值范围是 [100, 1000]，默认值为 1000。 range (Float)：广告灯照射距离。推荐的取值范围是 [10, 40]，默认值为 15。 text (String)：指定显示的文本内容，不超过 9 个汉字或字符。 animation (Int)：文字动画类型。0：无；1：跳动 bounce；2：波浪 wave；3：摇摆 swing。该参数仅在设置 text 时生效。

背景特效

MetaKit 插件支持你开启 360 度全景背景模式、自定义背景替换资源，并开启陀螺仪功能，增强场景背景的互动性和沉浸感。体验 360 背景相关功能，需要在开启纹理请求时将 avatarMode 设置为 2 或在添加场景视图时将 backgroundEffect 设置为 true。

设置 360 背景的替换资源

成功设置后，可以观察到视频画面背景被替换为指定资源，且转动手机能体验到全景效果。

• key：setBGVideo
• value：Object。包含以下字段：
  • mode：String。设置为 tex360，即 360 度全景背景。
  • param：
    • path：String。指定背景资源的 URL 或本地路径。
    • rotation：（可选）Int。旋转角度，默认值为 0。

开启背景陀螺仪

仅在成功设置 360 度全景背景后，才支持开启陀螺仪功能。开启陀螺仪功能可以进一步增强背景的互动性和沉浸感。

• key：setCameraGyro
• value：Object。包含以下字段：
  • state：Boolean。背景陀螺仪功能状态。on：开启；off：（默认）关闭。