Creating a multiview video playback experience in visionOS

At a glance

Project structure

MultiviewVideoPlayback/
├── MultiviewVideoPlaybackApp.swift
├── Models/
│   ├── MultiviewStateModel.swift
│   ├── VideoModel.swift
│   └── Video.swift
├── Views/
│   ├── ContentView.swift
│   ├── VideoHomeView.swift
│   ├── MultiviewVideoSelectionView.swift
│   └── ItemVideoPlayer.swift
└── Helpers/
    ├── SceneDelegate.swift
    └── AVMultiviewManager+Extension.swift

Structure observations

• Models own transition/playback state; views send selection intents and render observed values.
• Helpers bridge SwiftUI content and scene lifecycle into UIKit/AVKit APIs.

Overall architecture

flowchart LR
    App["SwiftUI App"] --> View["ContentView / selection views"]
    View --> State["MultiviewStateModel @MainActor"]
    State --> VideoModels["VideoModel per video"]
    VideoModels --> PVC["AVPlayerViewController"]
    PVC --> Experience["AVExperienceController"]
    State -. delegate .-> Experience
    State --> Group["withTransitionGroup"]
    Scene["CustomSceneDelegate"] --> State
    Select["AVMultiviewManager content selection"] --> View

Reference code

MultiviewVideoPlayback/Models/MultiviewStateModel.swift:47 — a selection intent becomes an experience transition owned by the state model.

func videoSelected(videoModel: VideoModel, inMultiview: Bool) async {
    if inMultiview {
        await AVExperienceController.withTransitionGroup { group in
            group.addTransition {
                await videoModel.viewController.experienceController.transition(
                    to: videoModel.isAddedToMultiview ? .embedded : .multiview)
            }
        }
    } else {
        // Transition the selected item to its expanded experience.
    }
}

Interpretation

MultiviewStateModel is both application state authority and AVExperienceController delegate. Each VideoModel owns the player/controller pair for one immutable Video; views do not manipulate controllers directly.

Ownership and state

classDiagram
    ContentView *-- MultiviewStateModel : State owns
    MultiviewStateModel *-- VideoModel : array owns
    VideoModel *-- AVPlayer : private owns
    VideoModel *-- AVPlayerViewController : owns
    AVPlayerViewController *-- AVExperienceController : framework owns
    MultiviewStateModel o-- UIScene : observes reference
    CustomSceneDelegate o-- UIScene : observes lifecycle

Ownership evidence

MultiviewVideoPlayback/Models/VideoModel.swift:10 — one model creates and retains all playback objects for one video.

@Observable @MainActor
class VideoModel {
    let video: Video
    private let player: AVPlayer
    let viewController: AVPlayerViewController
    var isAddedToMultiview = false

    init(video: Video) {
        let playerController = AVPlayerViewController()
        self.video = video
        self.viewController = playerController
        self.player = AVPlayer(playerItem: video.playerItem)
        self.viewController.player = player
    }
}

Class and protocol design

Access control

Reference code

MultiviewVideoPlayback/Models/Video.swift:34 — metadata construction is confined to the model file.

extension AVMetadataItem {
    fileprivate static func metadataItem(
        key identifier: AVMetadataIdentifier,
        value: Any
    ) -> AVMetadataItem {
        // Build and copy a mutable metadata item.
    }
}

Logic ownership and placement

Design patterns

Main application flow

sequenceDiagram
    actor User
    participant View as Selection view
    participant State as State model
    participant Exp as Experience controller
    User->>View: Add/remove video
    View->>State: videoSelected(item, inMultiview)
    State->>Exp: grouped transition
    Exp-->>State: transition context delegate callback
    State->>State: update isAddedToMultiview/embeddedVideo
    State-->>View: observable state rerenders

Reference code

MultiviewVideoPlayback/Views/MultiviewVideoSelectionView.swift:24 — the view forwards a typed intent and awaits the model.

ForEach(multiviewStateModel.videoModels, id: \.video) { videoModel in
    Button {
        Task {
            await multiviewStateModel.videoSelected(
                videoModel: videoModel,
                inMultiview: fromMultiviewContentSelection)
        }
    } label: { VideoItemSelectionView(videoModel: videoModel, inMultiviewContentSelection: fromMultiviewContentSelection) }
}

Naming conventions

• StateModel names the shared reducer; VideoModel names per-item playback state; Video is immutable content.
• Experience methods use event/action language: videoSelected, prepareForTransition, didChangeTransitionContext.
• Boolean names communicate membership/capability: isAddedToMultiview, supportsEmbeddedPlaybackExperience.
• Helper extension filename names the extended framework type.

Architecture takeaways

• Keep controller/player lifetime in per-item models and aggregate transition truth in one state model.
• Treat AVExperienceController delegate callbacks as the authoritative transition result, not the button tap.
• Use transition groups when several experience changes must be coordinated.
• Isolate SwiftUI/UIKit seams in representables and hosting-controller helpers.

Source map

• Official Apple documentation