Processing spatial video with a custom video compositor

At a glance

Project structure

AVFSpatialCustomVideoCompositorSample/
├── AVFSpatialCustomVideoCompositorSample.swift # App root
├── ContentView.swift                           # Feature UI and file flow
├── SampleModel.swift                           # Playback/export owner
├── Model/UserSettings.swift                    # UserDefaults-backed selection
├── Compositing/
│   ├── VideoCompositionBuilder.swift
│   ├── MonoOutputCompositor.swift
│   ├── StereoOutputCompositor.swift
│   └── PixelBufferHelper.swift
├── Export/
│   ├── Exporter.swift                          # Protocol, factory enum, status/errors
│   ├── ExportSessionExporter.swift
│   ├── ReaderWriterExporter.swift
│   └── FileManagerExtensions.swift
└── Views/PlayerView.swift / SettingsView.swift

Structure observations

• Folder boundaries follow capabilities rather than UI screens.
• SampleModel is the feature facade and only long-lived owner of playback/export state.
• Export has an app-defined protocol; compositing implements Apple’s protocol and uses an enum to choose concrete classes.

Overall architecture

flowchart LR
    App["App"] --> View["ContentView"]
    View --> Model["SampleModel"]
    Model --> Player["AVPlayer"]
    Model --> Builder["VideoCompositionBuilder"]
    Builder --> Mono["MonoOutputCompositor"]
    Builder --> Stereo["StereoOutputCompositor"]
    Model --> Factory["ExporterType factory"]
    Factory --> Session["ExportSessionExporter"]
    Factory --> RW["ReaderWriterExporter"]
    Settings["UserSettings.shared"] --> Model

Reference code

AVFSpatialCustomVideoCompositorSample/SampleModel.swift:80 — model selects export and composition collaborators

func export(using exporterType: ExporterType) async throws {
    exporter = exporterType.createExporter()
    isExportInProgress = true
    let asset = AVURLAsset(url: movieFile)
    let videoComposition = try await makeVideoComposition(for: asset)
    try await exporter?.export(asset: asset, videoComposition: videoComposition)
    // publish output, then release exporter
}

Interpretation

ContentView owns presentation state and sends intents to SampleModel. The model is a concrete observable facade: it owns the player, turns settings into a video composition, and retains the chosen exporter only for the active operation.

Ownership and state

classDiagram
    ContentView *-- SampleModel : creates as State
    SampleModel *-- AVPlayer : creates and replaces
    SampleModel *-- Exporter : retains during export
    SampleModel ..> VideoCompositionBuilder : creates per operation
    UserSettings o-- UserDefaults : shared storage
    AVVideoComposition ..> AVVideoCompositing : framework creates selected class

Ownership evidence

AVFSpatialCustomVideoCompositorSample/ContentView.swift:14 and AVFSpatialCustomVideoCompositorSample/SampleModel.swift:14 — view/model ownership

@State private var sampleModel = SampleModel()

private(set) var player = AVPlayer()
private var movieFile: URL? = nil
private var exporter: Exporter?
private(set) var isExportInProgress = false
private(set) var exportTempURL: URL? = nil

Class and protocol design

classDiagram
    class Exporter {
        <<protocol>>
        status
        export
    }
    ExportSessionExporter ..|> Exporter
    ReaderWriterExporter ..|> Exporter
    ExporterType ..> Exporter : factory
    MonoOutputCompositor ..|> AVVideoCompositing
    StereoOutputCompositor ..|> AVVideoCompositing
    SpatialVideoCompositionInstruction ..|> AVVideoCompositionInstructionProtocol

Reference code

AVFSpatialCustomVideoCompositorSample/Export/Exporter.swift:27 — protocol factory

func createExporter() -> Exporter {
    switch self {
    case .exportSession: return ExportSessionExporter()
    case .readerWriter:  return ReaderWriterExporter()
    }
}

protocol Exporter {
    var status: ExporterStatus { get }
    func export(asset: AVAsset, videoComposition: AVVideoComposition?) async throws
}

Access control

Reference code

AVFSpatialCustomVideoCompositorSample/SampleModel.swift:14 and AVFSpatialCustomVideoCompositorSample/Model/UserSettings.swift:10 — enforced mutation and singleton boundary

private(set) var player = AVPlayer()
private(set) var isMovieFileLoaded = false
private var exporter: Exporter?

struct UserSettings {
    static let shared = UserSettings()
    private let userDefaults = UserDefaults.standard
    private init() {}
}

Logic ownership and placement

Design patterns

Naming conventions

• Capability roles use precise suffixes: Builder, Exporter, Compositor, Instruction, and Helper.
• Concrete strategies state mechanism/output: ExportSessionExporter, ReaderWriterExporter, MonoOutputCompositor, StereoOutputCompositor.
• Boolean names state conditions: isMovieFileLoaded, isExportInProgress, previewRequiresStereo, outputsStereo.
• Commands use clear verbs: loadMovieFile, applyUserSettings, createExporter, build, and export.
• Files mirror primary types and capability folders.

Architecture takeaways

• Use private(set) when views need observation but one model must retain mutation authority.
• A small protocol plus enum factory cleanly supports materially different export mechanisms.
• Wrap framework instructions when custom compositors need metadata beyond the base protocol.
• Keep video-composition construction separate from both UI and frame processing.
• This sample demonstrates meaningful protocol-oriented design at both app (Exporter) and framework (AVVideoCompositing) boundaries.

Source map

• Official Apple documentation