常见问题

​

集成

​

引擎构造抛异常或一直无法就绪

• IllegalArgumentException：EngineConfig 需要非空 licenseToken，或者同时提供 appId 与 appKey
• 在控制台绑定的 应用包名 必须与当前 App 一致
• 在线鉴权需能访问 /facebetter/v2/auth
• 监听 EngineEventCode.LICENSE_VALIDATION_FAILED / INITIALIZATION_FAILED
• 在 new BeautyEffectEngine(...) 之前 调用 setLogConfig

​

编译找不到 net.pixpark.facebetter

• Maven：implementation 'net.pixpark:facebetter:2.0.0'
• 本地 AAR：implementation files('libs/facebetter.aar') 后 Sync
• Clean / Rebuild

​

运行时 UnsatisfiedLinkError

• 设备 ABI 须为 arm64-v8a 或 armeabi-v7a
• 开启混淆 / 缩减时保留 libfacebetter.so，并在 ProGuard / R8 中保留 Facebetter 的 native 方法
• 确认 AAR / Maven 产物完整

​

效果

​

美颜不明显

• 在 [0, 1] 内加大 setSmoothing、setWhitening、美妆等强度
• 整形范围是 [-1, 1]，接近 0 几乎等于关闭
• 确认收到 INITIALIZATION_COMPLETE，且 processImage 返回非空帧
• 通过 onFaceLandmarks 查看关键点（空列表表示未检测到人脸）

​

脸型变形过度

• 减小 setReshape 的绝对值；改符号会反向
• 避免多个整形参数同时拉到很大
• 静图导出可用 FrameType.IMAGE；直播 VIDEO 更偏流畅而非更强效果

​

虚拟背景无效

• 调用 setVirtualBackgroundBlur(level) 且 level > 0，或 setVirtualBackground(path|bytes)
• setVirtualBackgroundBlur(0) 会清除效果
• 图片路径必须是可读的 PNG/JPG；空路径返回 ErrorCode.INVALID_ARGUMENT
• 绿幕：setChromaKey(ChromaKeyColor.GREEN) 并配合填充（模糊或图片）
• clearChromaKey() 只恢复肖像遮罩，不会去掉填充

​

滤镜或贴纸不出现

• 向 setFilter / setSticker 传入 .fbd 的 路径或字节（没有注册接口）
• 在下一次 processImage 后生效
• externalContext = true 时，该调用必须在已绑定的 GL 上下文中执行
• setFilterIntensity(0) 会让 LUT 看不见

​

性能与内存

​

预览卡顿

• input.type = ImageFrame.FrameType.VIDEO
• 降低采集分辨率
• 减少同时开启的整形 / 美妆 / 虚拟背景
• 在相机或 GL 线程执行 processImage，不要放在主线程
• 查看 engine.getStats().avgProcessTimeMs
• 相册大图：打开时做较小预览帧，导出再打原图。见 最佳实践

​

内存持续上涨或原生崩溃

• 每个 ImageFrame 都要 release()，包括 convert() 结果和 processImage 输出
• 使用 ByteBuffer.allocateDirect
• 全程一个引擎实例；在 onDestroy 调用 engine.release()

​

ANR

• 不要在 UI 线程对高清视频跑 processImage
• 不要在主线程加载大型 .fbd / JPEG

​

图像与相机

​

如何转换像素格式？

ImageFrame rgba = frame.convert(ImageFrame.Format.RGBA);
ImageFrame nv21 = frame.convert(ImageFrame.Format.NV21);
ImageFrame i420 = frame.convert(ImageFrame.Format.I420);

​

Camera2 预览

1. 从 YUV_420_888 得到 Image
2. ImageFrame.createWithAndroid420(...)
3. 按传感器与前置摄像头 rotate / mirror
4. input.type = FrameType.VIDEO
5. processImage(input)
6. convert 或 getTexture() 后显示

​

旋转

​

权限

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

​

调试

BeautyEffectEngine.LogConfig logConfig = new BeautyEffectEngine.LogConfig();
logConfig.consoleEnabled = true;
logConfig.fileEnabled = true;
logConfig.level = BeautyEffectEngine.LogLevel.DEBUG;
logConfig.fileName = getFilesDir() + "/facebetter.log";
BeautyEffectEngine.setLogConfig(logConfig);

​

兼容性

• Android 7.0（API 24）及以上
• ABI：arm64-v8a、armeabi-v7a
• Maven：net.pixpark:facebetter:2.0.0