Skip to content

Camera Capture Diagnostics ​

Systematic troubleshooting for AVFoundation camera problems: black or frozen previews, wrong rotation, slow capture, session interruptions, permission problems, slow launch, and dropped frames. The cause is usually threading, session lifecycle, rotation, permissions, or configuration, so the diagnostic checks those before you debug capture code.

Symptoms This Diagnoses ​

Use when you're experiencing:

  • "No camera device found" or a black preview while running in the Simulator
  • Black or frozen camera preview
  • Black preview with no error at all — no exception, no log, and setup appeared to succeed
  • Camera worked, then went black mid-session and stayed black until relaunch
  • UI freezes for 1–3 seconds when opening the camera
  • Camera freezes during a phone call or in Split View
  • Preview or captured photo rotated 90 degrees
  • Front camera photo doesn't match the mirrored preview
  • Photo capture takes 2 or more seconds
  • Slow camera launch, with the preview taking a second or more to appear
  • ProRes or high-bitrate recording drops frames
  • "Camera in use by another app" errors
  • Camera stops working after prolonged use (thermal pressure)
  • Crash on older iOS versions that lack iOS 17 APIs
  • Camera permission denied or never requested

Example Prompts ​

  • "Why does AVCaptureDevice.default return nil in the Simulator?"
  • "My camera preview is just a black screen"
  • "The preview is black but nothing errors — should I rewrite this with DiscoverySession?"
  • "My camera dies partway through and only a relaunch fixes it — how do I even see the error?"
  • "The UI freezes when I open the camera"
  • "Camera freezes when I get a phone call"
  • "Why is the captured photo rotated wrong?"
  • "The front camera photo doesn't match the preview"
  • "Photo capture is really slow, takes 2+ seconds"
  • "My camera app launches slowly"
  • "My ProRes recording drops frames"
  • "Camera crashes on iOS 16 devices"
  • "User says camera permission is denied but they never saw a prompt"

Diagnostic Workflow ​

First, make sure you're on a real device: the Simulator has no camera hardware. Then:

1. Check Session State
   ├─ Verify session.isRunning = true
   ├─ Verify inputs.count >= 1
   ├─ Verify outputs.count >= 1
   └─ Check the preview layer connection

2. Check Threading
   ├─ Verify startRunning() runs on a background queue
   ├─ Verify all session work runs on sessionQueue
   └─ Verify UI updates run on the main thread

3. Check Permissions
   ├─ Print authorizationStatus
   ├─ Handle .notDetermined (request access)
   └─ Handle .denied (prompt to open Settings)

4. Check Interruptions
   ├─ Add an interruption observer
   ├─ Reproduce with a phone call
   └─ Verify the UI shows feedback

5. Turn On the Error Channel (do this first if the console is clean)
   ├─ Observe runtimeErrorNotification
   ├─ Observe didStopRunning, didStartRunning, and wasInterrupted
   └─ Recover from runtime errors: the session won't restart itself

A clean console doesn't mean capture is working. AVCaptureSession reports most runtime failures through notifications rather than thrown errors, so a session that fails while running stays black and silent unless you observe them.

Diagnostic Patterns ​

The skill covers 18 diagnostic patterns. Common symptoms and their fixes:

SymptomCheck FirstLikely Fix
Black previewSession stateStart the session, add an input, connect the preview layer
Black preview, no error at allAdd a deinit print to the camera controllerKeep the controller alive for the view's lifetime
UI freezesThreadingMove startRunning() to a background queue
Freezes on callInterruptionsAdd an interruption observer with UI feedback
Wrong rotationRotation angleUse RotationCoordinator (iOS 17 and later)
Slow captureQuality settingSet photoQualityPrioritization to .speed or .balanced
Slow launchLaunch-to-preview timeAdopt deferred start (iOS 26 and later)
Recording drops frameshardwareCost and system pressureLower the format or frame rate; use Pro Video Storage for ProRes (iOS 27)
Denied accessPermissionsShow a prompt to open Settings
Crash on old iOS@available checkGuard iOS 17 APIs
Random stopsThermal stateReduce quality and show a cooling message
iPad Split ViewMultitaskingShow an "unavailable in Split View" message
Front camera "bug"MirroringExpected: the preview mirrors and the photo doesn't (Apple's standard)

Documentation Scope ​

This page documents the camera-capture-diag diagnostic skill (in the axiom-media suite). It runs the checks above before your assistant debugs any code, and each of its 18 patterns includes specific symptoms, diagnostic steps, fixes, and an estimated time to fix.

  • camera-capture – Camera implementation patterns and session setup, including deferred start and Pro Video Storage
  • camera-capture-ref – Complete AVFoundation camera API reference
  • camera-auditor – Scans your code for capture problems, including a missing runtime-error observer
  • photo-library – Photo picking and library access

Resources ​

WWDC: 2021-10247, 2023-10105, 2026-303

Docs: /avfoundation/avcapturesession

Released under the MIT License