HarmonyOS 鸿蒙Next中Camera API 扩展 — 在 VideoOutput 中增加 crop region 支持，允许录制时直接指定有效画面区域

HarmonyOS 鸿蒙Next中Camera API 扩展 — 在 VideoOutput 中增加 crop region 支持，允许录制时直接指定有效画面区域

问题描述

在 HarmonyOS 应用开发中，无法将录制的视频按照指定的画幅比（如 2.39:1、1.85:1 等）裁剪后导出/分享。

具体场景： 相机类应用需要在录制后导出非 16:9 画幅比的视频（如电影级 2.39:1 宽银幕），并在分享时保持该画幅比。当前系统分享视频时统一为 16:9，无法保留应用内设定的画幅比。

当前 HarmonyOS API 现状

API 能力 局限
AVTranscoder 可设置输出分辨率（240-3840 × 240-2160） 缩放而非裁剪，画面变形，无法实现裁剪效果
VideoOutput（Camera） 录制视频 无 crop region 支持，PreconfigRatio 仅支持 1:1、4:3、16:9
videoDecoder + videoEncoder 逐帧解码/编码 无硬件加速裁剪管线，需逐帧 PixelMap 操作，性能极差

对比平台能力

iOS（AVFoundation）

  • AVAssetExportSession + AVVideoComposition + AVMutableVideoCompositionInstruction
  • 可直接指定 renderSize 和通过 transform 设置裁剪区域
  • 底层硬件加速，处理速度快（秒级完成）
  • 大量专业相机 App（如 FiLMiC Pro、Blackmagic Camera）均依赖此能力

Android（MediaCodec）

  • MediaCodec + MediaMuxer 支持裁剪编码
  • MediaMetadataRetriever 可提取帧
  • 第三方库（如 mp4parser）可实现无重编码裁剪

诉求

  1. Camera API 扩展 — 在 VideoOutput 中增加 crop region 支持，允许录制时直接指定有效画面区域

建议的 API 形态

// 方案一：AVTranscoder 扩展裁剪能力
let transcoder = new AVTranscoder()
transcoder.setOutputParameter({
  videoFrameWidth: 1920,
  videoFrameHeight: 804,
  cropRect: { x: 0, y: 138, width: 1920, height: 804 }  // 从原始帧中央裁剪
})

// 方案二：新增 AVVideoComposition 类（参考 iOS）
let composition = new AVVideoComposition()
composition.renderSize = { width: 1920, height: 804 }
composition.addInstruction({
  cropRect: { x: 0, y: 138, width: 1920, height: 804 },
  sourceTrack: videoTrack
})
let exporter = new AVAssetExporter(composition)
exporter.export(outputURL)

应用场景

  • 专业相机/摄影 App（电影画幅比拍摄）
  • 视频编辑工具（裁剪、重新构图）
  • 社交媒体应用（竖屏/方屏视频导出）
  • 短视频平台（多画幅比适配）

环境信息

  • HarmonyOS 版本：6.0（API 20）
  • 开发工具：DevEco Studio 5.0
  • 测试设备：Pura X 典藏版等所有 HarmonyOS 6.0 手机

反馈人：MTVF 开发团队 日期：2026-05-08


更多关于HarmonyOS 鸿蒙Next中Camera API 扩展 — 在 VideoOutput 中增加 crop region 支持，允许录制时直接指定有效画面区域的实战教程也可以访问 https://www.itying.com/category-93-b0.html

4 回复

尊敬的开发者，您好！该功能正在规划中，还请关注后续版本，感谢您的理解与支持。

更多关于HarmonyOS 鸿蒙Next中Camera API 扩展 — 在 VideoOutput 中增加 crop region 支持，允许录制时直接指定有效画面区域的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html


帮顶！

HarmonyOS Next Camera Kit 的 VideoOutput 支持通过 setCropRegion(Rect) 方法设置录制区域。该方法接受一个 Rect 对象，指定相对于传感器输出分辨率的裁剪矩形。配置后，录制的视频仅包含该矩形内的画面，不影响预览或拍照输出。需确保 Rect 在有效范围内且宽高比与编码配置匹配。，

HarmonyOS Next当前视频处理管线在录制阶段的裁剪确实是能力空白。核心问题不在于输出分辨率调整，而在于有效像素区域的偏移提取——AVTranscoder的setOutputParameter仅做拉伸适配，画面变形不可避免。

你提出的crop region参数思路是正确的，实际需要的是在编解码管线中插入一个硬件加速的裁剪节点。目前VideoOutput的PreconfigRatio枚举值完全不够用，缺少类似CropRegion的元数据注入能力。

期望的理想状态是VideoOutput或AVTranscoder支持类似参数：

transcoder.setVideoCropRegion({
  left: 0,
  top: 138,   
  width: 1920, 
  height: 804  // 从16:9画幅裁出2.39:1
})

但这个API目前不存在。问题根源在于HarmonyOS的多媒体引擎在视频通路中，编码前处理和显示坐标转换是分离的，crop在显示层有方案（通过XComponent的setCropRegion），但编码层没有对应实现。要同步编码流的裁剪区域，需要修改底层buffer分配和编码器配置，这涉及系统多媒体服务。

临时方案可以结合XComponent预览时裁剪+录制后使用AVTranscoder二次处理——但体验会变差。这个需求的核心价值在专业影像场景，需要在官方渠道作为VideoOutput/AVTranscoder功能需求明确提出，明确标注期望的是编码阶段的crop region支持而不仅仅是分辨率适配。

回到顶部