了解如何在 visionos app 中播放沉浸视频。我们将介绍各种沉浸感十足的渲染模式、查看支持这些模式的框架，并讲解如何在你的 app 中渲染沉浸视频。为了充分利用好本次视频，我们建议你先观看 wwdc25 讲座“探索 visionos 的视频体验”。

视频封面
视频地址

此文章由AI生成，可能存在错误，如有问题，请联系djs66256@163.com

支持 visionOS App 播放沉浸视频

随着 visionOS 的不断发展，开发者现在可以利用多种框架在应用中实现沉浸式视频播放体验。本文将详细介绍如何在 visionOS 26 中通过 Quick Look、AVKit 和 RealityKit 支持沉浸式视频播放，并探讨相关技术实现和最佳实践。

介绍

在 visionOS 26 中，Apple 引入了多种新的沉浸式媒体配置文件，包括 Apple Projected Media Profile (APMP) 和 Apple 沉浸视频。这些新特性为开发者提供了丰富的工具集，以创建引人入胜的沉浸式视频体验。Quick Look、AVKit 和 RealityKit 是三个主要框架，它们各自适用于不同的场景需求：从快速预览到完全自定义的沉浸式播放。

接下来的内容将分为几个部分：首先回顾支持的视频配置文件，然后逐步讲解如何使用 Quick Look 和 AVKit 实现沉浸式视频播放，最后深入探讨如何通过 RealityKit 创建高度定制化的沉浸体验。

visionOS 26 中支持的视频配置文件

visionOS 26 支持多种视频配置文件，涵盖了从传统的 2D 和 3D 视频到更具沉浸感的 Apple Projected Media Profile（包括 180°、360° 和宽视场视频）以及 Apple 沉浸视频。不同类型的视频配置文件各有特点，例如 APMP 提供了广泛的沉浸视角选择，而 Apple 沉浸视频则专注于极致的沉浸体验。

为了充分利用这些视频配置文件，开发者需要根据应用的需求选择合适的框架。Quick Look 适合快速呈现媒体内容；AVKit 提供了一致且增强的播放控制功能；而 RealityKit 则专为需要高度定制化体验的应用设计，例如游戏环境中的视频播放。

Quick Look 中的沉浸视频播放

Quick Look 在 visionOS 26 中得到了显著增强，能够支持空间照片和视频的展示。QLPreviewController API 可用于在一个应用程序窗口或模态展示风格中预览媒体，同时支持 Apple 沉浸视频和 APMP 配置文件。

对于已经实现了 Quick Look API 的应用，所有新支持的沉浸式媒体配置文件将自动生效。开发者可以通过 WWDC 相关视频进一步了解如何实现 QLPreviewController 和 PreviewApplication API，从而提升应用的沉浸式媒体支持能力。

使用 AVKit 进行沉浸视频播放

AVKit 在 visionOS 26 中新增了对沉浸式视频播放的支持，通过 AVExperienceController API 可以实现向新沉浸体验的过渡。开发者可以选择使用 Expanded 或 Immersive 体验模式来满足不同需求。

自动过渡与手动控制

在 Expanded 模式下，AutomaticTransitionToImmersive 属性允许开发者控制是否自动切换到沉浸体验。以下代码展示了如何禁用自动过渡并手动管理沉浸体验：

import AVKit

let controller = AVPlayerViewController()

let experienceController = controller.experienceController
experienceController.allowedExperiences = .recommended(including: [.expanded, .immersive])

experienceController.configuration.expanded.automaticTransitionToImmersive = .none

await experienceController.transition(to: .expanded)

手动转换到沉浸模式

要显式地转换到沉浸模式，开发者可以使用 configuration.placement API 来指定沉浸式视频播放的位置。以下代码演示了如何通过指定目标窗口场景完成这一操作：

import AVKit

let controller = AVPlayerViewController()

let experienceController = controller.experienceController
experienceController.allowedExperiences = .recommended(including: [.immersive])

let myScene = getMyPreferredWindowUIScene()
experienceController.configuration.placement = .over(scene: myScene)

await experienceController.transition(to: .immersive)

此外，AVExperienceController 的委托协议提供了灵活的状态管理方法，例如 didChangeAvailableExperiences 和 prepareForTransitionUsing，使开发者能够精确控制沉浸式体验的过渡过程。

舒适缓解检测

沉浸式视频可能会因显著的摄像机运动导致观众不适。为解决这一问题，visionOS 26 在 Quick Look 和 AVKit 中引入了舒适缓解检测功能，能够自动检测高运动并降低沉浸水平。用户还可以通过设置应用调整相关选项，确保播放行为符合个人偏好。

RealityKit 中的自定义播放

对于需要更高定制化程度的应用，RealityKit 提供了强大的工具集来渲染和管理沉浸式视频播放。其核心组件 VideoPlayerComponent 能够根据当前 AVPlayer 的内容动态生成网格和材质，从而简化开发流程。

渐进沉浸模式

在 RealityKit 中，渐进沉浸模式是一种全新的 API，允许用户通过数码表冠调整沉浸级别，从而在享受视频的同时保持与周围环境的联系。以下代码展示了如何在门户模式下渲染 180° 视频：

import AVFoundation
import RealityKit
import SwiftUI

struct PortalVideoView: View {
    var body: some View {
        RealityView { content in
            guard let url = URL(string: "https://cdn.example.com/My180.m3u8") else { return }
            let player = AVPlayer(playerItem: AVPlayerItem(url: url))
            let videoEntity = Entity()
            var videoPlayerComponent = VideoPlayerComponent(avPlayer: player)
            videoPlayerComponent.desiredImmersiveViewingMode = .portal
            videoEntity.components.set(videoPlayerComponent)
            videoEntity.scale *= 0.4
            content.add(videoEntity)
        }
    }
}

如果希望切换到渐进沉浸模式，只需将 desiredImmersiveViewingMode 设置为 .progressive，并在 SwiftUI 场景中使用 ImmersiveSpace 包装视图：

import AVFoundation
import RealityKit
import SwiftUI

@main
struct ImmersiveVideoApp: App {
    var body: some Scene {
        ImmersiveSpace {
            ProgressiveVideoView()
        }
        .immersionStyle(selection: .constant(.progressive(0.1...1, initialAmount: 1.0)), in: .progressive)    
    }
}

空间视频渲染

RealityKit 还支持空间视频的原生播放，并提供完全空间样式的渲染选项。通过设置 desiredSpatialVideoMode 属性，开发者可以灵活选择渲染方式。例如，以下代码展示了如何在门户模式下渲染空间视频：

import AVFoundation
import RealityKit
import SwiftUI

struct PortalSpatialVideoView: View {
    var body: some View {
        RealityView { content in
            let url = Bundle.main.url(forResource: "MySpatialVideo", withExtension: "mov")!
            let player = AVPlayer(url: url)
            let videoEntity = Entity()
            var videoPlayerComponent = VideoPlayerComponent(avPlayer: player)
            videoPlayerComponent.desiredViewingMode = .stereo
            videoPlayerComponent.desiredSpatialVideoMode = .spatial
            videoPlayerComponent.desiredImmersiveViewingMode = .portal
            videoEntity.components.set(videoPlayerComponent)
            videoEntity.scale *= 0.4
            content.add(videoEntity)
        }
    }
}

若需进一步扩展视频至全沉浸模式，可将 desiredImmersiveViewingMode 设置为 .full 并移除缩放操作：

import AVFoundation
import RealityKit
import SwiftUI

struct PortalSpatialVideoView: View {
    var body: some View {
        RealityView { content in
            let url = Bundle.main.url(forResource: "MySpatialVideo", withExtension: "mov")!
            let player = AVPlayer(url: url)
            let videoEntity = Entity()
            var videoPlayerComponent = VideoPlayerComponent(avPlayer: player)
            videoPlayerComponent.desiredViewingMode = .stereo
            videoPlayerComponent.desiredSpatialVideoMode = .spatial
            videoPlayerComponent.desiredImmersiveViewingMode = .full
            videoEntity.position = [0, 1.5, -1]
            videoEntity.components.set(videoPlayerComponent)
            content.add(videoEntity)
        }
    }
}

结论

通过 Quick Look、AVKit 和 RealityKit，开发者可以在 visionOS 应用中实现丰富多样的沉浸式视频播放体验。无论是快速预览还是深度定制，Apple 提供的工具集都为开发者创造了无限可能。建议开发者进一步探索相关文档和示例代码，以充分发挥这些框架的潜力。

相关视频

了解 Apple 沉浸视频技术
了解 Apple Projected Media Profile
探索 visionOS 的视频体验
空间网页的新功能
深入探究空间容器和沉浸式空间
使用 RealityKit 增强你的空间计算 App

文档

AVFoundation
AVKit
HTTP Live Streaming Examples
RealityKit