Supporting device rotation in your camera app

At a glance

Platform boundary: the DocC record lists iOS, iPadOS, and Mac Catalyst. In the downloaded project, every target sets SUPPORTS_MACCATALYST = NO and SDKROOT = iphoneos (AVCam.xcodeproj/project.pbxproj:945), so the source shows only an iPhone and iPad build. The project also sets an iOS 26.0 deployment target (AVCam.xcodeproj/project.pbxproj:936), while the DocC record lists 27.0.

Project structure

AVCam.xcodeproj/                     (3 targets, no Swift packages)
AVCam/                               app target sources (also compiled into the capture extension)
├── AVCamApp.swift                   @main App, creates CameraModel
├── CameraModel.swift                @MainActor @Observable model
├── CaptureService.swift             actor; session, devices, rotation coordinator
├── CameraView.swift                 root view, generic over Camera
├── Capture/
│   ├── PhotoCapture.swift           OutputService for AVCapturePhotoOutput
│   ├── MovieCapture.swift           OutputService for AVCaptureMovieFileOutput
│   ├── DeviceLookup.swift           discovery sessions
│   └── SPCObserver.swift            SystemPreferredCameraObserver (KVO -> AsyncStream)
├── Model/
│   ├── Camera.swift                 @MainActor protocol for the view model
│   ├── CameraState.swift            persisted state shared with the extension
│   ├── DataTypes.swift              enums, value types, OutputService protocol
│   ├── MediaLibrary.swift           actor; Photos saving and thumbnails
│   └── Intent/AVCamCaptureIntent.swift
├── Views/                           CameraPreview, PreviewContainer, CameraUI, toolbars, overlays
├── Support/                         extensions
└── Preview Content/PreviewCameraModel.swift
AVCamCaptureExtension/               LockedCameraCaptureExtension entry
AVCamControlCenterExtension/         ControlWidget bundle

Structure observations

• The project has three native targets: AVCam (application), AVCamCaptureExtension (ExtensionKit extension), and AVCamControlCenterExtension (app extension) (AVCam.xcodeproj/project.pbxproj:445).
• The capture extension’s Sources phase compiles the shared app files. This includes CaptureService.swift and CameraModel.swift but not AVCamApp.swift (AVCam.xcodeproj/project.pbxproj:525, AVCam.xcodeproj/project.pbxproj:542). That is how AVCamCaptureExtension can build its own CameraModel (AVCamCaptureExtension/AVCamCaptureExtension.swift:16).
• All rotation logic is in one // MARK: - Rotation handling section of CaptureService (AVCam/CaptureService.swift:365). One protocol-extension method in DataTypes.swift applies the capture angle to each output (AVCam/Model/DataTypes.swift:157). No view type computes angles.
• The interface-orientation settings differ by device family: iPhone supports only portrait, and iPad supports all four orientations (AVCam.xcodeproj/project.pbxproj:933, AVCam.xcodeproj/project.pbxproj:934). The view layer also defines its aspect ratios in portrait terms (AVCam/Views/PreviewContainer.swift:10).
• This snapshot also includes AVCam features unrelated to rotation: a photo-dimension picker, photo-output readiness tracking, and a menu that toggles deferred processing, responsive capture, and fast capture (AVCam/CameraModel.swift:135, AVCam/Capture/PhotoCapture.swift:169). This document mentions them only where they affect ownership or concurrency.

Overall architecture

flowchart LR
    App["AVCamApp / AVCamCaptureExtension"] --> Model["CameraModel (@MainActor)"]
    App --> View["CameraView and CameraUI"]
    View --> Model
    View --> Preview["CameraPreview / PreviewView (preview layer)"]
    Model --> Service["CaptureService actor (sessionQueue executor)"]
    Model --> Library["MediaLibrary actor"]
    Service --> Session["AVCaptureSession"]
    Service --> Rotation["RotationCoordinator + KVO observers"]
    Service --> Outputs["PhotoCapture / MovieCapture (OutputService)"]
    Service -. "PreviewSource" .-> Preview

Reference code

AVCam/CameraModel.swift:20 — CameraModel

@MainActor
@Observable
final class CameraModel: Camera {
    // ...
    /// An object that provides the connection between the capture session and the video preview layer.
    var previewSource: PreviewSource { captureService.previewSource }
    // ...
    /// An object that saves captured media to a person's Photos library.
    private let mediaLibrary = MediaLibrary()
    
    /// An object that manages the app's capture functionality.
    private let captureService = CaptureService()
    // ...
}

Interpretation

Observed: the dependencies point one way. Views know only the Camera protocol and a PreviewSource. CameraModel privately owns CaptureService and MediaLibrary. CaptureService owns every AVFoundation object, including the rotation coordinator. The only session-related value that reaches the UI is previewSource, which CameraModel forwards from the actor’s nonisolated let (AVCam/CaptureService.swift:30).

Inference: keeping rotation inside the actor means the coordinator, the observers, and output-connection writes all live in the same place as the session reconfiguration that replaces them (changeCaptureDevice(to:)). The view layer never needs to know about device orientation.

Ownership and state

classDiagram
    AVCamApp *-- CameraModel : @State camera
    AVCamCaptureExtension *-- CameraModel : @State camera
    CameraModel *-- CaptureService : private let
    CameraModel *-- MediaLibrary : private let
    CameraModel *-- CameraState : private var
    CaptureService *-- AVCaptureSession : private let
    CaptureService *-- PhotoCapture : private let
    CaptureService *-- MovieCapture : private let
    CaptureService *-- RotationCoordinator : private var, replaced per device
    CaptureService *-- DefaultPreviewSource : nonisolated let
    CameraView o-- CameraModel : receives
    CameraPreview o-- DefaultPreviewSource : receives as PreviewSource
    CameraPreview *-- PreviewView : makeUIView

Ownership evidence

AVCam/CaptureService.swift:30 — CaptureService stored properties

actor CaptureService {
    // ...
    /// A type that connects a preview destination with the capture session.
    nonisolated let previewSource: PreviewSource
    
    // The app's capture session.
    private let captureSession = AVCaptureSession()
    
    // An object that manages the app's photo capture behavior.
    private let photoCapture = PhotoCapture()
    
    // An object that manages the app's video capture behavior.
    private let movieCapture = MovieCapture()
    
    // An internal collection of output services.
    private var outputServices: [any OutputService] { [photoCapture, movieCapture] }
    // ...
    // An object that monitors video device rotations.
    private var rotationCoordinator: AVCaptureDevice.RotationCoordinator!
    private var rotationObservers = [AnyObject]()
    // ...
}

Observed: CameraView stores the model in a @State property but does not create it. The object still comes from the app or extension entry point, so the view’s property is a shared reference, not a second owner. PreviewView uses AVCaptureVideoPreviewLayer as its backing layer class (AVCam/Views/CameraPreview.swift:54), so the UIKit view owns the layer, and the capture session is attached later through PreviewTarget.setSession(_:).

Concurrency, scheduling, and thread safety

Evidence limit: actor isolation, async/await, or Task creation does not by itself prove background-thread execution; Sendable conformance alone does not prove thread-safe mutation.

Reference code

AVCam/CaptureService.swift:70 — the actor’s custom serial executor

actor CaptureService {
    // ...
    // A serial dispatch queue to use for capture control actions.
    private let sessionQueue = DispatchSerialQueue(label: "com.example.apple-samplecode.AVCam.sessionQueue")
    
    // Sets the session queue as the actor's executor.
    nonisolated var unownedExecutor: UnownedSerialExecutor {
        sessionQueue.asUnownedSerialExecutor()
    }
    // ...
}

Interpretation: the custom executor is the specific source evidence that moves capture work off the main actor. actor alone would not establish that. The README states the goal directly: the actor exists “to ensure that AVFoundation capture API calls don’t occur on the main thread” (README.md:13). Because AVFoundation callbacks for controls use the same queue, those callbacks and actor jobs are serialized by one queue. The rotation KVO callbacks do not use that queue, which is why they re-enter through Task { await ... }.

Not established by source: which thread delivers the rotation coordinator’s KVO notifications, and whether MovieCapture.captureActivity, which the main-run-loop timer writes, is protected against the actor’s other accesses. The source shows no lock for that property.

State propagation, frameworks, and dependencies

Evidence limit: an import proves a source-level compilation dependency at the cited line; it does not prove runtime use, architectural adoption, or whether a Swift package is a direct application dependency.

Combine scheduling: the source never calls receive(on:) or subscribe(on:). Publisher values reach CameraModel through .values async sequences inside main-actor tasks. Observed: this is the only path by which actor-owned publishers update model state.

Class and protocol design

classDiagram
    class Camera {
        <<protocol>>
    }
    class OutputService {
        <<protocol>>
        setVideoRotationAngle(angle)
    }
    class PreviewSource {
        <<protocol>>
    }
    class PreviewTarget {
        <<protocol>>
    }
    CameraModel ..|> Camera
    PreviewCameraModel ..|> Camera
    PhotoCapture ..|> OutputService
    MovieCapture ..|> OutputService
    DefaultPreviewSource ..|> PreviewSource
    PreviewView ..|> PreviewTarget
    CaptureService --> OutputService : rotates all outputs
    CameraView --> Camera : generic constraint

Reference code

AVCam/Model/DataTypes.swift:147 — OutputService and its default rotation method

protocol OutputService {
    associatedtype Output: AVCaptureOutput
    var output: Output { get }
    var captureActivity: CaptureActivity { get }
    var capabilities: CaptureCapabilities { get }
    func updateConfiguration(for device: AVCaptureDevice)
    func setVideoRotationAngle(_ angle: CGFloat)
}

extension OutputService {
    func setVideoRotationAngle(_ angle: CGFloat) {
        // Set the rotation angle on the output object's video connection.
        output.connection(with: .video)?.videoRotationAngle = angle
    }
    func updateConfiguration(for device: AVCaptureDevice) {}
}

Observed: OutputService declares setVideoRotationAngle(_:) as a requirement and provides it in an extension, so both outputs inherit one implementation. CaptureService rotates through [any OutputService] (AVCam/CaptureService.swift:42), so adding another output to that array would include it in rotation updates. Views are generic over CameraModel: Camera (AVCam/CameraView.swift:13), and PreviewCameraModel conforms to Camera (AVCam/Preview Content/PreviewCameraModel.swift:13).

Access control

Reference code

AVCam/CaptureService.swift:368 — private rotation API

actor CaptureService {
    // ...
    /// Create a new rotation coordinator for the specified device and observe its state to monitor rotation changes.
    private func createRotationCoordinator(for device: AVCaptureDevice) {
        // Create a new rotation coordinator for this device.
        rotationCoordinator = AVCaptureDevice.RotationCoordinator(device: device, previewLayer: videoPreviewLayer)
        // ...
    }
    // ...
}

All types are in a single module, so most declarations use Swift’s implicit internal. The private and private(set) modifiers above are the boundaries that matter.

Logic ownership and placement

Design patterns

Removed from the draft: “Service object”. It came from the Service suffix. Here OutputService is a protocol for output wrappers, and CaptureService is better described by the verified actor-isolation and protocol boundaries above. No MVVM, Coordinator, or Adapter label is claimed: the source neither names those roles nor establishes them.

Main application flow

sequenceDiagram
    participant Coord as RotationCoordinator
    participant KVO as KVO closure
    participant Service as CaptureService (sessionQueue)
    participant Main as MainActor
    participant Outputs as OutputService connections
    Service->>Coord: init(device:previewLayer:)
    Service->>Main: initial preview angle
    Service->>Outputs: initial capture angle
    Service->>Coord: observe preview and capture angles
    Coord-->>KVO: angle changed
    KVO->>Service: Task { await updatePreviewRotation }
    Service->>Main: Task { @MainActor } set preview angle
    KVO->>Service: Task { await updateCaptureRotation }
    Service->>Outputs: setVideoRotationAngle(angle)

Reference code

AVCam/CaptureService.swift:368 — coordinator creation and observation

    private func createRotationCoordinator(for device: AVCaptureDevice) {
        // Create a new rotation coordinator for this device.
        rotationCoordinator = AVCaptureDevice.RotationCoordinator(device: device, previewLayer: videoPreviewLayer)
        
        // Set initial rotation state on the preview and output connections.
        updatePreviewRotation(rotationCoordinator.videoRotationAngleForHorizonLevelPreview)
        updateCaptureRotation(rotationCoordinator.videoRotationAngleForHorizonLevelCapture)
        
        // Cancel previous observations.
        rotationObservers.removeAll()
        
        // Add observers to monitor future changes.
        rotationObservers.append(
            rotationCoordinator.observe(\.videoRotationAngleForHorizonLevelPreview, options: .new) { [weak self] _, change in
                guard let self, let angle = change.newValue else { return }
                // Update the capture preview rotation.
                Task { await self.updatePreviewRotation(angle) }
            }
        )
        // ...
    }

AVCam/CaptureService.swift:397 — the two appliers

    private func updatePreviewRotation(_ angle: CGFloat) {
        let connection = videoPreviewLayer.connection
        Task { @MainActor in
            // Set initial rotation angle on the video preview.
            connection?.videoRotationAngle = angle
        }
    }
    
    private func updateCaptureRotation(_ angle: CGFloat) {
        // Update the orientation for all output services.
        outputServices.forEach { $0.setVideoRotationAngle(angle) }
    }

Observed: preview and capture angles are separate inputs with separate destinations. The preview angle goes to the preview layer’s connection, and the capture angle goes to every output’s video connection. Inference, consistent with Apple’s abstract: separating them lets the iPhone build, whose interface is portrait-only, keep a correct preview while photos and movies still record upright in any device orientation.

Naming conventions

• Types: role nouns that pair a domain with a responsibility: CaptureService (actor), CameraModel (concrete model), PhotoCapture and MovieCapture (output wrappers), DeviceLookup, MediaLibrary, SystemPreferredCameraObserver. AVFoundation delegate adopters end in Delegate (PhotoCaptureDelegate, CaptureControlsDelegate). The protocol default implementation is DefaultPreviewSource, and the preview stub is PreviewCameraModel.
• Protocols: Camera names the capability that views consume. OutputService, PreviewSource, and PreviewTarget name collaborator roles. The concrete class is named CameraModel, and views use CameraModel as their generic parameter name (CameraView<CameraModel: Camera>), which shadows the concrete type inside those views.
• Methods: rotation verbs mirror the AVFoundation vocabulary: createRotationCoordinator(for:), updatePreviewRotation(_:), updateCaptureRotation(_:), setVideoRotationAngle(_:). Long-lived subscriptions use observe…/monitor… (observeNotifications, monitorSystemPreferredCamera, observeSubjectAreaChanges(of:)). Booleans use is…, prefers…, should… (isSwitchingVideoDevices, prefersMinimizedUI, shouldFlashScreen).
• Files and extensions: generally one primary type per file, named after it. Exceptions: SPCObserver.swift holds SystemPreferredCameraObserver, and DataTypes.swift groups enums, value types, and the OutputService protocol. Folders group by role (Capture/, Model/, Views/Toolbars/...).

Architecture takeaways

• A custom actor executor is the verified piece that puts capture work on a dedicated serial queue (AVCam/CaptureService.swift:73). Without it, actor would not say where the work runs.
• Rotation is owned by the object that owns the device. The coordinator is rebuilt inside every device change, inside the same configuration transaction, so rotation state cannot drift from the active input.
• Preview and capture rotation are separate data flows with different isolation: preview writes go to the main actor, and output writes stay on the actor.
• A protocol extension (OutputService.setVideoRotationAngle) gives every output wrapper the same rotation behavior, and fan-out over [any OutputService] keeps CaptureService free of output-specific code.
• Task lifetime is mostly implicit: one subject-area task is stored and cancelled, while the notification, preferred-camera, and model-observation loops are unretained. That is a deliberate reading point for anyone adapting this code.

Source map

• Official Apple documentation