Capturing Cinematic video

At a glance

Project structure

CinematicCaptureSample/
├── CinematicCaptureSampleApp.swift
├── CameraModel.swift
├── CameraView.swift
├── CaptureService.swift
├── Capture/
│   ├── DeviceLookup.swift
│   ├── MovieCapture.swift
│   └── SPCObserver.swift
├── Model/
│   ├── Camera.swift
│   ├── DataTypes.swift
│   └── MediaLibrary.swift
├── Views/
│   ├── CameraPreview.swift
│   ├── FocusOverlayView.swift
│   ├── Controls/SimulatedApertureView.swift
│   ├── Overlays/
│   └── Toolbars/
├── Support/
└── Preview Content/PreviewCameraModel.swift

Structure observations

• The sample follows the same high-level separation as AVCam but removes photo capture and specializes the service/view layer for Cinematic metadata and focus controls.
• CaptureService.swift includes the capture actor and its small observable CinematicMetadataManager, keeping metadata production beside the AVFoundation delegates.
• Views depend on the Camera protocol, while preview content provides a hardware-free conformer.

Overall architecture

flowchart LR
    App["CinematicCaptureSampleApp"] --> View["CameraView<Camera>"]
    App --> Model["CameraModel"]
    View --> Model
    Model --> Service["CaptureService actor"]
    Model --> Library["MediaLibrary actor"]
    Service --> Session["AVCaptureSession"]
    Service --> Movie["MovieCapture"]
    Service --> Metadata["CinematicMetadataManager"]
    Metadata --> Overlay["FocusOverlayView"]
    Service --> Preview["AVSampleBufferDisplayLayer"]
    Library --> Photos["PhotoKit"]

Reference code

CinematicCaptureSample/CinematicCaptureSampleApp.swift:13 — composition root

@State private var camera = CameraModel()

WindowGroup {
    CameraView(camera: camera)
        .task {
            await camera.start()
        }
}

Interpretation

The app constructs one long-lived model. The model presents a main-actor interface to SwiftUI, while the capture actor owns session configuration, video/metadata callbacks, and movie capture. A separate actor saves the completed movie. Calling this MVVM is an interpretation supported by the explicit model mediation and source comments.

Ownership and state

classDiagram
    CinematicCaptureSampleApp *-- CameraModel : State creates
    CameraView --> CameraModel : observes and sends intents
    CameraModel *-- AVSampleBufferDisplayLayer : creates
    CameraModel *-- CaptureService : creates with preview layer
    CameraModel *-- MediaLibrary : creates
    CaptureService *-- AVCaptureSession : creates
    CaptureService *-- MovieCapture : creates
    CaptureService *-- CinematicMetadataManager : creates
    FocusOverlayView --> CinematicMetadataManager : observes

Ownership evidence

CinematicCaptureSample/CameraModel.swift:58 — model composition

private let mediaLibrary = MediaLibrary()
private let captureService: CaptureService

init() {
    captureService = CaptureService(
        previewLayer: preview as! AVSampleBufferDisplayLayer
    )
}

Class and protocol design

classDiagram
    class Camera {
        <<protocol>>
    }
    class OutputService {
        <<protocol>>
    }
    CameraModel ..|> Camera
    PreviewCameraModel ..|> Camera
    CameraView --> Camera
    FocusOverlayView --> Camera
    MovieCapture ..|> OutputService
    CaptureService --> OutputService

Reference code

CinematicCaptureSample/Model/Camera.swift:13 — view-facing capability

@MainActor
protocol Camera: AnyObject, SendableMetatype {
    var status: CameraStatus { get }
    var metadataManager: CinematicMetadataManager { get }
    var preview: CALayer { get }
    func toggleRecording() async
    func tapPreview(at point: CGPoint) async
}

Access control

Reference code

CinematicCaptureSample/Views/FocusOverlayView.swift:110 — same-file-only helper

fileprivate extension CGPoint {
    func normalized(for proxy: GeometryProxy) -> CGPoint {
        .init(x: x / proxy.size.width, y: y / proxy.size.height)
    }
}

No public or open declaration appears in the Swift source.

Logic ownership and placement

Design patterns

Main application flow

sequenceDiagram
    participant Output as Metadata output
    participant Service as CaptureService
    participant Store as CinematicMetadataManager
    participant Overlay as FocusOverlayView
    actor User
    Output->>Service: metadataOutput(objects)
    Service->>Store: replace normalized focus metadata
    Store-->>Overlay: observable update
    User->>Overlay: tap or long press
    Overlay->>Service: focus command through CameraModel
    Service->>Service: configure device focus

Reference code

CinematicCaptureSample/CaptureService.swift:498 — metadata publication

nonisolated func metadataOutput(_ output: AVCaptureMetadataOutput,
                                didOutput metadataObjects: [AVMetadataObject],
                                from connection: AVCaptureConnection) {
    assumeIsolated { isolatedSelf in
        isolatedSelf.metadataObjectsCache = metadataObjects
        // Convert objects to CinematicFocusMetadata values.
        isolatedSelf.metadataManager.cinematicFocusMetadata = cinematicFocusMetadataObjects
    }
}

Naming conventions

• Types: responsibility and feature names (CameraModel, CaptureService, CinematicMetadataManager, FocusOverlayView).
• Protocols: capability nouns (Camera, OutputService).
• Methods: user commands (toggleRecording, tapPreview, longPressPreview) and setup verbs (setupCinematicCapture, metadataVDOSetup).
• State: is..., min..., and max... prefixes make Boolean/range semantics visible.
• Files: primary type per file, folders by Capture/Model/Views/Support responsibility.

Architecture takeaways

• Keep presentation state on the main actor and capture mutation on a dedicated serial actor executor.
• Expose focus metadata as small normalized value objects instead of raw AVFoundation objects in views.
• Use a protocol-backed camera model to keep hardware-free SwiftUI previews possible.
• A same-file fileprivate extension is a precise home for view-only geometry helpers.
• The movie-output delegate remains inside MovieCapture, while CaptureService coordinates Cinematic-specific behavior.

Source map

• Official Apple documentation