大家好,我是[晚风依旧似温柔],新人一枚,欢迎大家关注~

前言

在开发带有相机拍摄功能的应用时,很多开发者都会遇到一个非常经典的疑问:为什么前置摄像头预览的时候,画面看起来是正常的(像照镜子一样),但是录制下来的视频,回放时左右却反了?如果衣服上有字,预览时是正的,录下来的视频里字反倒变成了镜像?

这并不是系统的 Bug,而是由物理相机传感器的成像原理,以及人类日常“照镜子”的心理习惯共同决定的。

对于 HarmonyOS 应用开发者而言,如何根据业务需求,正确地处理前置相机的镜像问题,不仅关乎代码的实现,更关乎用户体验。本文将结合 HarmonyOS Camera Kit 的最新官方能力,详细梳理视频输出(VideoOutput)镜像功能的实践方法。

一、前置相机镜像与真实画面的区别

在动手写代码之前,我们需要先理清三个概念:物理真实画面、预览画面、最终输出视频。

  1. 物理真实画面:摄像头传感器捕捉到的画面,就是现实世界客观存在的方向。别人看你是什么样,传感器抓取的就是什么样。
  2. 预览画面 (PreviewOutput):为了符合人类照镜子的习惯,几乎所有的操作系统在调用前置摄像头进行预览时,都会在底层自动对画面做一次“水平翻转(镜像)”。如果不做镜像,当你向左歪头时,屏幕里的你会向右歪头,这会导致严重的操作眩晕感。
  3. 最终输出视频 (VideoOutput):默认情况下,视频录制输出的流是物理真实的流(即没有经过镜像翻转的)。

这也就是为什么会出现“预览正常,录像反了”的原因。在很多社交类、自拍类应用中,用户希望“所见即所得”——预览里是什么样,保存下来的 .mp4 文件就是什么样。这就要求我们在代码层面,手动为 VideoOutput 开启镜像能力。

二、先把官方规则弄清楚

在 HarmonyOS 的 @ohos.multimedia.camera 模块中,控制视频录制流的关键类是 VideoOutput。

根据 HarmonyOS Camera Kit 的接口定义,处理镜像的核心步骤分为两步:

  1. 能力查询 (isMirrorSupported):并不是所有的硬件设备、在所有的分辨率和帧率下都支持硬件级或底层流级的镜像翻转。直接调用设置接口可能会抛出异常或无效,因此必须先查询。
  2. 状态设置 (setMirror):根据查询结果和业务逻辑,传入布尔值来开启或关闭镜像。

前置条件:

  • 需要申请 ohos.permission.CAMERA 权限。
  • 视频录制还需要 ohos.permission.MICROPHONE 和媒体读取相关权限。
  • API Level 至少需要关注到 API 11/12(当前 HarmonyOS NEXT 的主流适配版本),此时 Camera 接口已全面采用 Promise/Async 风格。

三、核心代码实现:检查与开启镜像

下面这段代码按照官方文档提供的接口,组织为一个最小示例。重点展示在配置相机会话(Camera Session)时,如何正确处理 VideoOutput 的镜像。

import camera from '@ohos.multimedia.camera';
import { BusinessError } from '@ohos.base';

/**
 * 这是一个专门处理视频录制流镜像的工具函数示例
 * 
 * @param videoOutput 已经创建好的视频输出流对象
 * @param isFrontCamera 当前是否为前置摄像头
 * @param userWantsMirror 用户是否在设置中开启了“保存镜像视频”
 */
function configureVideoMirror(
  videoOutput: camera.VideoOutput, 
  isFrontCamera: boolean, 
  userWantsMirror: boolean
): void {
  
  // 1. 只有前置摄像头才考虑开启镜像,后置摄像头通常不需要镜像
  if (!isFrontCamera) {
    try {
      // 如果当前是后置,强制关闭镜像,防止切换摄像头时状态残留
      if (videoOutput.isMirrorSupported()) {
        videoOutput.setMirror(false);
        console.info('Camera_Log: Rear camera, mirror disabled.');
      }
    } catch (error) {
      let err = error as BusinessError;
      console.error(`Camera_Log: Failed to disable mirror. Code: ${err.code}`);
    }
    return;
  }

  // 2. 前置摄像头的处理逻辑
  try {
    // 关键步骤:查询当前设备/配置是否支持镜像
    let isSupported = videoOutput.isMirrorSupported();
    console.info(`Camera_Log: Is mirror supported? ${isSupported}`);

    if (isSupported) {
      // 3. 开启或关闭镜像 (enableMirror 逻辑)
      // 根据用户的偏好设置决定是否开启
      videoOutput.setMirror(userWantsMirror);
      console.info(`Camera_Log: Video mirror set to ${userWantsMirror}`);
    } else {
      // 不支持时的降级处理
      console.warn('Camera_Log: This device does not support video mirroring for current config.');
    }
  } catch (error) {
    let err = error as BusinessError;
    console.error(`Camera_Log: Failed to check or set mirror. Code: ${err.code}`);
  }
}

【建议插图1:DevEco Studio 侧边栏预览日志,展示 isMirrorSupported 返回 true,以及成功设置的日志输出】

代码关键点解析:

真正需要关注的是查询 isMirrorSupported() 这个动作。相机的视频流处理会消耗大量的系统资源(ISP和DSP)。在部分低端设备,或者当开发者设置了 4K 60fps 这种极高规格的 Profile 时,底层可能无法同时提供额外的镜像翻转能力。强制调用 setMirror(true) 会导致不可预知的崩溃。

四、前后摄像头切换时的注意事项

在实际应用中,用户会在录制前或录制过程中(部分高阶设备支持)切换前后摄像头。

这里比较容易理解错:镜像状态是挂载在 VideoOutput 对象上的,而不是跟着摄像头自身走的。

如果在前置状态下调用了 videoOutput.setMirror(true),随后用户点击了切换摄像头,应用重新配置了后置摄像头(CAMERA_POSITION_BACK)的输入流 CameraInput,但复用了同一个 VideoOutput。此时,如果不显式地去重置镜像状态,录制出来的后置视频也会变成左右颠倒的!

正确做法:
每次执行相机会话的切换(session.beginConfig() 到 session.commitConfig() 之间),只要 CameraInput 发生了变化,就必须重新调用一次前文示例中的 configureVideoMirror() 函数,重新校验并重置 VideoOutput 的镜像参数。

五、不支持设备的降级处理与用户设置

如果 isMirrorSupported() 返回了 false,应用该怎么办?

  1. UI 降级:很多自拍应用会在相机的设置面板提供一个“自拍镜像保存”的 Switch 开关。如果 API 返回不支持,这个开关应当被禁用(置灰),并提示用户“当前设备或分辨率暂不支持视频镜像”。
  2. 后期处理补偿:如果业务上强依赖视频镜像,而在 Camera 录制阶段系统不支持,开发者可以考虑在录制完成后,借助 @ohos.multimedia.media 或者 OpenGL / WebGL / AVPlayer 播放渲染时,在播放端或编辑端做水平翻转。但这属于后处理范畴,会增加耗时和性能开销。

用户设置是否应该保存?
从产品体验角度来看,是否开启镜像属于用户的强烈个人偏好。建议使用 @ohos.data.preferences(用户首选项)将该状态持久化。每次启动相机初始化流时,读取 Preference 的值,再结合 isMirrorSupported() 共同决定最终的 setMirror 参数。

六、容易踩坑的地方

根据官方接口设计,以下几个细节值得单独注意:

  1. 设置时机:对 VideoOutput 属性的修改(包括设置镜像),应当在将其添加到 Session 并 commitConfig() 之前,或者在配置阶段完成。如果视频正在录制中(start() 已经调用),此时去动态调用 setMirror() 可能会抛出异常或不生效。
  2. 别把 PreviewOutput 和 VideoOutput 弄混:PreviewOutput 也有镜像能力,但正如前文所述,系统底层通常会对前置预览做默认镜像。业务代码中手动设置的,主要是 VideoOutput(录制)和 PhotoOutput(拍照)。这两者的能力是独立查询、独立设置的(例如 photoOutput.isMirrorSupported())。
  3. 折叠屏设备的形态变化:当折叠屏从闭合态展开为大屏态时,如果相机流因窗口变化而发生重建,务必确保在重建 VideoOutput 时,重新赋予之前保存的镜像状态。

七、实际项目中怎么排查镜像问题

如果测试团队反馈:“前置录像保存下来左右还是反的”,可以通过以下清单按顺序排查:

  1. 看镜头位置:确认当时构建 CameraInput 时,读取的确实是 CAMERA_POSITION_FRONT。
  2. 看 API 调用顺序:确认 setMirror(true) 是否在 VideoOutput 创建成功后、视频真正开始录制(start)之前被调用。
  3. 看能力查询结果:抓取 Hilog 日志,搜索 isMirrorSupported 的返回值。如果是 false,说明是设备底层限制,代码逻辑本身没有错,需要转为 UI 提示或后处理方案。
  4. 看会话重置:如果一开始是好的,切换了一次前后镜头后失效了,重点排查前后镜头切换时,是否漏掉了对 VideoOutput 状态的重新赋值。

八、最后整理一下

  1. 预览和录像是独立的数据流,前置预览系统一般会自动镜像,但录像默认输出真实物理画面。
  2. 在处理 VideoOutput 镜像前,绝对不能省略 isMirrorSupported() 的校验,这是保证应用稳定性的底线。
  3. 镜像状态不会根据摄像头的切换自动重置,开发者需要在前后置切换的业务逻辑中,手动维护 VideoOutput 的镜像开启与关闭。

通过合理的 Camera 状态管理,结合 HarmonyOS 提供的明确的能力查询接口,我们完全可以做到相机应用在多设备上的平滑体验。如果你正在做全屏相机适配,可以重点观察一下自己的页面在前后置切换时,日志里是否依然保持着干净的状态校验流,这类隐式状态的管理往往比单纯的 UI 布局更考验基本功。

参考资料

  1. 《Camera Kit 简介与开发指导》
    华为开发者联盟
    链接:https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/camera-overview-V5
  2. 《VideoOutput 视频输出 API 参考》
    华为开发者联盟
    链接:https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V5/js-apis-camera-V5#videooutput

如果觉得有帮助,别忘了点个赞+关注支持一下~
喜欢记得关注,别让好内容被埋没~

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐