AVFoundation 相机问题诊断指南：解决 iOS 相机预览冻结、旋转错误、捕获缓慢

axiom-camera-capture-diag by charleswiltgen/axiom

160 周安装量

767 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/charleswiltgen/axiom --skill axiom-camera-capture-diag

iOS 移动应用调试

🇨🇳中文介绍

相机捕获诊断

针对 AVFoundation 相机问题的系统性故障排除：预览冻结、旋转错误、捕获缓慢、会话中断和权限问题。

概述

核心原则：当相机无法正常工作时，问题通常出在：

线程处理（会话在主线程上工作）- 35%
会话生命周期（未启动、中断、未配置）- 25%
旋转（使用了已弃用的 API，缺少协调器）- 20%
权限（被拒绝、未请求）- 15%
配置（预设错误，缺少输入/输出）- 5%

在调试捕获逻辑之前，务必先检查线程处理和会话状态。

危险信号

指示特定相机问题的症状：

症状	可能原因
预览显示黑屏	会话未启动、权限被拒绝、无相机输入
打开相机时 UI 冻结	在主线程上调用了 `startRunning()`
来电时相机冻结	未处理中断
预览旋转错误 90°	未使用 RotationCoordinator (iOS 17+)
捕获的照片旋转错误

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

强制性的第一步

在调查代码之前，运行这些诊断：

步骤 1：检查会话状态

print("📷 Session state:")
print("  isRunning: \(session.isRunning)")
print("  inputs: \(session.inputs.count)")
print("  outputs: \(session.outputs.count)")

for input in session.inputs {
    if let deviceInput = input as? AVCaptureDeviceInput {
        print("  Input: \(deviceInput.device.localizedName)")
    }
}

for output in session.outputs {
    print("  Output: \(type(of: output))")
}

✅ isRunning: true, inputs ≥ 1, outputs ≥ 1 → 会话正常工作
⚠️ isRunning: false → 会话未启动或中断
❌ inputs: 0 → 未添加相机（权限？配置？）

步骤 2：检查线程处理

print("🧵 Thread check:")

// 设置会话时
sessionQueue.async {
    print("  Setup thread: \(Thread.isMainThread ? "❌ MAIN" : "✅ Background")")
}

// 启动会话时
sessionQueue.async {
    print("  Start thread: \(Thread.isMainThread ? "❌ MAIN" : "✅ Background")")
}

✅ 全部在后台 → 正确
❌ 任何在主线程 → UI 将冻结

步骤 3：检查权限

let status = AVCaptureDevice.authorizationStatus(for: .video)
print("🔐 Camera permission: \(status.rawValue)")

switch status {
case .authorized: print("  ✅ Authorized")
case .notDetermined: print("  ⚠️ Not yet requested")
case .denied: print("  ❌ Denied by user")
case .restricted: print("  ❌ Restricted (parental controls?)")
@unknown default: print("  ❓ Unknown")
}

步骤 4：检查中断情况

// 添加临时观察器以查看中断
NotificationCenter.default.addObserver(
    forName: .AVCaptureSessionWasInterrupted,
    object: session,
    queue: .main
) { notification in
    if let reason = notification.userInfo?[AVCaptureSessionInterruptionReasonKey] as? Int {
        print("🚨 Interrupted: reason \(reason)")
    }
}

Camera not working as expected?
│
├─ Black/frozen preview?
│  ├─ Check Step 1 (session state)
│  │  ├─ isRunning = false → See Pattern 1 (session not started)
│  │  ├─ inputs = 0 → See Pattern 2 (no camera input)
│  │  └─ isRunning = true, inputs > 0 → See Pattern 3 (preview layer)
│
├─ UI freezes when opening camera?
│  └─ Check Step 2 (threading)
│     └─ Main thread → See Pattern 4 (move to session queue)
│
├─ Camera freezes during use?
│  ├─ After phone call → See Pattern 5 (interruption handling)
│  ├─ In Split View (iPad) → See Pattern 6 (multitasking)
│  └─ Random freezes → See Pattern 7 (thermal pressure)
│
├─ Preview/photo rotated wrong?
│  ├─ Preview rotated → See Pattern 8 (RotationCoordinator preview)
│  ├─ Captured photo rotated → See Pattern 9 (capture rotation)
│  └─ Front camera "wrong" → See Pattern 10 (mirroring expected)
│
├─ Capture too slow?
│  ├─ 2+ seconds delay → See Pattern 11 (quality prioritization)
│  └─ Slight delay → See Pattern 12 (deferred processing)
│
├─ Permission issues?
│  ├─ Status: notDetermined → See Pattern 13 (request permission)
│  └─ Status: denied → See Pattern 14 (settings prompt)
│
└─ Crash on some devices?
   └─ See Pattern 15 (API availability)

模式 1：会话未启动

症状：黑屏预览，isRunning = false

从未调用 startRunning()
调用了 startRunning() 但会话没有输入
会话停止后从未重新启动

// Check if startRunning was called
print("isRunning before start: \(session.isRunning)")
session.startRunning()
print("isRunning after start: \(session.isRunning)")

// Ensure session is started on session queue
func startSession() {
    sessionQueue.async { [self] in
        guard !session.isRunning else { return }

        // Verify we have inputs before starting
        guard !session.inputs.isEmpty else {
            print("❌ Cannot start - no inputs configured")
            return
        }

        session.startRunning()
    }
}

修复时间：10 分钟

模式 2：无相机输入

症状：session.inputs.count = 0

相机权限被拒绝
AVCaptureDeviceInput 创建失败
canAddInput() 返回 false
配置未提交

// Step through input setup
guard let camera = AVCaptureDevice.default(for: .video) else {
    print("❌ No camera device found")
    return
}
print("✅ Camera: \(camera.localizedName)")

do {
    let input = try AVCaptureDeviceInput(device: camera)
    print("✅ Input created")

    if session.canAddInput(input) {
        print("✅ Can add input")
    } else {
        print("❌ Cannot add input - check session preset compatibility")
    }
} catch {
    print("❌ Input creation failed: \(error)")
}

修复：确保在创建输入之前已授予权限，并包装在配置块中：

session.beginConfiguration()
// Add input here
session.commitConfiguration()

修复时间：15 分钟

模式 3：预览层未连接

症状：isRunning = true，输入已配置，但预览是黑屏

预览层会话未设置
预览层不在视图层级中
预览层 frame 为零

print("Preview layer session: \(previewLayer.session != nil)")
print("Preview layer superlayer: \(previewLayer.superlayer != nil)")
print("Preview layer frame: \(previewLayer.frame)")
print("Preview layer connection: \(previewLayer.connection != nil)")

// Ensure preview layer is properly configured
previewLayer.session = session
previewLayer.videoGravity = .resizeAspectFill

// Ensure frame is set (common in SwiftUI)
previewLayer.frame = view.bounds

修复时间：10 分钟

模式 4：主线程阻塞

症状：打开相机时 UI 冻结 1-3 秒

根本原因：startRunning() 是一个阻塞调用，在主线程上执行

// If this prints on main thread, that's the problem
print("startRunning on thread: \(Thread.current)")
session.startRunning()

// Create dedicated serial queue
private let sessionQueue = DispatchQueue(label: "camera.session")

func startSession() {
    sessionQueue.async { [self] in
        session.startRunning()
    }
}

修复时间：15 分钟

模式 5：来电中断

症状：相机正常工作，来电时冻结

根本原因：会话中断但未处理/无 UI 反馈

// Check if session is still running after returning from call
print("Session running: \(session.isRunning)")
// Will be false during active call, true after call ends

修复：添加中断观察器（参见 camera-capture 技能模式 5）

关键点：中断结束后会话会自动恢复。您不需要再次调用 startRunning()。只需更新您的 UI。

修复时间：30 分钟

模式 6：分屏视图相机不可用

症状：iPad 进入分屏视图时相机停止工作

根本原因：多个前台应用运行时相机不可用

// Check interruption reason
// InterruptionReason.videoDeviceNotAvailableWithMultipleForegroundApps

修复：显示适当的 UI 消息，并在用户退出分屏视图时恢复：

case .videoDeviceNotAvailableWithMultipleForegroundApps:
    showMessage("Camera unavailable in Split View. Use full screen.")

修复时间：15 分钟

模式 7：热压力

症状：相机随机停止，尤其是在长时间使用后

根本原因：设备发热，系统减少资源分配

// Check thermal state
print("Thermal state: \(ProcessInfo.processInfo.thermalState.rawValue)")
// 0 = nominal, 1 = fair, 2 = serious, 3 = critical

修复：降低质量或显示冷却消息：

case .videoDeviceNotAvailableDueToSystemPressure:
    // Reduce quality
    session.sessionPreset = .medium
    showMessage("Camera quality reduced due to device temperature")

修复时间：20 分钟

模式 8：预览旋转错误

症状：预览旋转了 90°，与预期不符

根本原因：未使用 RotationCoordinator (iOS 17+) 或未观察更新

print("Preview connection rotation: \(previewLayer.connection?.videoRotationAngle ?? -1)")

// Create and observe RotationCoordinator
let coordinator = AVCaptureDevice.RotationCoordinator(device: camera, previewLayer: previewLayer)

// Set initial rotation
previewLayer.connection?.videoRotationAngle = coordinator.videoRotationAngleForHorizonLevelPreview

// Observe changes
observation = coordinator.observe(\.videoRotationAngleForHorizonLevelPreview) { [weak previewLayer] coord, _ in
    DispatchQueue.main.async {
        previewLayer?.connection?.videoRotationAngle = coord.videoRotationAngleForHorizonLevelPreview
    }
}

修复时间：30 分钟

模式 9：捕获的照片旋转错误

症状：预览看起来正确，但捕获的照片旋转了

根本原因：旋转角度未应用于照片输出连接

if let connection = photoOutput.connection(with: .video) {
    print("Photo connection rotation: \(connection.videoRotationAngle)")
}

func capturePhoto() {
    // Apply current rotation to capture
    if let connection = photoOutput.connection(with: .video) {
        connection.videoRotationAngle = rotationCoordinator.videoRotationAngleForHorizonLevelCapture
    }

    photoOutput.capturePhoto(with: settings, delegate: self)
}

修复时间：15 分钟

模式 10：前置摄像头镜像

症状：设计师说"前置摄像头照片与预览不匹配"

现实：这是正确的行为，不是错误。

预览是镜像的（就像照镜子 - 用户期望）
捕获的照片不是镜像的（共享时文字可读）
这与系统相机应用的行为一致

如果业务需要镜像照片（自拍应用）：

func mirrorImage(_ image: UIImage) -> UIImage? {
    guard let cgImage = image.cgImage else { return nil }
    return UIImage(cgImage: cgImage, scale: image.scale, orientation: .upMirrored)
}

修复时间：5 分钟（解释）或 15 分钟（如果需要镜像）

模式 11：捕获缓慢（质量优先）

症状：照片捕获耗时 2 秒以上

根本原因：photoQualityPrioritization = .quality（某些设备的默认设置）

print("Max quality prioritization: \(photoOutput.maxPhotoQualityPrioritization.rawValue)")
// Check what you're requesting in AVCapturePhotoSettings

var settings = AVCapturePhotoSettings()

// For fast capture (social/sharing)
settings.photoQualityPrioritization = .speed

// For balanced (general use)
settings.photoQualityPrioritization = .balanced

// Only use .quality when image quality is critical

修复时间：5 分钟

模式 12：延迟处理

症状：希望获得最大响应速度（零快门延迟）

解决方案：启用延迟处理 (iOS 17+)

photoOutput.isAutoDeferredPhotoDeliveryEnabled = true

// Then handle proxy in delegate:
// - didFinishProcessingPhoto gives proxy for immediate display
// - didFinishCapturingDeferredPhotoProxy gives final image later

修复时间：30 分钟

模式 13：权限未请求

症状：authorizationStatus = .notDetermined

// Must request before setting up session
Task {
    let granted = await AVCaptureDevice.requestAccess(for: .video)
    if granted {
        setupSession()
    }
}

修复时间：10 分钟

模式 14：权限被拒绝

症状：authorizationStatus = .denied

修复：显示设置提示

func showSettingsPrompt() {
    let alert = UIAlertController(
        title: "Camera Access Required",
        message: "Please enable camera access in Settings to use this feature.",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(title: "Settings", style: .default) { _ in
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    })
    alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
    present(alert, animated: true)
}

修复时间：15 分钟

模式 15：API 可用性崩溃

症状：在 iOS 16 或更早版本上崩溃

根本原因：使用 iOS 17+ API 但未进行可用性检查

if #available(iOS 17.0, *) {
    // Use RotationCoordinator
    let coordinator = AVCaptureDevice.RotationCoordinator(device: camera, previewLayer: preview)
} else {
    // Fallback to deprecated videoOrientation
    if let connection = previewLayer.connection {
        connection.videoOrientation = .portrait
    }
}

修复时间：20 分钟

症状	首先检查	可能模式
黑屏预览	步骤 1 (会话状态)	1, 2, 或 3
UI 冻结	步骤 2 (线程处理)	4
来电时冻结	步骤 4 (中断)	5
旋转错误	打印旋转角度	8 或 9
捕获缓慢	打印质量设置	11
访问被拒绝	步骤 3 (权限)	14
旧版 iOS 上崩溃	检查 @available	15

在升级相机问题之前：

☑ 会话至少有一个输入
☑ 会话至少有一个输出
☑ Session isRunning = true
☑ 预览层已连接到会话
☑ 预览层具有非零 frame

☑ 所有会话工作在 sessionQueue 上
☑ startRunning() 在后台线程
☑ UI 更新在主线程

☑ 已检查授权状态
☑ 如果状态为 notDetermined，则请求权限
☑ 针对拒绝状态有优雅的 UI

☑ RotationCoordinator 已使用 device 和 previewLayer 创建
☑ 已设置观察以获取预览角度变化
☑ 拍摄照片时应用了捕获角度

☑ 已注册中断观察器
☑ 中断状态有 UI 反馈
☑ 已测试来电情况

WWDC：2021-10247, 2023-10105

文档：/avfoundation/avcapturesession, /avfoundation/avcapturesessionwasinterruptednotification

技能：axiom-camera-capture, axiom-camera-capture-ref

🇺🇸English

Camera Capture Diagnostics

Systematic troubleshooting for AVFoundation camera issues: frozen preview, wrong rotation, slow capture, session interruptions, and permission problems.

Overview

Core Principle : When camera doesn't work, the problem is usually:

Threading (session work on main thread) - 35%
Session lifecycle (not started, interrupted, not configured) - 25%
Rotation (deprecated APIs, missing coordinator) - 20%
Permissions (denied, not requested) - 15%
Configuration (wrong preset, missing input/output) - 5%

Always check threading and session state BEFORE debugging capture logic.

Red Flags

Symptoms that indicate camera-specific issues:

Symptom	Likely Cause
Preview shows black screen	Session not started, permission denied, no camera input
UI freezes when opening camera	`startRunning()` called on main thread
Camera freezes on phone call	No interruption handling
Preview rotated 90° wrong	Not using RotationCoordinator (iOS 17+)
Captured photo rotated wrong	Rotation angle not applied to output connection
Front camera photo not mirrored	This is correct! (preview mirrors, photo does not)
"Camera in use by another app"	Another app has exclusive access
Capture takes 2+ seconds	`photoQualityPrioritization` set to `.quality`
Session won't start on iPad	Split View - camera unavailable
Crash on older iOS	Using iOS 17+ APIs without availability check

Mandatory First Steps

Before investigating code, run these diagnostics:

Step 1: Check Session State

print("📷 Session state:")
print("  isRunning: \(session.isRunning)")
print("  inputs: \(session.inputs.count)")
print("  outputs: \(session.outputs.count)")

for input in session.inputs {
    if let deviceInput = input as? AVCaptureDeviceInput {
        print("  Input: \(deviceInput.device.localizedName)")
    }
}

for output in session.outputs {
    print("  Output: \(type(of: output))")
}

Expected output :

✅ isRunning: true, inputs ≥ 1, outputs ≥ 1 → Session working
⚠️ isRunning: false → Session not started or interrupted
❌ inputs: 0 → Camera not added (permission? configuration?)

Step 2: Check Threading

print("🧵 Thread check:")

// When setting up session
sessionQueue.async {
    print("  Setup thread: \(Thread.isMainThread ? "❌ MAIN" : "✅ Background")")
}

// When starting session
sessionQueue.async {
    print("  Start thread: \(Thread.isMainThread ? "❌ MAIN" : "✅ Background")")
}

Expected output :

✅ All background → Correct
❌ Any main thread → UI will freeze

Step 3: Check Permissions

let status = AVCaptureDevice.authorizationStatus(for: .video)
print("🔐 Camera permission: \(status.rawValue)")

switch status {
case .authorized: print("  ✅ Authorized")
case .notDetermined: print("  ⚠️ Not yet requested")
case .denied: print("  ❌ Denied by user")
case .restricted: print("  ❌ Restricted (parental controls?)")
@unknown default: print("  ❓ Unknown")
}

Step 4: Check for Interruptions

// Add temporary observer to see interruptions
NotificationCenter.default.addObserver(
    forName: .AVCaptureSessionWasInterrupted,
    object: session,
    queue: .main
) { notification in
    if let reason = notification.userInfo?[AVCaptureSessionInterruptionReasonKey] as? Int {
        print("🚨 Interrupted: reason \(reason)")
    }
}

Decision Tree

Camera not working as expected?
│
├─ Black/frozen preview?
│  ├─ Check Step 1 (session state)
│  │  ├─ isRunning = false → See Pattern 1 (session not started)
│  │  ├─ inputs = 0 → See Pattern 2 (no camera input)
│  │  └─ isRunning = true, inputs > 0 → See Pattern 3 (preview layer)
│
├─ UI freezes when opening camera?
│  └─ Check Step 2 (threading)
│     └─ Main thread → See Pattern 4 (move to session queue)
│
├─ Camera freezes during use?
│  ├─ After phone call → See Pattern 5 (interruption handling)
│  ├─ In Split View (iPad) → See Pattern 6 (multitasking)
│  └─ Random freezes → See Pattern 7 (thermal pressure)
│
├─ Preview/photo rotated wrong?
│  ├─ Preview rotated → See Pattern 8 (RotationCoordinator preview)
│  ├─ Captured photo rotated → See Pattern 9 (capture rotation)
│  └─ Front camera "wrong" → See Pattern 10 (mirroring expected)
│
├─ Capture too slow?
│  ├─ 2+ seconds delay → See Pattern 11 (quality prioritization)
│  └─ Slight delay → See Pattern 12 (deferred processing)
│
├─ Permission issues?
│  ├─ Status: notDetermined → See Pattern 13 (request permission)
│  └─ Status: denied → See Pattern 14 (settings prompt)
│
└─ Crash on some devices?
   └─ See Pattern 15 (API availability)

Diagnostic Patterns

Pattern 1: Session Not Started

Symptom : Black preview, isRunning = false

Common causes :

startRunning() never called
startRunning() called but session has no inputs
Session stopped and never restarted

Diagnostic :

// Check if startRunning was called
print("isRunning before start: \(session.isRunning)")
session.startRunning()
print("isRunning after start: \(session.isRunning)")

Fix :

// Ensure session is started on session queue
func startSession() {
    sessionQueue.async { [self] in
        guard !session.isRunning else { return }

        // Verify we have inputs before starting
        guard !session.inputs.isEmpty else {
            print("❌ Cannot start - no inputs configured")
            return
        }

        session.startRunning()
    }
}

Time to fix : 10 min

Pattern 2: No Camera Input

Symptom : session.inputs.count = 0

Common causes :

Camera permission denied
AVCaptureDeviceInput creation failed
canAddInput() returned false
Configuration not committed

Diagnostic :

// Step through input setup
guard let camera = AVCaptureDevice.default(for: .video) else {
    print("❌ No camera device found")
    return
}
print("✅ Camera: \(camera.localizedName)")

do {
    let input = try AVCaptureDeviceInput(device: camera)
    print("✅ Input created")

    if session.canAddInput(input) {
        print("✅ Can add input")
    } else {
        print("❌ Cannot add input - check session preset compatibility")
    }
} catch {
    print("❌ Input creation failed: \(error)")
}

Fix : Ensure permission is granted BEFORE creating input, and wrap in configuration block:

session.beginConfiguration()
// Add input here
session.commitConfiguration()

Time to fix : 15 min

Pattern 3: Preview Layer Not Connected

Symptom : isRunning = true, inputs configured, but preview is black

Common causes :

Preview layer session not set
Preview layer not in view hierarchy
Preview layer frame is zero

Diagnostic :

print("Preview layer session: \(previewLayer.session != nil)")
print("Preview layer superlayer: \(previewLayer.superlayer != nil)")
print("Preview layer frame: \(previewLayer.frame)")
print("Preview layer connection: \(previewLayer.connection != nil)")

Fix :

// Ensure preview layer is properly configured
previewLayer.session = session
previewLayer.videoGravity = .resizeAspectFill

// Ensure frame is set (common in SwiftUI)
previewLayer.frame = view.bounds

Time to fix : 10 min

Pattern 4: Main Thread Blocking

Symptom : UI freezes for 1-3 seconds when camera opens

Root cause : startRunning() is a blocking call executed on main thread

Diagnostic :

// If this prints on main thread, that's the problem
print("startRunning on thread: \(Thread.current)")
session.startRunning()

Fix :

// Create dedicated serial queue
private let sessionQueue = DispatchQueue(label: "camera.session")

func startSession() {
    sessionQueue.async { [self] in
        session.startRunning()
    }
}

Time to fix : 15 min

Pattern 5: Phone Call Interruption

Symptom : Camera works, then freezes when phone call comes in

Root cause : Session interrupted but no handling/UI feedback

Diagnostic :

// Check if session is still running after returning from call
print("Session running: \(session.isRunning)")
// Will be false during active call, true after call ends

Fix : Add interruption observers (see camera-capture skill Pattern 5)

Key point : Session AUTOMATICALLY resumes after interruption ends. You don't need to call startRunning() again. Just update your UI.

Time to fix : 30 min

Pattern 6: Split View Camera Unavailable

Symptom : Camera stops working when iPad enters Split View

Root cause : Camera not available with multiple foreground apps

Diagnostic :

// Check interruption reason
// InterruptionReason.videoDeviceNotAvailableWithMultipleForegroundApps

Fix : Show appropriate UI message and resume when user exits Split View:

case .videoDeviceNotAvailableWithMultipleForegroundApps:
    showMessage("Camera unavailable in Split View. Use full screen.")

Time to fix : 15 min

Pattern 7: Thermal Pressure

Symptom : Camera stops randomly, especially after prolonged use

Root cause : Device getting hot, system reducing resources

Diagnostic :

// Check thermal state
print("Thermal state: \(ProcessInfo.processInfo.thermalState.rawValue)")
// 0 = nominal, 1 = fair, 2 = serious, 3 = critical

Fix : Reduce quality or show cooling message:

case .videoDeviceNotAvailableDueToSystemPressure:
    // Reduce quality
    session.sessionPreset = .medium
    showMessage("Camera quality reduced due to device temperature")

Time to fix : 20 min

Pattern 8: Preview Rotation Wrong

Symptom : Preview is rotated 90° from expected

Root cause : Not using RotationCoordinator (iOS 17+) or not observing updates

Diagnostic :

print("Preview connection rotation: \(previewLayer.connection?.videoRotationAngle ?? -1)")

Fix :

// Create and observe RotationCoordinator
let coordinator = AVCaptureDevice.RotationCoordinator(device: camera, previewLayer: previewLayer)

// Set initial rotation
previewLayer.connection?.videoRotationAngle = coordinator.videoRotationAngleForHorizonLevelPreview

// Observe changes
observation = coordinator.observe(\.videoRotationAngleForHorizonLevelPreview) { [weak previewLayer] coord, _ in
    DispatchQueue.main.async {
        previewLayer?.connection?.videoRotationAngle = coord.videoRotationAngleForHorizonLevelPreview
    }
}

Time to fix : 30 min

Pattern 9: Captured Photo Rotation Wrong

Symptom : Preview looks correct, but captured photo is rotated

Root cause : Rotation angle not applied to photo output connection

Diagnostic :

if let connection = photoOutput.connection(with: .video) {
    print("Photo connection rotation: \(connection.videoRotationAngle)")
}

Fix :

func capturePhoto() {
    // Apply current rotation to capture
    if let connection = photoOutput.connection(with: .video) {
        connection.videoRotationAngle = rotationCoordinator.videoRotationAngleForHorizonLevelCapture
    }

    photoOutput.capturePhoto(with: settings, delegate: self)
}

Time to fix : 15 min

Pattern 10: Front Camera Mirroring

Symptom : Designer says "front camera photo doesn't match preview"

Reality : This is CORRECT behavior, not a bug.

Explanation :

Preview is mirrored (like looking in a mirror - user expectation)
Captured photo is NOT mirrored (text reads correctly when shared)
This matches the system Camera app behavior

If business requires mirrored photos (selfie apps):

func mirrorImage(_ image: UIImage) -> UIImage? {
    guard let cgImage = image.cgImage else { return nil }
    return UIImage(cgImage: cgImage, scale: image.scale, orientation: .upMirrored)
}

Time to fix : 5 min (explanation) or 15 min (if mirroring required)

Pattern 11: Slow Capture (Quality Priority)

Symptom : Photo capture takes 2+ seconds

Root cause : photoQualityPrioritization = .quality (default for some devices)

Diagnostic :

print("Max quality prioritization: \(photoOutput.maxPhotoQualityPrioritization.rawValue)")
// Check what you're requesting in AVCapturePhotoSettings

Fix :

var settings = AVCapturePhotoSettings()

// For fast capture (social/sharing)
settings.photoQualityPrioritization = .speed

// For balanced (general use)
settings.photoQualityPrioritization = .balanced

// Only use .quality when image quality is critical

Time to fix : 5 min

Pattern 12: Deferred Processing

Symptom : Want maximum responsiveness (zero-shutter-lag)

Solution : Enable deferred processing (iOS 17+)

photoOutput.isAutoDeferredPhotoDeliveryEnabled = true

// Then handle proxy in delegate:
// - didFinishProcessingPhoto gives proxy for immediate display
// - didFinishCapturingDeferredPhotoProxy gives final image later

Time to fix : 30 min

Pattern 13: Permission Not Requested

Symptom : authorizationStatus = .notDetermined

Fix :

// Must request before setting up session
Task {
    let granted = await AVCaptureDevice.requestAccess(for: .video)
    if granted {
        setupSession()
    }
}

Time to fix : 10 min

Pattern 14: Permission Denied

Symptom : authorizationStatus = .denied

Fix : Show settings prompt

func showSettingsPrompt() {
    let alert = UIAlertController(
        title: "Camera Access Required",
        message: "Please enable camera access in Settings to use this feature.",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(title: "Settings", style: .default) { _ in
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    })
    alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
    present(alert, animated: true)
}

Time to fix : 15 min

Pattern 15: API Availability Crash

Symptom : Crash on iOS 16 or earlier

Root cause : Using iOS 17+ APIs without availability check

Fix :

if #available(iOS 17.0, *) {
    // Use RotationCoordinator
    let coordinator = AVCaptureDevice.RotationCoordinator(device: camera, previewLayer: preview)
} else {
    // Fallback to deprecated videoOrientation
    if let connection = previewLayer.connection {
        connection.videoOrientation = .portrait
    }
}

Time to fix : 20 min

Quick Reference Table

Symptom	Check First	Likely Pattern
Black preview	Step 1 (session state)	1, 2, or 3
UI freezes	Step 2 (threading)	4
Freezes on call	Step 4 (interruptions)	5
Wrong rotation	Print rotation angle	8 or 9
Slow capture	Print quality setting	11
Denied access	Step 3 (permissions)	14
Crash on old iOS	Check @available	15

Checklist

Before escalating camera issues:

Basics :

☑ Session has at least one input
☑ Session has at least one output
☑ Session isRunning = true
☑ Preview layer connected to session
☑ Preview layer has non-zero frame

Threading :

☑ All session work on sessionQueue
☑ startRunning() on background thread
☑ UI updates on main thread

Permissions :

☑ Authorization status checked
☑ Permission requested if notDetermined
☑ Graceful UI for denied state

Rotation :

☑ RotationCoordinator created with device AND previewLayer
☑ Observation set up for preview angle changes
☑ Capture angle applied when taking photos

Interruptions :

☑ Interruption observer registered
☑ UI feedback for interrupted state
☑ Tested with incoming phone call

Resources

WWDC : 2021-10247, 2023-10105

Docs : /avfoundation/avcapturesession, /avfoundation/avcapturesessionwasinterruptednotification

Skills : axiom-camera-capture, axiom-camera-capture-ref

Weekly Installs

Repository

charleswiltgen/axiom

GitHub Stars

606

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode85

codex79

gemini-cli78

cursor77

claude-code77

github-copilot75

AVFoundation 相机问题诊断指南：解决 iOS 相机预览冻结、旋转错误、捕获缓慢

🇨🇳中文介绍

相机捕获诊断

概述

危险信号

相关 Skills

强制性的第一步

步骤 1：检查会话状态

步骤 2：检查线程处理

步骤 3：检查权限

步骤 4：检查中断情况

决策树

诊断模式

模式 1：会话未启动

模式 2：无相机输入

模式 3：预览层未连接

模式 4：主线程阻塞

模式 5：来电中断

模式 6：分屏视图相机不可用

模式 7：热压力

模式 8：预览旋转错误

模式 9：捕获的照片旋转错误

模式 10：前置摄像头镜像

模式 11：捕获缓慢（质量优先）

模式 12：延迟处理

模式 13：权限未请求

模式 14：权限被拒绝

模式 15：API 可用性崩溃

快速参考表

检查清单

资源

🇺🇸English

Camera Capture Diagnostics

Overview

Red Flags

Mandatory First Steps

Step 1: Check Session State

Step 2: Check Threading

Step 3: Check Permissions

Step 4: Check for Interruptions

Decision Tree

Diagnostic Patterns

Pattern 1: Session Not Started

Pattern 2: No Camera Input

Pattern 3: Preview Layer Not Connected

Pattern 4: Main Thread Blocking

Pattern 5: Phone Call Interruption

Pattern 6: Split View Camera Unavailable

Pattern 7: Thermal Pressure

Pattern 8: Preview Rotation Wrong

Pattern 9: Captured Photo Rotation Wrong

Pattern 10: Front Camera Mirroring

Pattern 11: Slow Capture (Quality Priority)

Pattern 12: Deferred Processing

Pattern 13: Permission Not Requested

Pattern 14: Permission Denied

Pattern 15: API Availability Crash

Quick Reference Table

Checklist

Resources

最新 Skills