Editing and playing HDR video

At a glance

Project structure

├── CommonSource/
│   ├── Composition.swift             # AssetLoader, AssetExporter, HDR filter
│   └── HDRIndicator.ci.metal
├── CommonUI-macOS/                   # SwiftUI + AVPlayerView bridge
├── CIFilter-iOS/                     # iOS SwiftUI + AVPlayerViewController bridge
├── BuiltInCompositor/
│   └── AVVideoCompositionBuilder.swift
├── CIFilter/
│   └── AVVideoCompositionBuilder.swift
└── CustomCompositor/
    └── AVVideoCompositionBuilder.swift # Builder + AVVideoCompositing type

Structure observations

• Every scheme compiles one same-named AVVideoCompositionBuilder; AssetLoader calls a stable static method without runtime dependency injection.
• Shared files hold asset assembly, export, and the Core Image filter; technique-specific code stays in target folders.
• UI differs by platform, while the composition call chain remains shared.

Overall architecture

flowchart LR
    UI["Platform UI"] --> Loader["AssetLoader"]
    Loader --> Builder["Target-specific AVVideoCompositionBuilder"]
    Builder --> BuiltIn["Built-in instructions"]
    Builder --> CIFilter["Core Image handler"]
    Builder --> Custom["SampleCustomCompositor"]
    Custom --> Filter["HDRIndicatorFilter"]
    Loader --> Player["AVPlayerItem"]
    UI --> Exporter["AssetExporter"]
    Exporter --> Builder

Reference code

CommonSource/Composition.swift:13 — shared call into the target-selected builder

class AssetLoader {
    static func loadAsCompositions() -> (AVComposition, AVVideoComposition) {
        // ... create AVMutableComposition ...
        let videoComposition = AVVideoCompositionBuilder
            .buildVideoComposition(asset: asset, avComposition: avComposition)
        return (avComposition, videoComposition)
    }
}

Interpretation

This is a compile-time variation point: schemes select which builder file belongs to the target. It resembles Strategy, but there is no runtime strategy protocol or injected instance. Playback and export therefore share one composition-building API in every variant.

Ownership and state

classDiagram
    PlatformUI ..> AssetLoader : calls
    AssetLoader ..> AVMutableComposition : creates and returns
    AssetExporter *-- ProgressChecker : returns handle
    ProgressChecker o-- AVAssetExportSession : privately retains
    SampleCustomCompositor *-- HDRIndicatorFilter : creates
    SampleCustomCompositor *-- CIContext : creates
    PlayerView *-- AVPlayer : creates

Ownership evidence

CommonSource/Composition.swift:35 and CustomCompositor/AVVideoCompositionBuilder.swift:29 — operation handle and custom compositor resources

struct ProgressChecker {
    private var exportSession: AVAssetExportSession? = nil
    var progress: Float { exportSession?.progress ?? 0 }
}

class SampleCustomCompositor: NSObject, AVVideoCompositing {
    private let filter = HDRIndicatorFilter()
    private let coreImageContext = CIContext(/* ... */)
}

Class and protocol design

CustomCompositor/AVVideoCompositionBuilder.swift:29 — framework-defined compositor capability

class SampleCustomCompositor: NSObject, AVVideoCompositing {
    var supportsWideColorSourceFrames = true
    var supportsHDRSourceFrames = true
    func startRequest(_ request: AVAsynchronousVideoCompositionRequest) {
        // render HDR-preserving output
    }
}

The significant protocol boundary is Apple’s AVVideoCompositing; the sample does not define its own builder protocol.

Access control

Reference code

CommonUI-macOS/ContentView.swift:73 — private presentation state

@State private var showingAlert = false
@State private var alertReason: AlertReason = .none
@State private var showingExportProgress = false
@State private var exportProgressChecker: AssetExporter.ProgressChecker? = nil
private let exportAssetMenuSelectPublisher =
    NotificationCenter.default.publisher(for: .exportAsset)

Logic ownership and placement

Design patterns

Naming conventions

• Variant folders name the editing mechanism: BuiltInCompositor, CIFilter, and CustomCompositor.
• The same AVVideoCompositionBuilder name is intentionally reused across exclusive targets.
• Shared types use explicit roles: AssetLoader, AssetExporter, ProgressChecker, and HDRIndicatorFilter.
• Method names state construction or operation: buildVideoComposition, loadAsCompositions, exportAsynchronously.

Architecture takeaways

• Target membership can be a clean compile-time variation point for a sample suite.
• Keep a stable builder API so playback and export use identical composition configuration.
• Encapsulate export session mutation and expose a read-only progress handle.
• Use the framework’s compositor protocol when runtime AVFoundation callbacks are the true substitution boundary.

Source map

• Official Apple documentation