Playing immersive media with AVKit

At a glance

Project structure

AVKitImmersivePlayback/
├── AVKitImmersivePlaybackApp.swift
├── ContentView.swift
├── VideoCard.swift
├── PlayerModel.swift
├── SceneProvider.swift
└── Video.swift

Structure observations

• The root app, not a leaf view, owns playback state and injects it through SwiftUI environment.
• Content metadata is an immutable value catalog; all mutable framework state stays in PlayerModel.

Overall architecture

flowchart LR
    App["AVKitImmersivePlaybackApp"] --> Model["PlayerModel @MainActor"]
    App --> Env["SwiftUI environment"]
    Env --> Card["VideoCard"]
    Card --> Model
    Catalog["Video.library"] --> Card
    Model --> Player["AVPlayer"]
    Model --> PVC["AVPlayerViewController"]
    PVC --> Experience["AVExperienceController"]
    Model -. delegate .-> Experience
    Scene["SceneProvider"] --> Model

Reference code

AVKitImmersivePlayback/PlayerModel.swift:33 — the façade turns one view intent into load, UI configuration, and an asynchronous experience transition.

func playVideo(_ video: Video) {
    loadVideo(video)
    configurePlaybackUI()
    Task { await presentPlayer() }
}

private func configurePlaybackUI() {
    let controller = AVPlayerViewController()
    controller.experienceController.allowedExperiences = .recommended()
    controller.experienceController.delegate = self
    controller.player = player
    playerViewController = controller
}

Interpretation

Views know only a Video and playVideo command. The model owns AVPlayer, constructs the transient system UI, supplies scene placement, and responds to experience availability/lifecycle.

Ownership and state

classDiagram
    AVKitImmersivePlaybackApp *-- PlayerModel : State owns
    PlayerModel *-- AVPlayer : owns
    PlayerModel *-- AVPlayerViewController : owns while presented
    AVPlayerViewController *-- AVExperienceController : framework owns
    PlayerModel o-- UIScene : observes
    SceneProvider o-- UIScene : publishes
    ContentView --> PlayerModel : environment reads
    VideoCard --> PlayerModel : sends intent

Ownership evidence

AVKitImmersivePlayback/AVKitImmersivePlaybackApp.swift:10 — the root retains and injects one player model for the window.

@main
struct AVKitImmersivePlaybackApp: App {
    @State private var player = PlayerModel()
    @UIApplicationDelegateAdaptor private var appDelegate: AppDelegate

    var body: some Scene {
        WindowGroup { ContentView().environment(player) }
    }
}

Class and protocol design

Access control

Reference code

AVKitImmersivePlayback/PlayerModel.swift:11 — a small internal command surface wraps private framework state.

@MainActor
@Observable
class PlayerModel {
    var scene: UIScene?
    private let player = AVPlayer()
    private var playerViewController: AVPlayerViewController?
}

Logic ownership and placement

Design patterns

Main application flow

sequenceDiagram
    actor User
    participant Card as VideoCard
    participant Model as PlayerModel
    participant Exp as ExperienceController
    User->>Card: Select video
    Card->>Model: playVideo(video)
    Model->>Model: create item metadata and player VC
    Model->>Exp: transition(to: expanded)
    Exp-->>Model: completed or reversed
    alt completed
        Model->>Model: player.play()
    end

Reference code

AVKitImmersivePlayback/PlayerModel.swift:67 — playback begins only after AVKit completes the expanded transition.

private func presentPlayer() async {
    switch await playerViewController?.experienceController.transition(to: .expanded) {
    case .completed: player.play()
    case .reversed(reason: let reason): print("Unable to start playback: \(reason).")
    default: fatalError()
    }
}

Naming conventions

• PlayerModel names observable playback state; SceneProvider names lifecycle data supply.
• Commands use user-domain verbs: playVideo, loadVideo, presentPlayer.
• Helpers use configure/create prefixes for setup and transformation.
• VideoCard and Video.library separate presentation from catalog data.

Architecture takeaways

• Own and inject one playback model at the app boundary when playback spans many views.
• Keep AVPlayerViewController transient and reset it when returning to embedded state.
• Start media only after the requested AVKit experience transition completes.
• Model scene discovery as an adapter rather than coupling SwiftUI views to UIKit lifecycle callbacks.

Source map

• Official Apple documentation