1. Android release 包报错找不到某些方法，如何解决？
如果您在打 release 包时，启用了编译优化（把 minifyEnabled 设置为 true），会裁掉一些未在 java 层调用的代码，而这些代码有可能会被 native 层调用，从而引起
no xxx method 的异常。如果您启用了这样的编译优化，那就要添加这些 keep 规则，防止 xmagic 的代码被裁掉：
-keep class com.tencent.xmagic.** { *;}-keep class org.light.** { *;}-keep class org.libpag.** { *;}-keep class org.extra.** { *;}-keep class com.gyailib.**{ *;}-keep class com.tencent.cloud.iai.lib.** { *;}-keep class com.tencent.beacon.** { *;}-keep class com.tencent.qimei.** { *;}-keep class androidx.exifinterface.** { *;}
2. Android SDK 集成到宿主工程报 gson 库冲突，如何解决？
在宿主工程
build.gradle 文件中添加如下代码：Android{configurations {all*.exclude group: 'com.google.code.gson'}}
3. Android targetSdkVersion 为31或更高时，so 库没有加载成功？或者无法使用 GAN 类型特效（例如童话脸、童年泡泡糖等）？
Android targetSdkVersion 为31或更高版本时需要在 app 模块下找到
AndroidManifest.xml 文件，在 application 标签内加入如下标签：<uses-native-libraryandroid:name="libOpenCL.so"android:required="false" />//true 表示libOpenCL是当前app必需的。如果没有此库，系统将不允许app安装。不建议设置为true，否则可能导致用户无法安装app。//false 表示libOpenCL不是当前app必需的。无论有没有此库，都可以正常安装app。如果设备有此库，美颜特效SDK里的GAN类型特效能正常生效（例如童话脸、国漫脸）。如果设备没有此库，GAN类型不会生效，但也不影响SDK内其他功能的使用。//关于uses-native-library的说明，请参考Android 官网介绍：https://developer.android.com/guide/topics/manifest/uses-native-library-element
4. 使用美颜时传递的纹理是横向纹理，如何解决？
可以使用 demo 中工具类
TextureConverter.java 的 convert 方法对纹理进行旋转，转换为竖屏，然后再传递给美颜 SDK。/*** 此方法用于对rgba纹理进行旋转和镜像处理。处理过程为：先顺时针旋转rotation度（可取值0,90,180，270），再进行左右翻转(flipHorizontal）和 上下翻转（flipVertical）。* 使用场景：某些推流SDK返回的纹理是横屏纹理或者画面中人物朝向不对，而美颜特效SDK要求纹理中的人物是正向的，所以可以通过此方法对纹理进行转换。** @param srcID rgba纹理* @param width 纹理宽度* @param height 纹理高度* @param rotation 需要进行旋转的角度。* @return 旋转后的纹理，注意：如果旋转90或者270度，那么宽度需要进行交换。*/public int convert(int srcID, int width, int height, @RotationDegreesValue int rotation, boolean flipVertical, boolean flipHorizontal)
5. 使用美颜时传递的纹理是 oes 纹理，如何解决？
可以使用 demo 中工具类
TextureConverter.java 的 oes2Rgba 方法对纹理进行转换，转换为 RGBA 纹理，然后再传递给美颜 SDK。/*** 此方法用于将oes纹理转换为rgba纹理** @param srcID oes 纹理* @param width 纹理宽度* @param height 纹理高度* @return rgba纹理ID*/public int oes2Rgba(int srcID, int width, int height)
6. 如果想使用别的版本的 pag 如何解决？V3.5.0及以上支持
客户集成美颜 SDK 时：
如果是通过 Maven 集成，通过 implementation TencentEffect 就能引入 pag。如果您不想用 TencentEffect 依赖的 pag，可以通过 exclude 排除，然后在自己 app 的 build.gradle 中引入您需要的 pag 版本：
implementation ('com.tencent.mediacloud:TencentEffect_S1-04:版本号'){exclude group: "com.tencent.tav", module: "libpag"}
如果是下载美颜 SDK 的 aar 手动集成，在项目中依赖 TencentEffect.aar，这个 aar 是不带 pag 的，您还需要在 app 的 build.gradle 加一句 implementation pag 引入 pag 才能用：
implementation 'com.tencent.tav:libpag:4.3.33-noffavc'
如果您想动态下载 pag 的 so，请从 pag 官网 找到您需要的版本，下载 aar，将 .aar 重命名为 .zip，解压，剔除其中的 so，再把剩余文件压缩为 .zip，然后重命名为 .aar，最后引入这个不包含 so 的 pag aar，pag 的 so 则联网动态下载。
7. Android 常见错误码
7.1. 通用错误码
错误码 | 含义 | 排查建议 |
0 | 成功 | 无异常，接口调用成功。 |
-1 | 未知错误 | 未被具体错误码分类的兜底错误。请先查看 Logcat 中 Xmagic / Light tag 的详细日志。 |
7.2. 初始化阶段错误码
XmagicApi 构造与销毁生命周期相关的错误。
错误码 | 含义 | 排查建议 |
-10000 | SDK 尚未初始化。 | 在调用其他接口前必须先成功构造 XmagicApi，检查是否漏掉初始化或初始化已失败。 |
-10010 | so 动态库加载失败。 | 检查 APK 是否包含目标 ABI 的 so 文件、abiFilters 配置是否正确、是否被裁剪，如果是动态加载 so 可以先忽略。 |
-10020 | SDK 未授权。 | License 未通过校验，确认 LicenseKey/LicenseUrl 已下发且包名一致，检查网络是否可访问 license 服务。 |
-10025 | 资源目录参数为 null 或空串。 | 调用方传入的 resDir 为空。与 -10030 区分：本错误属于传参问题，请检查上层传参逻辑。 |
-10030 | 资源模型目录不存在。 | 路径合法但磁盘上找不到，检查资源包是否已解压到期望路径、路径是否被应用清理策略删除。 |
-10040 | template.json 不存在。 | 资源目录下缺少 template.json，检查资源包完整性。 |
-10050 | 人脸模型文件不存在。 | 缺少人脸检测模型文件，重新拷贝完整模型资源。 |
-10060 | 必需模型文件不完整。 | 部分模型文件缺失，通常是资源拷贝中断，重新拷贝完整资源包。 |
-10070 | 加载空模板失败。 | Light 引擎加载空模板失败，附上日志联系技术支持。 |
-10080 | 空模板素材返回错误码。 | 空模板资源报错，附上 Light 层日志排查。 |
-10090 | Light 引擎创建失败。 | Light 引擎无法构建，通常伴随其他 C++ 层错误，检查设备 GL 环境与授权。 |
-10100 | 初始化过程中抛出未处理异常。 | init 调用栈内部抛出 Throwable（含 RuntimeException / UnsatisfiedLinkError / OOM 等），需查看 Logcat 中的堆栈信息。与 -1 区分：走到了 catch 兜底。 |
-10110 | SDK 已被销毁后又被调用。 | onDestroy 之后不允许再调用 XmagicApi 的方法，检查生命周期管理，避免销毁后仍持有并使用旧实例。 |
7.3. setEffect 错误码
调用 setEffect 设置素材/滤镜/美妆时产生的错误码。
错误码 | 含义 | 排查建议 |
-30000 | 特效名称为空。 | 检查 setEffect 的 name 参数，禁止空串。 |
-30010 | 轻美妆 JSON 不存在。 | 轻美妆资源目录下缺少 JSON 文件，检查资源包完整性。 |
-30020 | 轻美妆 JSON 内容为空。 | 轻美妆 JSON 为空文件，重新下发资源。 |
-30030 | 不支持 GAN 美颜。 | GAN 美颜需要单独授权与设备支持，联系商务确认。 |
-30040 | 特效模板 JSON 不存在。 | 素材路径下缺少 template.json，检查资源包完整性。 |
-30050 | 分割类型无效。 | 传入的分割类型枚举值非法。 |
-30060 | 分割背景类型无效。 | 分割背景类型枚举值非法。 |
-30070 | 分割背景路径无效。 | 分割背景文件路径为空或不存在。 |
7.4. 背景分割错误码
视频/图片背景替换（setEffect 中 seg 类型）相关的错误码。
错误码 | 含义 | 排查建议 |
-20000 | 未授权使用背景分割。 | 分割能力需要单独授权，联系商务开通。 |
-20010 | 背景资源路径为空。 | 检查传入的背景路径参数，禁止 null 或空串。 |
-20020 | 背景资源路径无效。 | 路径格式非法或文件不存在，检查路径拼写与文件权限。 |
-20030 | 背景类型无效。 | 背景类型枚举传入错误，参见 XmagicConstant 中的 seg 背景类型定义。 |
-20040 | 背景图分辨率超过 2160×3840。 | 请将图片下采样至 2160×3840 以内后再传入。 |
-20050 | 背景图旋转角度不支持。 | 背景图不支持带旋转角度，如果图片有旋转角度，可以先在外部进行处理。 |
-20060 | 背景图内存不足。 | 图片过大导致解码 OOM，压缩后再传入或释放内存后重试。 |
-20070 | 背景图解码失败。 | 图片文件损坏或格式不支持，尝试转换为标准 JPEG / PNG。 |
-20080 | 背景视频格式不支持。 | 仅支持常见 mp4 编码，检查视频容器与编码格式。 |
-20090 | 背景视频时长超过 200 秒。 | 请裁剪视频至 200 秒以内。 |
-20100 | 背景视频解析异常。 | MediaExtractor 解析失败，检查视频文件完整性。 |
-20110 | 基础分割类型无效。 | 传入的基础分割枚举值非法，对照文档更正。 |
7.5. process 阶段错误码
XmagicApi.process 每帧处理阶段产生的错误码，包含 Java 层错误（-40000 ~ -40100）与 Light 引擎 C++ 层错误（-2 ~ -1801，涉及素材加载、设备/版本兼容性、授权、图像内容合法性检测等）。
错误码 | 含义 | 排查建议 |
-40000 | 输入纹理尺寸非法。 | 纹理宽高为 0 或超出限制，检查上游 CameraX / TextureView 的输出。 |
-40010 | 按路径加载素材失败。 | 素材文件路径错误或磁盘 IO 异常。 |
-40020 | 素材加载伴随错误。 | 素材已加载但内部报错，附上 Light 层日志排查。 |
-40030 | 素材更新失败。 | 更新素材参数失败，检查参数合法性。 |
-40040 | 素材更新被忽略。 | 更新未生效（如状态相同），确认是否需要强制刷新。 |
-40050 | 合并素材上下文错误。 | 素材合并流程内部错误，附上日志排查。 |
-40060 | 合并素材添加失败。 | 合并素材时添加子素材失败。 |
-40070 | 合并素材导出失败。 | 合并结果导出失败。 |
-40080 | 渲染时相机配置为空。 | SDK 内部错误 cameraConfig 为 null。 |
-40090 | 渲染视频输出为空。 | SDK 内部 videoOutput 为 null。 |
-40100 | 输入 Bitmap 为空。 | 检查图片美颜的输入参数。 |
-2 | 模板 JSON 路径为空。 | 检查传入的素材路径参数是否为 null 或空串。 |
-100 | 3D 引擎资源不存在。 | 确认 3D 模型文件完整，是否在拷贝或解压过程中丢失文件。 |
-200 | 不支持 GAN 素材。 | GAN 类素材需要单独授权与设备支持，联系商务/技术支持确认权限。 |
-300 | 设备不支持此素材。 | 素材声明的最低设备要求高于当前设备，需更换设备或使用低配版素材。 |
-400 | 模板 JSON 内容为空。 | 素材 template.json 文件为空，检查素材包是否损坏。 |
-500 | SDK 版本低于素材版本。 | 升级 SDK 至素材要求的最低版本，或使用更旧版本的素材。 |
-600 | 不支持抠头素材。 | 抠头能力需要授权与设备支持，联系商务确认。 |
-700 | OpenGL 版本不支持。 | 素材所需 OpenGL 版本高于当前设备，无法在该设备使用。 |
-800 | 不支持 JavaScript 脚本。 | 当前 SDK 未启用 JS 能力，联系商务开启或换素材。 |
-900 | 不支持被裁剪的组件。 | 素材中包含裁剪组件，SDK 不支持。 |
-1000 | 不支持分割。 | 分割能力未授权或设备不支持，需要开通分割授权。 |
-1100 | 不支持 Filament。 | 当前 SDK 不含 Filament 能力，联系商务开启或换素材。 |
-1200 | 不支持多 GLContext（共享上下文）。 | 当前设备/驱动不支持共享 GLContext，检查渲染线程与 EGLContext 配置。 |
-1300 | UE 渲染失败。 | UE 渲染环节报错，检查 Light 层日志与 GPU 状态。 |
-1400 | 模板 JSON 缺少 root 节点。 | 素材 template.json 结构非法，请让素材侧修复。 |
-1500 | 不支持 Filament 骨骼动画。 | 骨骼动画能力未启用，联系商务或更换素材。 |
-1600 | ClipAsset 加载失败。 | 剪辑类素材加载失败，检查文件完整性与磁盘权限。 |
-1700 | License 校验失败。 | 授权信息无效或过期，检查 LicenseKey/LicenseUrl 是否正确、是否已过期、包名是否匹配。 |
-1800 | 检测到输入图像为黑屏。 | 输入纹理全黑，检查相机是否正常出图、纹理绑定是否正确。 |
-1801 | 检测到输入图像为白屏。 | 输入纹理全白，检查上游图像来源。 |
7.6. 历史 XMagicError（已废弃）
以下错误码仅在 SDK 4.2.0 及之前版本 使用，通过 OnXmagicPropertyErrorListener 回调。当前版本已由 TEErrorCode 中 -20040 ~ -20090 系列替代，仅为兼容存量客户保留。
错误码 | 含义 | 排查建议 |
5000 | 背景图分辨率超过 2160×3840。 | 等价于 TE_BACKGROUND_IMAGE_RESOLUTION_EXCEEDS_2160_3840（-20040）。 |
5001 | 背景图内存不足。 | 等价于 TE_BACKGROUND_IMAGE_MEMORY_INSUFFICIENT（-20060）。 |
5002 | 背景视频解析失败。 | 等价于 TE_BACKGROUND_VIDEO_PARSE_EXCEPTION（-20100）。 |
5003 | 背景视频时长超过 200 秒。 | 等价于 TE_BACKGROUND_VIDEO_OVER_200_SECONDS（-20090）。 |
5004 | 背景视频格式不支持。 | 等价于 TE_BACKGROUND_VIDEO_FORMAT_NOT_SUPPORTED（-20080）。 |
5005 | 背景图旋转角度不支持。 | 等价于 TE_BACKGROUND_IMAGE_ROTATION_ANGLE（-20050）。 |
