Reading multiview 3D video files

At a glance

Project structure

StereoViewer/
├── StereoViewerApp.swift          # Composition root
├── LaunchView.swift               # File selection and first navigation state
├── MediaDetailView.swift          # Asset-validation screen
├── MediaDetailViewModel.swift     # Async metadata loading
├── StereoView.swift               # Frame controls and image presentation
└── StereoViewModel.swift          # Track inspection and frame decoding

Structure observations

• Each Swift file contains one primary type; view and view-model pairs share the same feature prefix.
• The project has no separate service, domain, or persistence layer. AVFoundation work lives directly in the two view models.
• Configuration/ and the Xcode project hold build configuration; they do not introduce runtime architecture.

Overall architecture

flowchart LR
    App["StereoViewerApp"] --> Launch["LaunchView"]
    Launch --> Detail["MediaDetailView"]
    Detail --> Metadata["MediaDetailViewModel"]
    Detail --> Stereo["StereoView"]
    Stereo --> Decoder["StereoViewModel"]
    Metadata --> Asset["AVURLAsset"]
    Decoder --> Reader["AVAssetReader + track output"]

Reference code

StereoViewer/MediaDetailView.swift:18 — transition from validation to decoding

init(filename: URL) {
    mediaDetailViewModel = MediaDetailViewModel(filename: filename)
    self.filename = filename
}

// In body, after the user continues:
StereoView(asset: mediaDetailViewModel.asset)

Interpretation

The SwiftUI views form the navigation and composition layer. MediaDetailViewModel first validates and describes the selected asset; StereoViewModel then owns the lower-level AVFoundation read pipeline. This is a source-explicit MVVM organization, although the view models also act as framework services because the sample is intentionally small.

Ownership and state

classDiagram
    MediaDetailView *-- MediaDetailViewModel : creates and retains
    MediaDetailViewModel *-- AVURLAsset : creates and retains
    StereoView *-- StereoViewModel : creates and retains
    StereoViewModel o-- AVURLAsset : receives and retains
    StereoViewModel *-- AVAssetReader : creates per seek
    StereoView --> StereoViewModel : observes state and images

Ownership evidence

StereoViewer/StereoView.swift:19 and StereoViewer/StereoViewModel.swift:26 — injected asset and owned decoder

init(asset: AVURLAsset) {
    self.asset = asset
    self.stereoViewModel = StereoViewModel(asset: asset)
}

private let asset: AVURLAsset
private var assetReader: AVAssetReader?

The same AVURLAsset reference passes from the metadata phase into the decoding phase. The diagram uses aggregation for that injected reference and composition for objects each owner creates itself.

Class and protocol design

There are no application-defined protocols or interchangeable implementations. The design favors two concrete observable reference types because each coordinates mutable asynchronous framework state.

The ViewModel suffix, @Observable, and the direction of calls from views to model objects are direct evidence for MVVM. Calling the design protocol-oriented would not be supported by this source.

Access control

Reference code

StereoViewer/StereoViewModel.swift:22 — narrow public surface and private pipeline state

@MainActor var state: StereoViewModelState = .loading
@MainActor var leftEye = NSImage(...)
@MainActor var rightEye = NSImage(...)

private let asset: AVURLAsset
private var assetReader: AVAssetReader?
private var trackOutput: AVAssetReaderTrackOutput?

The three observable outputs remain module-visible so StereoView can read them, while the framework machinery is private. @MainActor controls concurrency isolation, not visibility. @unchecked Sendable is also a concurrency assertion, not an access level; the code manually routes published UI mutations to the main actor.

Logic ownership and placement

Design patterns

Main application flow

sequenceDiagram
    actor User
    participant View as SwiftUI views
    participant Metadata as MediaDetailViewModel
    participant Decoder as StereoViewModel
    participant AVF as AVFoundation
    User->>View: Select MV-HEVC file
    View->>Metadata: Create with URL
    Metadata->>AVF: Load metadata
    User->>View: Continue / choose frame
    View->>Decoder: Create or readBuffer(at:)
    Decoder->>AVF: Discover track and read tagged buffers
    AVF-->>Decoder: Left/right pixel buffers
    Decoder-->>View: Ready state and eye images

Reference code

StereoViewer/StereoViewModel.swift:39 and StereoViewer/StereoViewModel.swift:139 — track discovery to image publication

if let track = try await asset.loadTracks(
    withMediaCharacteristic: .containsStereoMultiviewVideo
).first {
    self.track = track
    self.framePresentationTimes = try presentationTimesFor(track: track, asset: asset)
    // ... configure and read the first frame
}

// For each tagged pixel buffer:
if tags.contains(.stereoView(.leftEye)) { leftEye = nsImage }
else if tags.contains(.stereoView(.rightEye)) { rightEye = nsImage }

Naming conventions

• Types use feature-and-role names: MediaDetailView, MediaDetailViewModel, StereoView, and StereoViewModel.
• State names describe lifecycle cases (loading, ready, error) and attach only the data relevant to a case.
• Commands use verbs and reveal intent: readBufferFromAsset(at:), readNextBufferFromAsset(), and publishState(_:).
• Loader/helper names describe returned data: presentationTimesFor(track:asset:) and loadVideoLayerIdsForTrack(_:).
• Files match their primary type. The two file-private free functions stay beside the only consumer instead of creating a generic utility layer.

Architecture takeaways

• Use a small composition chain when a sample has a linear workflow; separate metadata validation from expensive decoding state.
• Give one object ownership of the mutable AVAssetReader pipeline so views issue intent rather than coordinate framework pieces.
• Publish UI-consumed values on the main actor while keeping decode internals hidden.
• An enum state makes asynchronous loading and failure paths explicit without several competing Boolean flags.
• Protocol abstraction is unnecessary here because the app has one concrete decoding implementation and no test seam demonstrated in the source.

Source map

• Official Apple documentation