自拍录像为什么左右反了?Camera 视频镜像能力实践【鸿蒙心迹】

大家好,我是[晚风依旧似温柔],新人一枚,欢迎大家关注~
本文目录:
前言
在开发带有相机拍摄功能的应用时,很多开发者都会遇到一个非常经典的疑问:为什么前置摄像头预览的时候,画面看起来是正常的(像照镜子一样),但是录制下来的视频,回放时左右却反了?如果衣服上有字,预览时是正的,录下来的视频里字反倒变成了镜像?
这并不是系统的 Bug,而是由物理相机传感器的成像原理,以及人类日常“照镜子”的心理习惯共同决定的。
对于 HarmonyOS 应用开发者而言,如何根据业务需求,正确地处理前置相机的镜像问题,不仅关乎代码的实现,更关乎用户体验。本文将结合 HarmonyOS Camera Kit 的最新官方能力,详细梳理视频输出(VideoOutput)镜像功能的实践方法。
一、前置相机镜像与真实画面的区别
在动手写代码之前,我们需要先理清三个概念:物理真实画面、预览画面、最终输出视频。
- 物理真实画面:摄像头传感器捕捉到的画面,就是现实世界客观存在的方向。别人看你是什么样,传感器抓取的就是什么样。
- 预览画面 (PreviewOutput):为了符合人类照镜子的习惯,几乎所有的操作系统在调用前置摄像头进行预览时,都会在底层自动对画面做一次“水平翻转(镜像)”。如果不做镜像,当你向左歪头时,屏幕里的你会向右歪头,这会导致严重的操作眩晕感。
- 最终输出视频 (VideoOutput):默认情况下,视频录制输出的流是物理真实的流(即没有经过镜像翻转的)。
这也就是为什么会出现“预览正常,录像反了”的原因。在很多社交类、自拍类应用中,用户希望“所见即所得”——预览里是什么样,保存下来的 .mp4 文件就是什么样。这就要求我们在代码层面,手动为 VideoOutput 开启镜像能力。
二、先把官方规则弄清楚
在 HarmonyOS 的 @ohos.multimedia.camera 模块中,控制视频录制流的关键类是 VideoOutput。
根据 HarmonyOS Camera Kit 的接口定义,处理镜像的核心步骤分为两步:
- 能力查询 (
isMirrorSupported):并不是所有的硬件设备、在所有的分辨率和帧率下都支持硬件级或底层流级的镜像翻转。直接调用设置接口可能会抛出异常或无效,因此必须先查询。 - 状态设置 (
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,应用该怎么办?
- UI 降级:很多自拍应用会在相机的设置面板提供一个“自拍镜像保存”的 Switch 开关。如果 API 返回不支持,这个开关应当被禁用(置灰),并提示用户“当前设备或分辨率暂不支持视频镜像”。
- 后期处理补偿:如果业务上强依赖视频镜像,而在 Camera 录制阶段系统不支持,开发者可以考虑在录制完成后,借助
@ohos.multimedia.media或者 OpenGL / WebGL / AVPlayer 播放渲染时,在播放端或编辑端做水平翻转。但这属于后处理范畴,会增加耗时和性能开销。
用户设置是否应该保存?
从产品体验角度来看,是否开启镜像属于用户的强烈个人偏好。建议使用 @ohos.data.preferences(用户首选项)将该状态持久化。每次启动相机初始化流时,读取 Preference 的值,再结合 isMirrorSupported() 共同决定最终的 setMirror 参数。
六、容易踩坑的地方
根据官方接口设计,以下几个细节值得单独注意:
- 设置时机:对
VideoOutput属性的修改(包括设置镜像),应当在将其添加到Session并commitConfig()之前,或者在配置阶段完成。如果视频正在录制中(start()已经调用),此时去动态调用setMirror()可能会抛出异常或不生效。 - 别把 PreviewOutput 和 VideoOutput 弄混:
PreviewOutput也有镜像能力,但正如前文所述,系统底层通常会对前置预览做默认镜像。业务代码中手动设置的,主要是VideoOutput(录制)和PhotoOutput(拍照)。这两者的能力是独立查询、独立设置的(例如photoOutput.isMirrorSupported())。 - 折叠屏设备的形态变化:当折叠屏从闭合态展开为大屏态时,如果相机流因窗口变化而发生重建,务必确保在重建
VideoOutput时,重新赋予之前保存的镜像状态。
七、实际项目中怎么排查镜像问题
如果测试团队反馈:“前置录像保存下来左右还是反的”,可以通过以下清单按顺序排查:
- 看镜头位置:确认当时构建
CameraInput时,读取的确实是CAMERA_POSITION_FRONT。 - 看 API 调用顺序:确认
setMirror(true)是否在VideoOutput创建成功后、视频真正开始录制(start)之前被调用。 - 看能力查询结果:抓取 Hilog 日志,搜索
isMirrorSupported的返回值。如果是false,说明是设备底层限制,代码逻辑本身没有错,需要转为 UI 提示或后处理方案。 - 看会话重置:如果一开始是好的,切换了一次前后镜头后失效了,重点排查前后镜头切换时,是否漏掉了对
VideoOutput状态的重新赋值。
八、最后整理一下
- 预览和录像是独立的数据流,前置预览系统一般会自动镜像,但录像默认输出真实物理画面。
- 在处理
VideoOutput镜像前,绝对不能省略isMirrorSupported()的校验,这是保证应用稳定性的底线。 - 镜像状态不会根据摄像头的切换自动重置,开发者需要在前后置切换的业务逻辑中,手动维护
VideoOutput的镜像开启与关闭。
通过合理的 Camera 状态管理,结合 HarmonyOS 提供的明确的能力查询接口,我们完全可以做到相机应用在多设备上的平滑体验。如果你正在做全屏相机适配,可以重点观察一下自己的页面在前后置切换时,日志里是否依然保持着干净的状态校验流,这类隐式状态的管理往往比单纯的 UI 布局更考验基本功。
参考资料
- 《Camera Kit 简介与开发指导》
华为开发者联盟
链接:https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/camera-overview-V5 - 《VideoOutput 视频输出 API 参考》
华为开发者联盟
链接:https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V5/js-apis-camera-V5#videooutput
如果觉得有帮助,别忘了点个赞+关注支持一下~
喜欢记得关注,别让好内容被埋没~
更多推荐


所有评论(0)