Support Cinematic mode videos in your app
Media & Web 进阶 20m

在应用中支持电影效果模式视频

Support Cinematic mode videos in your app

2023年6月5日

在 Apple 官方观看视频

一句话判断

Cinematic API 让你在自己的 App 中实现和 Photos、Final Cut Pro 一样的电影效果模式编辑能力——改焦点、调光圈、重新编排叙事，全部无损可逆。

这场 Session 讲了什么

这场 Session 详细介绍了全新的 Cinematic API，用于在第三方 App 中播放和编辑 iPhone 13/14 拍摄的电影效果模式视频。

电影效果模式的数据结构包含三个轨道：

  • 视频轨道：原始视频（最高 4K@30fps，iPhone 14 支持 4K@24/25/30fps）。
  • 视差轨道（Disparity）：双摄像头视角差的数据，用于计算景深和焦点渲染。注意这是相对视差而非绝对深度。
  • 元数据轨道：包含渲染属性（焦点视差、光圈 f 值）和电影脚本（场景检测结果——人脸、头部、躯干，以及焦点决策记录）。

数据流：电影效果资产 -> 可选编辑（无损修改焦点和光圈）-> Cinematic Engine（根据焦点和视差渲染景深）-> 渲染后的资产（普通 QuickTime 电影）。

API 能力：

  • 播放时实时调整光圈（改变景深/散景程度）。
  • 无损修改焦点决策——可以切换到场景中的其他检测对象，改变叙事焦点。
  • 保存和加载编辑状态，所有修改都可回退到原始状态。
  • 支持在 macOS Sonoma、iOS 17、iPadOS 17、tvOS 17 上使用。

Session 用一个手球比赛的示例展示了焦点变更如何改变叙事——原版焦点在主角和队友之间切换制造紧张感，修改后全程聚焦队友，变成了完全不同的情绪表达。

值得深挖的点

**“电影脚本”（Cinematic Script）**是整个系统最精妙的设计。它不是简单的焦点追踪，而是一个包含场景检测和焦点决策的完整数据结构。每个检测对象（人脸、头部、躯干）都有唯一 ID，在时间轴上持续关联。焦点决策记录了”在某一帧选择聚焦哪个对象”的信息。你可以修改这些决策而不影响原始数据——这不是覆盖，是无损叠加。

相对视差而非绝对深度这个设计选择有深意。它意味着视差数据只能在同一帧内做相对比较（比如判断两个物体谁更近），不能直接得出”物体距离镜头 2 米”这种绝对距离。这个限制使得视差数据更适合渲染用途，不适合做精确的深度测量。

无损编辑的架构类似非破坏性图片编辑——编辑指令和原始数据分离存储。你可以反复修改焦点和光圈，随时回退到拍摄时的原始状态。这对专业视频编辑来说至关重要。

代码片段

从相册选取电影效果模式视频：

import PhotosUI
import AVFoundation

// 使用 Photos picker 过滤电影效果模式视频
var config = PHPickerConfiguration()
config.filter = .cinematicVideos  // 只显示电影效果模式视频
let picker = PHPickerViewController(configuration: config)

// 获取电影效果模式的 AVAsset
let asset = PHAsset.fetchAssets(
    withLocalIdentifiers: [selectedAssetID], options: nil
).firstObject!

let options = PHVideoRequestOptions()
options.version = .original  // 必须请求原始版本
options.isNetworkAccessAllowed = true  // 允许从 iCloud 下载

PHImageManager.default().requestAVAsset(
    forVideo: asset, options: options
) { avAsset, _, _ in
    // avAsset 就是包含完整电影效果数据的资产
    // 包含视频轨道、视差轨道和元数据轨道
}

播放电影效果模式视频并调整光圈：

// 创建电影效果模式的播放器
// 通过 API 访问 Cinematic Engine 进行实时渲染
// 可以动态修改光圈值改变散景强度

// 加载电影效果资产后：
// 1. 读取元数据轨道中的焦点决策和场景检测
// 2. 播放时通过 Cinematic Engine 实时渲染景深效果
// 3. 修改光圈 f 值 → 改变景深范围（f/1.4 散景最强，f/16 几乎无散景）
// 4. 修改焦点决策 → 改变聚焦对象 → 改变叙事焦点

修改焦点决策（重新对焦）：

// 电影脚本中的焦点决策可以被修改
// 场景检测结果提供可选的聚焦目标（人脸、头部、躯干）
// 每个检测目标有唯一 ID，在时间轴上持续关联

// 修改流程：
// 1. 获取指定时间范围的场景检测列表
// 2. 选择一个检测目标作为新焦点
// 3. 创建焦点决策覆盖（不会修改原始数据）
// 4. Cinematic Engine 根据新的焦点决策重新渲染
// 5. 所有修改可以保存，也可以随时回退到原始状态

最佳实践

  • 请求电影效果资产时必须指定 .original 版本，否则只能拿到渲染后的普通视频。
  • 如果资产存储在 iCloud，设置 isNetworkAccessAllowed = true，否则无法获取完整数据。
  • AirDrop 传输电影效果视频时选择”All Photos Data”选项，确保包含完整的电影效果数据。
  • 视差轨道的分辨率低于视频轨道，渲染时由系统自动上采样，不需要手动处理。
  • 编辑状态建议单独存储，不要修改原始资产文件。
  • 播放时的光圈调整是实时的，不需要重新渲染——Cinematic Engine 在播放过程中动态计算景深。

还有什么值得关注

  • Cinematic API 的可用范围包括 macOS Sonoma，意味着 Mac 上的视频编辑 App 也能接入。
  • iPhone 14 支持的电影效果模式分辨率提升到了 4K，API 对此透明处理。
  • 电影效果模式的焦点决策算法由 Cinematic Engine 自动生成，API 允许你在此基础上修改而非从零开始。
  • 搭配 AVFoundation 的编辑 API，可以在同一个编辑流程中同时处理普通视频轨和电影效果模式视频。
  • 如果你的 App 已经支持视频播放，接入 Cinematic API 的播放能力改动量不大，编辑能力需要更多工作。
WWDC 2023