Enhance the immersion of media viewing in custom environments

Highlight

这场 Session 讲的是如何在 visionOS 的自定义环境里构建沉浸式媒体观看体验。以 Destination Video 示例项目的 Studio 环境为蓝本，覆盖了从基础搭建到高级效果的全流程。

核心内容

在 visionOS 上看视频，默认体验是一个可以拖动、缩放的窗口。窗口体验本身没问题，但 Apple Vision Pro 的沉浸能力远不止于此。问题在于：当你把视频放进一个自定义 3D 环境，视频画面飘在半空中，跟环境没有任何交互——看起来像一块悬浮的屏幕贴在一个房间里，观众感受不到”在这个空间里看电影”的氛围。

Apple 在 visionOS 2 里给出了系统级的解决方案。核心思路是把视频”停靠”到环境中的固定位置，再通过媒体反射、环境光照、空间混响和穿透色调这些手段，让视频和环境融为一体。具体来说，ImmersiveSpace 提供渐进式沉浸（用户通过 Digital Crown 从无沉浸调到全沉浸），AVPlayerViewController 在全屏模式下自动参与系统停靠行为。今年新增的 Docking Region 组件让你可以自定义停靠位置，把视频精确放到环境中你设计好的位置上。加上 Virtual Environment Probe 提供环境光照、Reverb 组件提供空间混响、Brightness 和 Tint 让穿透画面匹配环境色调，整套体验从”窗口贴在房间里”变成了”在影院里看巨幕”。

详细内容

基础架构：ImmersiveSpace + AVPlayerViewController

媒体观看体验的地基是 ImmersiveSpace 场景类型配合 AVPlayerViewController（02:07）。ImmersiveSpace 支持渐进式沉浸，用户通过 Digital Crown 控制沉浸程度。AVPlayerViewController 支持 HLS 流媒体，提供与系统 TV、Music 应用一致的播放控制。当 AVPlayerViewController 进入全屏模式时，系统会自动执行”停靠”——把视频画面放到一个固定位置（03:26）。

自定义停靠位置：Docking Region

默认情况下，系统决定视频停靠在哪里。今年你可以通过 Reality Composer Pro 里的 Docking Region Component 自定义这个位置（03:37）。操作步骤：在 Reality Composer Pro 的插入菜单中选择 Environment > Video Dock 预设，展开 Video Dock 实体找到 Player 实体，在 Inspector 中调整 Docking Region Component 的 width 属性。width 定义了 2.4:1 宽高比下的最大播放尺寸，超出尺寸的视频会自动缩放（06:01）。调整完宽高后，需要通过修改 Player 实体的 position transform 把画面抬高——就像影院里屏幕略高于地面一样（06:30）。

需要注意 ImmersiveSpace 的坐标原点：原点在空间首次打开时位于观众脚下附近。所有实体的位置都相对于这个原点（05:36）。Destination Video 的 Studio 环境把 Docking Region 放在观众正前方，与周围建筑对称，确保视线无遮挡（07:01）。

媒体反射：Specular 和 Diffuse

视频画面可以在环境表面产生反射，增强真实感。Reality Composer Pro 的 ShaderGraph 提供两种反射节点（08:22）：

Reflection Specular：直接反射视频内容，适用于光滑表面（金属、镜面、水面）。设置方式：场景中有 Docking Region 的实体 + 表面材质连接 Reflection_Specular 节点，RealityKit 自动根据 Docking Region 位置和地面纹理坐标计算反射（08:55）。
Reflection Diffuse：柔和衰减的反射，适用于粗糙表面（木地板、混凝土）。Studio 环境使用了 Diffuse 反射，因为柔和衰减更匹配地板材质。需要注意：如果移动了 Docking Region、地面实体或使用自定义 mesh，需要重新计算 Reflection_Diffuse 的纹理坐标并导入 Reality Composer Pro（09:25）。

Virtual Environment Probe、Brightness & Tint、Reverb

Virtual Environment Probe 描述环境中的颜色变化和光照强度，系统据此自动为 PBR 材质着色，近似模拟光线在物体间的弹射（10:30）。如果你的环境支持明暗两种变体（如 Studio 的 Dark 和 Light），可以配置两个预生成的 Environment Resource 和一个 blend factor，应用代码驱动两者间的过渡，系统驱动沉浸混合。过渡时间建议短一些——系统环境的明暗过渡是 1.5 秒（11:13）。

Brightness & Tint 让穿透画面中观众手部的光照匹配自定义环境的色调，就像影院灯光变暗后手部的视觉感受（11:44）。对应代码属性是 immersiveContentBrightness 和 surroundingsEffect。

Reverb 组件 是今年新增的，在 Reality Composer Pro 的 Inspector 中通过 Add Component 添加（13:21）。预设包括 Medium Room (Treated)、Outdoor、Very Large Room 等。Studio 使用 Very Large Room 预设。即使你的环境没有自定义音频，也建议选择一个 Reverb 预设，这样系统可以用来空间化 UI 按钮等系统音效（13:46）。

Immersive Environment Picker

通过 .immersiveEnvironmentPicker 修饰符，你的自定义环境可以出现在与系统环境同一个选择列表中（14:45）：

WindowGroup {
    ContentView()
        .immersiveEnvironmentPicker {
            ForEach(viewModel.environmentItems) { item in
                Button(item.title, image: item.thumbnail) {
                    Task {
                        await openImmersiveSpace(id: item.id)
                    }
                }
            }
        }
}

关键点：

.immersiveEnvironmentPicker 修饰符挂在 ContentView() 上，定义该视图内视频播放器的环境选择列表
ForEach 遍历环境数据，每个条目需要提供 title 和 thumbnail 图像
Button 的 action 中通过 openImmersiveSpace(id:) 打开对应的沉浸空间
用户在系统环境列表中就能看到你的自定义环境，选择后视频自动停靠到该环境的 Docking Region

SharePlay 环境同步

SharePlay 现在可以同步环境状态，多个参与者可以共享同一种沉浸体验（15:35）：

import AVKit
import GroupActivities

for await session in MyActivity.sessions() {
    // join the session, activate the activity, etc.

    playerViewController
        .player?
        .playbackCoordinator
        .coordinateWithSession(session)

    playerViewController
        .groupExperienceCoordinator
        .coordinateWithSession(session)
}