Capture cinematic video in your app
Photos & Camera 进阶 0m

Capture cinematic video in your app

2025年6月9日

在 Apple 官方观看视频

一句话判断

Cinematic Video API 把电影模式的核心能力变成了几行 AVCaptureSession 配置 — 一个 isCinematicVideoCaptureEnabled = true 就能让所有输出获得浅景深效果，包括录视频、拍照、预览，甚至支持手动对焦和跟踪对焦。

这场 Session 讲了什么

Roy 演示了如何用 Cinematic Video API 构建完整的电影模式拍摄体验：

核心原理：电影模式的核心是浅景深（bokeh）和智能对焦。算法自动检测进入画面的主体并 rack focus 到他们，跟踪移动的主体，主体转头时自动切换焦点。

一行开启电影模式：在 AVCaptureDeviceInput 上设置 isCinematicVideoCaptureEnabled = true，整个 capture session 的所有输出自动获得电影效果。AVCaptureMovieFileOutput 产出的视频包含 disparity data、metadata 和原始视频，支持非破坏性编辑。AVCaptureVideoDataOutput 的帧直接带有浅景深效果。AVCaptureVideoPreviewLayer 实时渲染 bokeh。

格式要求：Dual Wide 和 TrueDepth 摄像头均支持 1080p 和 4K @ 30fps。支持 SDR（420 video range/full range）和 10-bit HDR（x420）。

三种手动对焦方式：

  1. setCinematicVideoTrackingFocus — 通过 detectedObjectID 对特定主体对焦，支持 strong（锁定跟踪）和 weak（算法可自动切换）模式。
  2. setCinematicVideoTrackingFocus(at:focusMode:) — 对画面中某一点对焦，算法会寻找该点的显著对象。
  3. setCinematicVideoFixedFocus — 固定焦距对焦，基于深度信息锁定特定平面。

UI 交互逻辑：点击未对焦的检测框 -> weak focus；点击已 weak focus 的检测框 -> 升级为 strong focus；点击空白区域 -> 寻找显著对象并 weak focus；长按 -> strong fixed focus。

高级特性：录制过程中可同时拍照（加 AVCapturePhotoOutput 即可，自动获得电影效果）。光线不足时通过 KVO cinematicVideoCaptureSceneMonitoringStatuses 获取提示。

值得深挖的点

  1. isCinematicVideoCaptureEnabled 的设计哲学很 Apple。一个属性开关搞定整个 session 的电影模式配置，所有输出自动适配。不需要分别配置每个 output。

  2. metadata output 的 requiredMetadataObjectTypesForCinematicVideoCapture 是硬性要求。如果 Cinematic 开启但 metadata types 不匹配，会抛异常。算法需要人脸检测等 metadata 来驱动自动对焦决策。

  3. strong vs weak focus 的选择决定了用户体验。strong 适合”我就是要跟踪这个人”的场景（如采访），weak 适合让算法智能决策的日常拍摄。在你的 app UI 中清晰区分这两种模式。

  4. 录制中同时拍照的能力容易被忽略。加一个 AVCapturePhotoOutput 到已配置为 Cinematic 的 session 中，照片自动带有 bokeh 效果，不需要额外配置。

代码片段

配置 Cinematic capture session：

// 找到支持 Cinematic 的格式
let format = device.formats.first {
    $0.isCinematicVideoCaptureSupported
}
device.activeFormat = format

// 创建 input 并开启 Cinematic
let videoInput = try AVCaptureDeviceInput(device: device)
videoInput.isCinematicVideoCaptureEnabled = true

// 添加到 session
session.addInput(videoInput)

// 配置 metadata output（Cinematic 必需）
let metadataOutput = AVCaptureMetadataOutput()
metadataOutput.metadataObjectTypes =
    device.requiredMetadataObjectTypesForCinematicVideoCapture
session.addOutput(metadataOutput)

手动对焦逻辑：

func handleTap(at point: CGPoint) {
    if let obj = findTappedMetadataObject(at: point) {
        if obj.cinematicVideoFocusMode == .weak {
            // 升级为 strong focus
            device.setCinematicVideoTrackingFocus(
                detectedObjectID: obj.objectID,
                focusMode: .strong
            )
        } else {
            // weak focus
            device.setCinematicVideoTrackingFocus(
                detectedObjectID: obj.objectID,
                focusMode: .weak
            )
        }
    } else {
        // 寻找显著对象
        device.setCinematicVideoTrackingFocus(at: point, focusMode: .weak)
    }
}

func handleLongPress(at point: CGPoint) {
    device.setCinematicVideoFixedFocus(at: point, focusMode: .strong)
}

最佳实践

  1. 开启视频稳定化。推荐 cinematicExtendedEnhanced 模式，手持拍摄的稳定性直接影响电影感体验。

  2. 必须配置 metadata output。Cinematic 算法依赖人脸检测等 metadata，不要遗漏这一步。

  3. 光线不足时给用户提示。KVO cinematicVideoCaptureSceneMonitoringStatuses，当值包含 notEnoughLight 时在 UI 中显示警告。

  4. 用 simulatedAperture 控制 bokeh 强度。值用 f-stop 表示（f 数值越小，光圈越大，bokeh 越强）。用 format 的 min/max/default 约束 slider 范围。

  5. 坐标空间转换不要搞错。metadata 的 bounds 需要用 layerRectConverted(fromMetadataOutputRect:) 转换到 preview layer 坐标空间。AVFoundation 用左上角原点，SwiftUI 的 position 用中心点。

还有什么值得关注

  • WWDC23 的 “Support Cinematic mode videos in your app” 介绍了 Cinematic Framework 的编辑/回放能力，与本次的 capture API 配套使用。
  • 空间音频（first order ambisonics）可以与 Cinematic capture 配合，提升沉浸感。
  • Cinematic Video 支持 Dual Wide 后置和 TrueDepth 前置摄像头，覆盖自拍和后拍两个场景。
Photos & Camera Audio & Video