即时通信 IM 美颜调节面板

·基础美颜

基础美颜功能已默认集成在 TUILiveKit 中，无需任何额外配置。它提供了美白、磨皮和红润效果，并支持美颜强度调节。

·高级美颜

高级美颜采用腾讯特效 SDK，提供了更加丰富和专业的美颜效果，例如 V 脸、眼距、瘦鼻、3D 贴纸等。

注意：高级美颜功能需要单独付费，详情请参见 腾讯特效 SDK。

一、效果展示

二、前提条件

参考 准备工作 完成 TUILiveKit 组件接入。

三、步骤 1：集成 tebeautykit 适配模块

下载并拷贝文件：下载并解压 TUILiveKit，将 Android/tebeautykit 文件夹拷贝到你工程的根目录，使其与 app 文件夹同级。

注意：该模块是 TUILiveKit 与腾讯特效 SDK 之间的适配层。模块内置的 TEBeautyProvider（ContentProvider）会在 App 启动时自动通过 TUICore 注册扩展与服务，TUILiveKit 检测到后会自动启用高级美颜面板与视频处理链路；未集成时则自动回退到基础美颜。

四、步骤 2：下载并导入美颜面板资源（必做）

高级美颜面板的 UI 与素材（面板配置 JSON、滤镜 LUT、2D/3D 动效贴纸、美妆、人像分割、面板图标等）不随 tebeautykit 模块发布，也不在 TUILiveKit 的开源仓库中。你需要从腾讯特效 SDK 按所购套餐获取完整资源包，再合并到 tebeautykit 模块的 assets/ 目录下。

1. 前往 腾讯特效 SDK 资源下载页 下载与你所购套餐匹配的 Android 资源包；如果下载页未提供，请联系腾讯特效 SDK 商务支持获取与 License 匹配的资源包。

2. 把资源包解压后的内容按以下结构合并到 tebeautykit/src/main/assets/ 目录下：

tebeautykit/src/main/assets/├── beauty_panel/ # 面板 JSON 配置 + 图标│ ├── beauty.json│ ├── beauty_template.json│ ├── beauty_image.json│ ├── beauty_shape.json│ ├── beauty_base_shape.json│ ├── beauty_general_shape.json│ ├── beauty_makeup.json│ ├── beauty_body.json│ ├── light_makeup.json│ ├── makeup.json│ ├── motion_2d.json│ ├── motion_3d.json│ ├── motion_gesture.json│ ├── segmentation.json│ ├── lut.json│ └── panel_icon/ # 面板内的所有 PNG 图标├── lut/ # 滤镜 LUT 调色图│ ├── baixi_lf.png│ ├── dongjing_lf.png│ ├── moren_lf.png│ ├── xindong_lf.png│ └── ziran_lf.png└── MotionRes/ # 动效 / 美妆 / 分割素材 ├── 2dMotionRes/ # 2D 动效贴纸 ├── 3dMotionRes/ # 3D 动效贴纸 ├── handMotionRes/ # 手势贴纸 ├── ganMotionRes/ # 一镜到底动效 ├── makeupRes/ # 整妆套装 ├── light_makeup/ # 轻美妆 └── segmentMotionRes/ # 人像分割 / 绿幕

注意：实际包含哪些 JSON 与子目录，由你所购买的套餐能力决定，详见下方的「套餐 → JSON 清单」对照表。

3. 各资源用途说明：

4. 套餐与 panel JSON 对照表——必须把所选 BeautyLevel 对应的所有 JSON 都导入，否则相关 Tab 会缺失或空白：

五、步骤 3：工程配置

1. 编辑工程根目录的 settings.gradle 文件，引入 tebeautykit 模块：

include ':tebeautykit'project(':tebeautykit').projectDir = new File(settingsDir, './tebeautykit')

2. 确保根目录 settings.gradle 的 dependencyResolutionManagement 中包含腾讯 Maven 源（tebeautykit 模块依赖的腾讯特效 SDK 从该源拉取）：

dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven { url 'https://mirrors.tencent.com/repository/maven/thirdparty' } }}

3. 在主 App 的 build.gradle 中加入对 tebeautykit 的依赖：

dependencies { api project(':tuilivekit') api project(':tebeautykit') // 关键}

注意：tebeautykit/build.gradle 中已经声明了所需的腾讯特效 SDK 依赖（com.tencent.mediacloud:TEBeautyKit 与 com.tencent.mediacloud:TencentEffect_<套餐编号>），主 App 无需重复添加。如需更换套餐，请在 tebeautykit/build.gradle 中把 TencentEffect_S1-07 替换为对应套餐编号。

六、步骤 4：鉴权和初始化

在 Application.onCreate()（或登录页 Activity.onCreate()）中调用一次 API 即可完成 License 鉴权 + 资源拷贝 + 套餐与面板装配：

//// App.kt//import android.app.Applicationimport com.tencent.effect.beautykit.tuiextension.BeautyLevelimport com.tencent.effect.beautykit.tuiextension.TUIBeautyKitclass App : Application() { override fun onCreate() { super.onCreate() // 一行完成：资源拷贝 + setTELicense + 选择套餐（默认 BeautyLevel.S1_07） TUIBeautyKit.instance.init( this, "YOUR_LICENSE_URL", "YOUR_LICENSE_KEY", BeautyLevel.S1_07 // 替换为你购买的套餐: A1_00 … S1_07 ) }}

BeautyLevel 可选值（与购买的腾讯特效 SDK 套餐一一对应）：

A1_00 A1_01 A1_02 A1_03 A1_04 A1_05 A1_06S1_00 S1_01 S1_02 S1_03 S1_04 S1_05 S1_06 S1_07

七、验证

完成以上步骤后，启动 App 进入开播页面或观众预览页，点击美颜按钮：

·看到 V 脸、瘦鼻、眼距、滤镜、贴纸、美妆、分割等多 Tab 面板 → 高级美颜接入成功

·仍是只有美白 / 磨皮 / 红润 的三项基础面板 → 高级美颜扩展未注册成功，请检查：

·主 App 的 build.gradle 是否依赖了 :tebeautykit module。

·Application 是否调用了 TUIBeautyKit.instance.init(…)。

·License 校验是否通过（查看 logcat 中 TEBeautySettings Tag 下 setTELicense callback 与 License Verification Success / Failed 日志）。

注意：面板能打开但某个 Tab（如贴纸 / 滤镜 / 美妆 / 分割）为空白或图标缺失 → 步骤 2 中对应的资源未完整合并到 tebeautykit/src/main/assets/ 下。

八、常见问题

Q1：美颜资源可以放到 App 的其它目录（如 assets/my_beauty/、res/raw/、SD 卡或在线下载）吗？

不可以直接放，需要遵守以下两条规则：

·面板 JSON 必须位于 assets/beauty_panel/ 下。tebeautykit 内部加载面板时传给 SDK 的是固定相对路径：

TEPanelDataModel("beauty_panel/beauty_template.json", TEUIProperty.UICategory.BEAUTY_TEMPLATE)

腾讯特效 SDK 会按这个路径直接从主 App 的 AssetManager 读取。若把 JSON 改到 assets/my_beauty/beauty_template.json 或挪到 res/raw/，SDK 是找不到的。各 JSON 内部对图标、MotionRes 子目录的引用（如 "icon": "beauty_panel/panel_icon/beauty/none.png"、"resourceUri": "MotionRes/3dMotionRes/video_zhixingmeigui"）也是同样的相对路径规则。

·MotionRes/、lut/ 必须位于 assets/ 根层级。TUIBeautyKit.init() 内部调用 TEBeautyKit.setResPath(filesDir/xmagic) + TEBeautyKit.copyRes(context)，由 SDK 把 assets/MotionRes/、assets/lut/ 等资源拷贝到 filesDir/xmagic/ 下。这里 assets/ 是写死在 SDK 内部的查找根。

如果确实需要做"按需下载"，可在用户实际使用某个 Tab 前，自行下载对应素材到 filesDir/xmagic/MotionRes/…（与 copyRes 拷贝出的目录结构一致）；但 panel JSON 本身（即 assets/beauty_panel/*.json）仍必须打包在 App 内。

Q2：License 鉴权失败怎么办？

请检查 LicenseUrl / LicenseKey 是否与套餐绑定、所选 BeautyLevel 是否与 License 匹配，并确认应用的 applicationId 与 License 申请时绑定的包名一致。可在 logcat 中过滤 Tag TEBeautySettings，查看 setTELicense callback 的 error 与 msg 字段定位失败原因。

Q3：如何动态切换套餐？

TUIBeautyKit.instance.init(…) 是进程内幂等的，单次启动后再次传入不同 BeautyLevel 不会生效。如需动态切换，请重新启动进程；或直接修改 tebeautykit/build.gradle 中 TencentEffect_<套餐编号> 依赖并重新编译。

Q4：首次启动很慢，需要优化吗？

首次启动时 TEBeautyKit.copyRes(…) 会把 assets/ 下数百 MB 的素材拷贝到 filesDir/xmagic/，耗时与素材量正相关。TUIBeautyKit.init() 内部已用子线程异步拷贝，且通过 SharedPreferences 记录版本号，相同版本下次启动会跳过。如对包体积敏感，可只保留所购套餐用得到的素材子目录，删除不需要的 MotionRes/* 子集。

九、恭喜你

完成以上步骤后，即可成功集成 TUILiveKit 高级美颜功能。