CameraX 接入美颜 SDK 的 12 个关键问题：黑屏、镜像、拉伸和掉帧怎么排查

项目地址：18818474455/ChromaBeautySDK

做相机类 App 时，美颜 SDK 的接入难点往往不在“有没有磨皮、美白、调色参数”，而在相机帧能不能稳定地进入渲染链路。

很多团队第一次接实时美颜时，会遇到这些现象：

• 相机已经打开，但预览区域黑屏；
• 前置摄像头看着正常，保存照片左右反了；
• 人脸被拉宽或压扁；
• 滑动美颜参数时掉帧明显；
• 预览效果不错，拍照保存后颜色不一样；
• 切换前后摄像头偶发崩溃；
• 页面进入后台再回来，画面冻结。

这篇文章换一种形式，不从完整流程开始讲，而是把 Android 相机接入美颜 SDK 时最容易踩的点整理成 12 个检查项。下面内容结合 Chroma Beauty SDK 的移动端影像处理思路展开，重点是工程接入和排查方法。

说明一下边界：公开仓库主要用于展示能力、Demo 流程和接入思路，不包含正式 SDK 包、模型权重、授权密钥或私有源码。文中的代码是架构伪代码，实际 API 以正式接入文档为准。

1. 先确认相机链路还是渲染链路的问题

遇到黑屏时，不要第一时间怀疑美颜算法。更稳的排查顺序是：

如果普通 CameraX Preview 能正常显示，但接入美颜后黑屏，大概率是纹理、Surface 或 GL 上下文的问题。如果普通 Preview 也不显示，先排查相机权限、生命周期和 CameraX 用例绑定。

2. 实时预览优先走纹理，不要每帧转 Bitmap

实时美颜对性能很敏感。预览链路如果每帧都从 ImageProxy 转成 Bitmap，再交给美颜 SDK，很容易出现卡顿和发热。

更推荐的方向是：

CameraX / Camera2
-> SurfaceTexture / OES Texture
-> 美颜与调色处理
-> OpenGL 渲染
-> 屏幕预览

ImageAnalysis 可以保留，但更适合做低频分析，比如人脸检测、人体姿态、场景判断等。高频实时预览尽量走纹理路径，减少 CPU 拷贝和格式转换。

3. 前置摄像头镜像要统一策略

前置摄像头最容易出现两个问题：

• 预览是镜像的，拍照不是镜像的；
• 预览和拍照都镜像了，但人脸关键点或贴纸坐标没跟着变。

建议把镜像作为一个明确参数传入渲染层，而不是在不同模块里各自处理：

val mirror = lensFacing == CameraSelector.LENS_FACING_FRONT

beautyEngine.renderCameraFrame(
    textureId = frameTexture,
    rotation = frameRotation,
    mirror = mirror,
    beautyParams = beautyParams
)

产品上要先定清楚：保存的照片是否保持镜像。自拍产品常见做法是预览镜像，保存是否镜像由产品配置决定。关键是预览、拍照、录制要用同一套规则。

4. 旋转角不要临时猜

Android 相机方向受三个因素影响：

• 设备当前方向；
• 相机传感器方向；
• 前置或后置摄像头。

如果只在 UI 层把 View 旋转一下，拍照或录制时很容易出错。更稳的做法是把每帧需要的方向信息作为元数据传给渲染层：

这样美颜、贴纸、截图、录制和导出都能基于同一套信息工作。

5. 画面拉伸通常不是 SDK 问题

相机输出比例和屏幕比例经常不同。比如相机输出 4:3，手机屏幕是 20:9，如果直接把纹理铺满整个 View，人脸就会被拉伸。

常见策略有两种：

如果画面变形，先检查渲染矩阵和裁剪矩阵，不要马上调整美颜参数。美型、贴纸、人脸框和触摸对焦也要共用这套坐标映射，否则会出现效果漂移。

6. CameraX 用例不要绑得太贪

很多项目会同时绑定：

Preview + ImageAnalysis + ImageCapture + VideoCapture

这在高端机上问题不大，但部分机型可能因为分辨率组合、硬件能力或资源占用导致失败。建议先从最小集合开始：

Preview + ImageAnalysis

确认实时预览稳定后，再接入拍照和录制。遇到绑定失败时，可以降低目标分辨率，或者按机型做能力分级。

7. 切换摄像头要先释放旧资源

切换前后摄像头时，不要只改 lensFacing 再重新 bind。旧的 Surface、纹理、Camera 用例和渲染状态都需要明确处理。

推荐顺序：

暂停预览
-> 停止渲染提交
-> unbindAll
-> 释放旧纹理或 Surface
-> 切换 lensFacing
-> 重新创建预览目标
-> bindToLifecycle
-> 恢复渲染

如果跳过释放，可能出现偶发黑屏、旧画面残留、前后摄像头方向错乱等问题。

8. 美颜参数变化不应该重建引擎

滑杆拖动时，如果每次都重建美颜引擎、重新加载模型或重新创建 GL 资源，必然会卡。

更合理的方式是：

引擎初始化一次
-> 渲染线程持续工作
-> UI 滑杆只更新参数对象
-> 下一帧读取最新参数

参数对象最好是可复制、可序列化的结构。这样不仅适合实时预览，也方便做草稿保存、模板预设、默认值下发和最终导出。

9. 预览和导出要复用同一套参数

用户最敏感的问题之一是：屏幕上看着很好，保存后变了。

原因通常是预览和导出走了两套逻辑：

• 预览用了 A 套 LUT，导出用了 B 套 LUT；
• 预览降采样后没有同步高质量导出参数；
• 预览做了镜像，导出没做；
• 预览用了当前滑杆值，导出读到旧参数。

比较稳的结构是：

UI 参数
-> Chroma 参数对象
-> 实时预览
-> 拍照时复制同一份参数
-> 离屏高质量渲染
-> 保存文件

Chroma Beauty SDK 这类移动端人像处理链路，通常会把预览速度和导出质量分成不同档位，但参数语义应该保持一致。

10. 低端机要有质量档位

实时美颜不能只按旗舰机调试。低端设备上，最先暴露的问题通常是掉帧、发热和内存抖动。

建议至少准备三个质量档位：

在 Fast 模式下，可以降低预览分辨率、减少高成本效果、降低部分分析频率。最终保存时再切到更高质量路径。

11. 生命周期要比“打开和关闭”更细

相机页面并不只有打开和关闭两个状态。真实用户会做很多操作：

• 进入后台；
• 锁屏再回来；
• 切换页面；
• 横竖屏变化；
• 切换摄像头；
• 打开拍照或录制；
• 权限被系统回收。

建议把状态拆清楚：

Idle
-> PreparingCamera
-> CameraReady
-> EngineReady
-> Previewing
-> Capturing / Recording
-> Releasing

状态机不一定复杂，但要避免一堆布尔值到处飞。尤其是 isCameraReady、isEngineReady、isPreviewing 同时存在时，很容易在异步回调里互相打架。

12. 接入前准备一组固定测试样张和机型

相机美颜不要只用一台手机、一张自拍验证。建议至少准备这些测试场景：

• 前置自拍；
• 后置人像；
• 暗光环境；
• 强逆光；
• 多人合影；
• 舞台蓝光或彩色灯光；
• 白衣服、高光区域；
• 横屏和竖屏；
• 中低端 Android 机型；
• 切前后摄像头后连续拍照。

如果要评估 Chroma Beauty SDK 这类人像处理能力，还可以重点看肤色是否稳定、背景增强是否影响人脸、预览和导出是否一致、低端机是否有明显掉帧。

一个更清晰的接入骨架

下面是一段伪代码，用来表达工程结构，不代表公开仓库中的正式 API：

class BeautyCameraSession(
    private val lifecycleOwner: LifecycleOwner,
    private val renderView: BeautyRenderView
) {
    private var engine: ChromaBeautyEngine? = null
    private var cameraProvider: ProcessCameraProvider? = null
    private var lensFacing = CameraSelector.LENS_FACING_FRONT

    fun prepare() {
        engine = ChromaBeautyEngine.create(
            quality = ChromaQuality.Balanced
        )

        renderView.onFrameAvailable = { frame ->
            engine?.renderCameraFrame(
                textureId = frame.textureId,
                rotation = frame.rotation,
                mirror = lensFacing == CameraSelector.LENS_FACING_FRONT,
                colorParams = currentColorParams(),
                beautyParams = currentBeautyParams()
            )
        }

        bindCamera()
    }

    fun switchCamera() {
        stopPreview()
        releaseCameraOnly()
        lensFacing = if (lensFacing == CameraSelector.LENS_FACING_FRONT) {
            CameraSelector.LENS_FACING_BACK
        } else {
            CameraSelector.LENS_FACING_FRONT
        }
        bindCamera()
    }

    fun release() {
        cameraProvider?.unbindAll()
        renderView.release()
        engine?.release()
        engine = null
    }
}

真正接入时，可以根据项目选择 CameraX、Camera2、GLSurfaceView、TextureView 或自定义渲染容器。核心目标始终是：相机输出、方向镜像、裁剪矩阵、效果参数和渲染目标要清楚地连接起来。

小结

相机连接美颜 SDK，看起来只是“把相机画面传进去”，但实际会牵涉权限、Surface、纹理、GL 线程、方向、镜像、裁剪、生命周期和导出一致性。

如果接入初期能把这 12 个问题逐项确认，后面再叠加 AI 调色、人像保护、磨皮美白、美型、录制和导出，整体会稳很多。

Chroma Beauty SDK 的定位是把移动端 AI 调色、人像保护、美颜精修和预览导出组织成一套可接入的人像影像链路。对相机类 App 来说，先把采集和渲染链路接稳，效果能力才有发挥空间。

项目地址：18818474455/ChromaBeautySDK

维护者标识：cylbaw