Camera Capture with AVFoundation

Guides you through implementing camera capture: session setup, photo capture, video recording, responsive capture UX, rotation handling, and session lifecycle management.

When to Use This Skill

Use when you need to:

• ☑ Build a custom camera UI (not system picker)
• ☑ Capture photos with quality/speed tradeoffs
• ☑ Record video with audio
• ☑ Handle device rotation correctly (RotationCoordinator)
• ☑ Make capture feel responsive (zero-shutter-lag)
• ☑ Handle session interruptions (phone calls, multitasking)
• ☑ Switch between front/back cameras
• ☑ Configure capture quality and resolution

Example Prompts

"How do I set up a camera preview in SwiftUI?" "My camera freezes when I get a phone call" "The photo preview is rotated wrong on front camera" "How do I make photo capture feel instant?" "Should I use deferred processing?" "My camera takes too long to capture" "How do I switch between front and back cameras?" "How do I record video with audio?"

Red Flags

Signs you're making this harder than it needs to be:

• ❌ Calling startRunning() on main thread (blocks UI for seconds)
• ❌ Using deprecated videoOrientation instead of RotationCoordinator (iOS 17+)
• ❌ Not observing session interruptions (app freezes on phone call)
• ❌ Creating new AVCaptureSession for each capture (expensive)
• ❌ Using .photo preset for video (wrong format)
• ❌ Ignoring photoQualityPrioritization (slow captures)
• ❌ Not handling .notAuthorized permission state
• ❌ Modifying session without beginConfiguration()/commitConfiguration()
• ❌ Using UIImagePickerController for custom camera UI (limited control)

Mandatory First Steps

Before implementing any camera feature:

1. Choose Your Capture Mode

What do you need?

┌─ Just let user pick a photo?
│  └─ Don't use AVFoundation - use PHPicker or PhotosPicker
│     See: /skill axiom-photo-library
│
├─ Simple photo/video capture with system UI?
│  └─ UIImagePickerController (but limited customization)
│
├─ Custom camera UI with photo capture?
│  └─ AVCaptureSession + AVCapturePhotoOutput
│     → Continue with this skill
│
├─ Custom camera UI with video recording?
│  └─ AVCaptureSession + AVCaptureMovieFileOutput
│     → Continue with this skill
│
└─ Both photo and video in same session?
   └─ AVCaptureSession + both outputs
      → Continue with this skill

2. Request Camera Permission

import AVFoundation

func requestCameraAccess() async -> Bool {
    let status = AVCaptureDevice.authorizationStatus(for: .video)

    switch status {
    case .authorized:
        return true
    case .notDetermined:
        return await AVCaptureDevice.requestAccess(for: .video)
    case .denied, .restricted:
        // Show settings prompt
        return false
    @unknown default:
        return false
    }
}

Info.plist required:

<key>NSCameraUsageDescription</key>
<string>Take photos and videos</string>

For audio (video recording):

<key>NSMicrophoneUsageDescription</key>
<string>Record audio with video</string>

3. Understand Session Architecture

AVCaptureSession
    ├─ Inputs
    │   ├─ AVCaptureDeviceInput (camera)
    │   └─ AVCaptureDeviceInput (microphone, for video)
    │
    ├─ Outputs
    │   ├─ AVCapturePhotoOutput (photos)
    │   ├─ AVCaptureMovieFileOutput (video files)
    │   └─ AVCaptureVideoDataOutput (raw frames)
    │
    └─ Connections (automatic between compatible input/output)

Key rule: All session configuration happens on a dedicated serial queue, never main thread.

Core Patterns

Pattern 1: Basic Session Setup

Use case: Set up camera preview with photo capture capability.

import AVFoundation

class CameraManager: NSObject {
    let session = AVCaptureSession()
    let photoOutput = AVCapturePhotoOutput()

    // CRITICAL: Dedicated serial queue for session work
    private let sessionQueue = DispatchQueue(label: "camera.session")

    func setupSession() {
        sessionQueue.async { [self] in
            session.beginConfiguration()
            defer { session.commitConfiguration() }

            // 1. Set session preset
            session.sessionPreset = .photo

            // 2. Add camera input
            guard let camera = AVCaptureDevice.default(.builtInWideAngleCamera,
                                                        for: .video,
                                                        position: .back),
                  let input = try? AVCaptureDeviceInput(device: camera),
                  session.canAddInput(input) else {
                return
            }
            session.addInput(input)

            // 3. Add photo output
            guard session.canAddOutput(photoOutput) else { return }
            session.addOutput(photoOutput)

            // 4. Configure photo output
            photoOutput.isHighResolutionCaptureEnabled = true
            photoOutput.maxPhotoQualityPrioritization = .quality
        }
    }

    func startSession() {
        sessionQueue.async { [self] in
            if !session.isRunning {
                session.startRunning()  // Blocking call - never on main thread!
            }
        }
    }

    func stopSession() {
        sessionQueue.async { [self] in
            if session.isRunning {
                session.stopRunning()
            }
        }
    }
}

Cost: 30 min implementation

Pattern 2: SwiftUI Camera Preview

Use case: Display camera preview in SwiftUI view.

import SwiftUI
import AVFoundation

struct CameraPreview: UIViewRepresentable {
    let session: AVCaptureSession

    func makeUIView(context: Context) -> PreviewView {
        let view = PreviewView()
        view.previewLayer.session = session
        view.previewLayer.videoGravity = .resizeAspectFill
        return view
    }

    func updateUIView(_ uiView: PreviewView, context: Context) {}

    class PreviewView: UIView {
        override class var layerClass: AnyClass { AVCaptureVideoPreviewLayer.self }
        var previewLayer: AVCaptureVideoPreviewLayer { layer as! AVCaptureVideoPreviewLayer }
    }
}

// Usage in SwiftUI
struct CameraView: View {
    @StateObject private var camera = CameraManager()

    var body: