Photokit

PhotoKit

Modern patterns for photo picking, camera capture, image loading, and media permissions targeting iOS 26+ with Swift 6.3. Patterns are backward-compatible to iOS 16 unless noted. See references/photokit-patterns.md for complete picker recipes and references/camera-capture.md for AVCaptureSession patterns.

Contents

• PhotosPicker (SwiftUI, iOS 16+)
• Privacy and Permissions
• Camera Capture Basics
• Image Loading and Display
• Common Mistakes
• Review Checklist
• References

PhotosPicker (SwiftUI, iOS 16+)

PhotosPicker is the native SwiftUI replacement for UIImagePickerController. It runs out-of-process, requires no photo library permission for browsing, and supports single or multi-selection with media type filtering.

Single Selection

import SwiftUI
import PhotosUI

struct SinglePhotoPicker: View {
    @State private var selectedItem: PhotosPickerItem?
    @State private var selectedImage: Image?

    var body: some View {
        VStack {
            if let selectedImage {
                selectedImage
                    .resizable()
                    .scaledToFit()
                    .frame(maxHeight: 300)
            }

            PhotosPicker("Select Photo", selection: $selectedItem, matching: .images)
        }
        .onChange(of: selectedItem) { _, newItem in
            Task {
                if let data = try? await newItem?.loadTransferable(type: Data.self),
                   let uiImage = UIImage(data: data) {
                    selectedImage = Image(uiImage: uiImage)
                }
            }
        }
    }
}

Multi-Selection

struct MultiPhotoPicker: View {
    @State private var selectedItems: [PhotosPickerItem] = []
    @State private var selectedImages: [Image] = []

    var body: some View {
        VStack {
            ScrollView(.horizontal) {
                HStack {
                    ForEach(selectedImages.indices, id: \.self) { index in
                        selectedImages[index]
                            .resizable()
                            .scaledToFill()
                            .frame(width: 100, height: 100)
                            .clipShape(.rect(cornerRadius: 8))
                    }
                }
            }

            PhotosPicker(
                "Select Photos",
                selection: $selectedItems,
                maxSelectionCount: 5,
                matching: .images
            )
        }
        .onChange(of: selectedItems) { _, newItems in
            Task {
                selectedImages = []
                for item in newItems {
                    if let data = try? await item.loadTransferable(type: Data.self),
                       let uiImage = UIImage(data: data) {
                        selectedImages.append(Image(uiImage: uiImage))
                    }
                }
            }
        }
    }
}

Media Type Filtering

Filter with PHPickerFilter composites to restrict selectable media:

// Images only
PhotosPicker(selection: $items, matching: .images)

// Videos only
PhotosPicker(selection: $items, matching: .videos)

// Live Photos only
PhotosPicker(selection: $items, matching: .livePhotos)

// Screenshots only
PhotosPicker(selection: $items, matching: .screenshots)

// Images and videos combined
PhotosPicker(selection: $items, matching: .any(of: [.images, .videos]))

// Images excluding screenshots
PhotosPicker(selection: $items, matching: .all(of: [.images, .not(.screenshots)]))

Loading Selected Items with Transferable

PhotosPickerItem loads content asynchronously via loadTransferable(type:). Define a Transferable type for automatic decoding:

struct PickedImage: Transferable {
    let data: Data
    let image: Image

    static var transferRepresentation: some TransferRepresentation {
        DataRepresentation(importedContentType: .image) { data in
            guard let uiImage = UIImage(data: data) else {
                throw TransferError.importFailed
            }
            return PickedImage(data: data, image: Image(uiImage: uiImage))
        }
    }
}

enum TransferError: Error {
    case importFailed
}

// Usage
if let picked = try? await item.loadTransferable(type: PickedImage.self) {
    selectedImage = picked.image
}

Always load in a Task to avoid blocking the main thread. Handle nil returns and thrown errors -- the user may select a format that cannot be decoded.

Privacy and Permissions

Photo Library Access Levels

iOS provides two access levels for the photo library. The system automatically presents the limited-library picker when an app requests .readWrite access -- users choose which photos to share.

PhotosPicker requires no permission to browse -- it runs out-of-process and only grants access to selected items. Request explicit permission only when you need to read the full library (e.g., a custom gallery) or save photos.

Checking and Requesting Photo Library Permission

import Photos

func requestPhotoLibraryAccess() async -> PHAuthorizationStatus {
    let status = PHPhotoLibrary.authorizationStatus(for: .readWrite)

    switch status {
    case .notDetermined:
        return await PHPhotoLibrary.requestAuthorization(for: .readWrite)
    case .authorized, .limited:
        return status
    case .denied, .restricted:
        return status
    @unknown default:
        return status
    }
}

Camera Permission

Add NSCameraUsageDescription to Info.plist. Check and request access before configuring a capture session:

import AVFoundation

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

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

Handling Denied Permissions

When the user denies access, guide them to Settings. Never repeatedly prompt or hide functionality silently.

struct PermissionDeniedView: View {
    let message: String
    @Environment(\.openURL) private var openURL

    var body: some View {
        ContentUnavailableView {
            Label("Access Denied", systemImage: "lock.shield")
        } description: {
            Text(message)
        } actions: {
            Button("Open Settings") {
                if let url = URL(string: UIApplication.openSettingsURLString) {
                    openURL(url)
                }
            }
        }
    }
}

Required Info.plist Keys

Omitting a required key causes a runtime crash when the permission dialog would appear.

Camera Capture Basics

Manage camera sessions in a dedicated @Observable model. The representable view only displays the preview. See references/camera-capture.md for complete patterns.

Minimal Camera Manager

import AVFoundation

@available(iOS 17.0, *)
@Observable
@MainActor
final class CameraManager {
    let session = AVCaptureSession()
    private let photoOutput = AVCapturePhotoOutput()
    private var currentDevice: AVCaptureDevice?

    var isRunning = false
    var capturedImage: Data?

    func configure() async {
        guard await requestCameraAccess() else { return }

        session.beginConfiguration()
        session.sessionPreset = .photo

        // Add camera input
        guard let device = AVCaptureDevice.default(.builtInWideAngleCamera,
                                                    for: .video,
                                                    position: .back) else { return }
        currentDevice = device

        guard let input = try? AVCaptureDeviceInput(device: device),
              session.canAddInput(input) else { return }
        session.addInput(input)

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

        session.commitConfiguration()
    }

    func start() {
        guard !session.isRunning else { return }
        Task.detached { [session] in
            session.startRunning()
        }
        isRunning = true
    }

    func stop() {
        guard session.isRunning else { return }
        Task.detached { [session] in
            session.stopRunning()
        }
        isRunning = false
    }

    private func requestCameraAccess() async -> Bool {
        let status = AVCaptureDevice.authorizationStatus(for: .video)
        if status == .notDetermined {
            return await AVCaptureDevice.requestAccess(for: .video)
        }
        return status == .authorized
    }
}

Start and stop AVCaptureSession on a background queue. The startRunning() and stopRunning() methods are synchronous and block the calling thread.

Camera Preview in SwiftUI

Wrap AVCaptureVideoPreviewLayer in a UIViewRepresentable. Override layerClass for automatic resizing:

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) {
        if uiView.previewLayer.session !== session {
            uiView.previewLayer.session = session
        }
    }
}

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

Using the Camera in a View

struct CameraScreen: View {
    @State private var cameraManager = CameraManager()

    var body: some View {
        ZStack(alignment: .bottom) {
            CameraPreview(session: cameraManager.session)
                .ignoresSafeArea()

            Button {
                // Capture photo -- see references/camera-capture.md
            } label: {
                Circle()
                    .fill(.white)
                    .frame(width: 72, height: 72)
                    .overlay(Circle().stroke(.gray, lineWidth: 3))
            }
            .padding(.bottom)
        }
        .task {
            await cameraManager.configure()
            cameraManager.start()
        }
        .onDisappear {
            cameraManager.stop()
        }
    }
}

Always call stop() in onDisappear. A running capture session holds the camera exclusively and drains battery.

Image Loading and Display

AsyncImage for Remote Images

AsyncImage(url: imageURL) { phase in
    switch phase {
    case .empty:
        ProgressView()
    case .success(let image):
        image
            .resizable()
            .scaledToFill()
    case .failure:
        Image(systemName: "photo")
            .foregroundStyle(.secondary)
    @unknown default:
        EmptyView()
    }
}
.frame(width: 200, height: 200)
.clipShape(.rect(cornerRadius: 12))

AsyncImage does not cache images across view redraws. For production apps with many images, use a dedicated image loading library or URLCache-based caching.

Downsampling Large Images

Load full-resolution photos from the library into a display-sized CGImage to avoid memory spikes. A 48MP photo can consume over 200 MB uncompressed.

import ImageIO
import UIKit

func downsample(data: Data, to pointSize: CGSize, scale: CGFloat = UITraitCollection.current.displayScale) -> UIImage? {
    let maxDimensionInPixels = max(pointSize.width, pointSize.height) * scale

    let options: [CFString: Any] = [
        kCGImageSourceCreateThumbnailFromImageAlways: true,
        kCGImageSourceShouldCacheImmediately: true,
        kCGImageSourceCreateThumbnailWithTransform: true,
        kCGImageSourceThumbnailMaxPixelSize: maxDimensionInPixels
    ]

    guard let source = CGImageSourceCreateWithData(data as CFData, nil),
          let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else {
        return nil
    }

    return UIImage(cgImage: cgImage)
}

Use this whenever displaying user-selected photos in lists, grids, or thumbnails. Pass the raw Data from PhotosPickerItem directly to the downsampler before creating a UIImage.

Image Rendering Modes

// Original: display the image as-is with its original colors
Image("photo")
    .renderingMode(.original)

// Template: treat the image as a mask, colored by foregroundStyle
Image(systemName: "heart.fill")
    .renderingMode(.template)
    .foregroundStyle(.red)

Use .original for photos and artwork. Use .template for icons that should adopt the current tint color.

Common Mistakes

DON'T: Use UIImagePickerController for photo picking. DO: Use PhotosPicker (SwiftUI) or PHPickerViewController (UIKit). Why: UIImagePickerController is legacy API with limited functionality. PhotosPicker runs out-of-process, supports multi-selection, and requires no library permission for browsing.

DON'T: Request full photo library access when you only need the user to pick photos. DO: Use PhotosPicker which requires no permission, or request .readWrite and let the system handle limited access. Why: Full access is unnecessary for most pick-and-use workflows. The system's limited-library picker respects user privacy and still grants access to selected items.

DON'T: Load full-resolution images into memory for thumbnails. DO: Use CGImageSource with kCGImageSourceThumbnailMaxPixelSize to downsample. A 48MP image is over 200 MB uncompressed.

DON'T: Block the main thread loading PhotosPickerItem data. DO: Use async loadTransferable(type:) in a Task.

DON'T: Forget to stop AVCaptureSession when the view disappears. DO: Call session.stopRunning() in onDisappear or dismantleUIView.

DON'T: Assume camera access is granted without checking. DO: Check AVCaptureDevice.authorizationStatus(for: .video) and handle .denied/.restricted.

DON'T: Call session.startRunning() on the main thread. DO: Dispatch to a background thread with Task.detached or a dedicated serial queue. Why: startRunning() is a synchronous blocking call that can take hundreds of milliseconds while the hardware initializes.

DON'T: Create AVCaptureSession inside a UIViewRepresentable. DO: Own the session in a separate @Observable model.

Review Checklist

• [ ] PhotosPicker used instead of deprecated UIImagePickerController
• [ ] Privacy descriptions in Info.plist for camera/photo library
• [ ] Loading states handled for async image/video loading
• [ ] Large images downsampled with CGImageSource before display
• [ ] Camera session started on background thread; stopped in onDisappear
• [ ] Permission denial handled with Settings deep link
• [ ] AVCaptureSession owned by model, not created inside UIViewRepresentable
• [ ] Media asset types and picker results are Sendable across concurrency boundaries

References

• references/photokit-patterns.md — Picker patterns, media loading, HEIC handling
• references/camera-capture.md — AVCaptureSession, photo/video capture, QR scanning
• references/image-loading-caching.md — AsyncImage, caching, downsampling
• references/av-playback.md — AVPlayer, streaming, audio

AV Playback

Patterns for media playback with AVPlayer, streaming HLS content, audio session configuration, background audio, Now Playing integration, remote command handling, and Picture-in-Picture.

Contents

• AVPlayer and AVPlayerViewController Setup
• AVPlayerItem and AVAsset Loading
• Playback Controls
• Observing Player State and Time
• Streaming HLS Content
• AVAudioSession Configuration
• Background Audio Setup
• Now Playing Info Center
• MPRemoteCommandCenter
• Picture-in-Picture

AVPlayer and AVPlayerViewController Setup

AVPlayer manages playback of a single media asset. Use AVPlayerViewController (AVKit) for the system-standard playback UI with transport controls, or AVPlayerLayer for a custom player interface.

Docs: AVPlayer, AVPlayerViewController

AVPlayerViewController in SwiftUI

import SwiftUI
import AVKit

struct VideoPlayerView: View {
    let url: URL
    @State private var player: AVPlayer?

    var body: some View {
        VideoPlayer(player: player)
            .onAppear {
                player = AVPlayer(url: url)
                player?.play()
            }
            .onDisappear {
                player?.pause()
                player = nil
            }
    }
}

AVPlayerViewController in UIKit

import UIKit
import AVKit

final class VideoViewController: UIViewController {
    private var player: AVPlayer?

    func presentVideo(url: URL) {
        player = AVPlayer(url: url)
        let controller = AVPlayerViewController()
        controller.player = player
        present(controller, animated: true) {
            self.player?.play()
        }
    }
}

Custom Player with AVPlayerLayer

For full control over the player UI, embed an AVPlayerLayer:

import AVFoundation
import UIKit

final class PlayerView: UIView {
    override class var layerClass: AnyClass { AVPlayerLayer.self }

    var playerLayer: AVPlayerLayer { layer as! AVPlayerLayer }

    var player: AVPlayer? {
        get { playerLayer.player }
        set { playerLayer.player = newValue }
    }

    func configure() {
        playerLayer.videoGravity = .resizeAspect
    }
}

AVPlayerItem and AVAsset Loading

AVAsset represents the static media (duration, tracks, metadata). AVPlayerItem adds the dynamic state (current time, buffering status) needed for playback.

Docs: AVPlayerItem, AVAsset

import AVFoundation

// Local file
let localURL = Bundle.main.url(forResource: "intro", withExtension: "mp4")!
let localItem = AVPlayerItem(url: localURL)

// Remote file
let remoteURL = URL(string: "https://example.com/video.mp4")!
let remoteItem = AVPlayerItem(url: remoteURL)

// From an existing AVAsset (for more control)
let asset = AVURLAsset(url: remoteURL, options: [
    AVURLAssetPreferPreciseDurationAndTimingKey: true
])

// Load properties asynchronously before playback (iOS 15+)
let duration = try await asset.load(.duration)
let tracks = try await asset.load(.tracks)
let isPlayable = try await asset.load(.isPlayable)

let item = AVPlayerItem(asset: asset)
let player = AVPlayer(playerItem: item)

Replacing the Current Item

Reuse a single AVPlayer and swap items:

let nextItem = AVPlayerItem(url: nextVideoURL)
player.replaceCurrentItem(with: nextItem)
player.play()

Queue Playback with AVQueuePlayer

let items = videoURLs.map { AVPlayerItem(url: $0) }
let queuePlayer = AVQueuePlayer(items: items)
queuePlayer.play()
// Automatically advances to the next item

Playback Controls

// Play
player.play()

// Pause
player.pause()

// Set playback rate (1.0 = normal, 2.0 = 2x, 0.5 = half speed)
player.rate = 1.5

// Seek to a specific time
let targetTime = CMTime(seconds: 30, preferredTimescale: 600)
await player.seek(to: targetTime)

// Seek with tolerance (for precise seeking, e.g., scrubbing)
await player.seek(
    to: targetTime,
    toleranceBefore: .zero,
    toleranceAfter: .zero
)

// Seek to a percentage of duration
func seekToPercentage(_ percentage: Double) async {
    guard let duration = player.currentItem?.duration,
          duration.isNumeric else { return }
    let targetSeconds = duration.seconds * percentage
    let target = CMTime(seconds: targetSeconds, preferredTimescale: 600)
    await player.seek(to: target)
}

Observing Player State and Time

Periodic Time Observer

Use addPeriodicTimeObserver to update UI elements like a progress bar:

import AVFoundation

@Observable
@MainActor
final class PlayerManager {
    let player = AVPlayer()
    var currentTime: Double = 0
    var duration: Double = 0
    var isPlaying = false

    private var timeObserver: Any?

    func startObserving() {
        // Fire every 0.5 seconds on the main queue
        let interval = CMTime(seconds: 0.5, preferredTimescale: 600)
        timeObserver = player.addPeriodicTimeObserver(
            forInterval: interval,
            queue: .main
        ) { [weak self] time in
            guard let self else { return }
            self.currentTime = time.seconds
            self.duration = self.player.currentItem?.duration.seconds ?? 0
            self.isPlaying = self.player.timeControlStatus == .playing
        }
    }

    func stopObserving() {
        if let observer = timeObserver {
            player.removeTimeObserver(observer)
            timeObserver = nil
        }
    }

    deinit {
        if let observer = timeObserver {
            player.removeTimeObserver(observer)
        }
    }
}

Observing Player Status with KVO

Check player and item readiness before playing:

import AVFoundation
import Combine

// Using Combine
var cancellables = Set<AnyCancellable>()

player.publisher(for: \.status)
    .sink { status in
        switch status {
        case .readyToPlay:
            print("Ready to play")
        case .failed:
            print("Failed: \(player.error?.localizedDescription ?? "")")
        case .unknown:
            print("Status unknown")
        @unknown default:
            break
        }
    }
    .store(in: &cancellables)

// Observe buffering state
player.publisher(for: \.timeControlStatus)
    .sink { status in
        switch status {
        case .playing: print("Playing")
        case .paused: print("Paused")
        case .waitingToPlayAtSpecifiedRate:
            print("Buffering: \(player.reasonForWaitingToPlay?.rawValue ?? "")")
        @unknown default: break
        }
    }
    .store(in: &cancellables)

Detecting Playback End

NotificationCenter.default.addObserver(
    forName: .AVPlayerItemDidPlayToEndTime,
    object: player.currentItem,
    queue: .main
) { _ in
    // Playback finished -- loop, show replay button, or advance
    player.seek(to: .zero)  // Loop
}

Streaming HLS Content

HTTP Live Streaming (HLS) works directly with AVPlayer. Pass the .m3u8 URL and AVFoundation handles adaptive bitrate selection, buffering, and failover.

let hlsURL = URL(string: "https://example.com/stream/master.m3u8")!
let player = AVPlayer(url: hlsURL)
player.play()

// AVPlayer automatically selects the best variant based on:
// - Network bandwidth
// - Device capabilities
// - Display resolution

Preferred Bitrate and Resolution

let item = AVPlayerItem(url: hlsURL)

// Limit maximum resolution (e.g., for cellular)
item.preferredMaximumResolution = CGSize(width: 1280, height: 720)

// Limit peak bitrate (bits per second)
item.preferredPeakBitRate = 2_000_000  // 2 Mbps

// For forward buffering duration
item.preferredForwardBufferDuration = 5  // seconds; 0 = system default

AVAudioSession Configuration

Configure AVAudioSession to tell the system how your app intends to use audio. This affects audio routing, mixing behavior, and background playback.

Docs: AVAudioSession, AVAudioSession.Category

Categories and Modes

import AVFAudio

func configureAudioSession(forPlayback: Bool = true) throws {
    let session = AVAudioSession.sharedInstance()

    if forPlayback {
        // Media playback: audio continues with silent switch, supports background
        try session.setCategory(
            .playback,
            mode: .default,
            options: []
        )
    } else {
        // Mix with other apps (e.g., game sounds over user's music)
        try session.setCategory(
            .ambient,
            mode: .default,
            options: [.mixWithOthers]
        )
    }

    try session.setActive(true)
}

// For video calls
try AVAudioSession.sharedInstance().setCategory(
    .playAndRecord,
    mode: .videoChat,
    options: [.defaultToSpeaker, .allowBluetooth]
)

Handling Audio Interruptions

NotificationCenter.default.addObserver(
    forName: AVAudioSession.interruptionNotification,
    object: AVAudioSession.sharedInstance(),
    queue: .main
) { notification in
    guard let info = notification.userInfo,
          let typeValue = info[AVAudioSessionInterruptionTypeKey] as? UInt,
          let type = AVAudioSession.InterruptionType(rawValue: typeValue) else {
        return
    }

    switch type {
    case .began:
        // Pause playback -- system has interrupted audio
        player.pause()
    case .ended:
        let options = info[AVAudioSessionInterruptionOptionKey] as? UInt ?? 0
        if AVAudioSession.InterruptionOptions(rawValue: options).contains(.shouldResume) {
            player.play()
        }
    @unknown default:
        break
    }
}

Handling Route Changes

NotificationCenter.default.addObserver(
    forName: AVAudioSession.routeChangeNotification,
    object: AVAudioSession.sharedInstance(),
    queue: .main
) { notification in
    guard let info = notification.userInfo,
          let reasonValue = info[AVAudioSessionRouteChangeReasonKey] as? UInt,
          let reason = AVAudioSession.RouteChangeReason(rawValue: reasonValue) else {
        return
    }

    if reason == .oldDeviceUnavailable {
        // Headphones unplugged -- pause playback (Apple HIG requirement)
        player.pause()
    }
}

Background Audio Setup

To play audio when the app is in the background, two things are required:

1. Enable the audio background mode in your app's capabilities. 2. Configure AVAudioSession with the .playback category.

Info.plist Configuration

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

Or enable "Audio, AirPlay, and Picture in Picture" in Xcode's Signing & Capabilities tab.

Activating Background Audio

import AVFAudio

func enableBackgroundAudio() throws {
    let session = AVAudioSession.sharedInstance()
    try session.setCategory(.playback, mode: .default)
    try session.setActive(true)
}

Rules:

• Call setCategory before setActive.
• The .playback category is required; .ambient and .soloAmbient do not

support background audio.

• Deactivate the session when playback ends to let other apps use audio:

func deactivateAudioSession() {
    try? AVAudioSession.sharedInstance().setActive(
        false,
        options: .notifyOthersOnDeactivation
    )
}

Now Playing Info Center

Update MPNowPlayingInfoCenter so the system displays track information on the lock screen, Control Center, and connected accessories (CarPlay, AirPods).

Docs: MPNowPlayingInfoCenter

import MediaPlayer

func updateNowPlayingInfo(
    title: String,
    artist: String,
    albumTitle: String? = nil,
    duration: TimeInterval,
    currentTime: TimeInterval,
    artwork: UIImage? = nil
) {
    var info: [String: Any] = [
        MPMediaItemPropertyTitle: title,
        MPMediaItemPropertyArtist: artist,
        MPMediaItemPropertyPlaybackDuration: duration,
        MPNowPlayingInfoPropertyElapsedPlaybackTime: currentTime,
        MPNowPlayingInfoPropertyPlaybackRate: 1.0,
        MPNowPlayingInfoPropertyMediaType: MPNowPlayingInfoMediaType.audio.rawValue
    ]

    if let albumTitle {
        info[MPMediaItemPropertyAlbumTitle] = albumTitle
    }

    if let artwork {
        info[MPMediaItemPropertyArtwork] = MPMediaItemArtwork(
            boundsSize: artwork.size
        ) { _ in artwork }
    }

    MPNowPlayingInfoCenter.default().nowPlayingInfo = info
}

// Update elapsed time during playback
func updateElapsedTime(_ seconds: TimeInterval, rate: Float = 1.0) {
    var info = MPNowPlayingInfoCenter.default().nowPlayingInfo ?? [:]
    info[MPNowPlayingInfoPropertyElapsedPlaybackTime] = seconds
    info[MPNowPlayingInfoPropertyPlaybackRate] = rate
    MPNowPlayingInfoCenter.default().nowPlayingInfo = info
}

MPRemoteCommandCenter

Register handlers for lock screen, Control Center, and accessory controls (play, pause, skip, seek). Without these, the system controls won't work.

Docs: MPRemoteCommandCenter

import MediaPlayer

func setupRemoteCommands(player: AVPlayer) {
    let commandCenter = MPRemoteCommandCenter.shared()

    // Play
    commandCenter.playCommand.isEnabled = true
    commandCenter.playCommand.addTarget { _ in
        player.play()
        return .success
    }

    // Pause
    commandCenter.pauseCommand.isEnabled = true
    commandCenter.pauseCommand.addTarget { _ in
        player.pause()
        return .success
    }

    // Toggle play/pause (headphone button, etc.)
    commandCenter.togglePlayPauseCommand.isEnabled = true
    commandCenter.togglePlayPauseCommand.addTarget { _ in
        if player.timeControlStatus == .playing {
            player.pause()
        } else {
            player.play()
        }
        return .success
    }

    // Skip forward (e.g., 15 seconds)
    commandCenter.skipForwardCommand.isEnabled = true
    commandCenter.skipForwardCommand.preferredIntervals = [15]
    commandCenter.skipForwardCommand.addTarget { event in
        guard let skipEvent = event as? MPSkipIntervalCommandEvent else {
            return .commandFailed
        }
        let currentTime = player.currentTime().seconds
        let target = CMTime(
            seconds: currentTime + skipEvent.interval,
            preferredTimescale: 600
        )
        player.seek(to: target)
        return .success
    }

    // Skip backward (e.g., 15 seconds)
    commandCenter.skipBackwardCommand.isEnabled = true
    commandCenter.skipBackwardCommand.preferredIntervals = [15]
    commandCenter.skipBackwardCommand.addTarget { event in
        guard let skipEvent = event as? MPSkipIntervalCommandEvent else {
            return .commandFailed
        }
        let currentTime = player.currentTime().seconds
        let target = CMTime(
            seconds: max(0, currentTime - skipEvent.interval),
            preferredTimescale: 600
        )
        player.seek(to: target)
        return .success
    }

    // Scrubbing (seek bar on lock screen)
    commandCenter.changePlaybackPositionCommand.isEnabled = true
    commandCenter.changePlaybackPositionCommand.addTarget { event in
        guard let positionEvent = event as? MPChangePlaybackPositionCommandEvent else {
            return .commandFailed
        }
        let target = CMTime(
            seconds: positionEvent.positionTime,
            preferredTimescale: 600
        )
        player.seek(to: target)
        return .success
    }

    // Disable unsupported commands to remove them from UI
    commandCenter.nextTrackCommand.isEnabled = false
    commandCenter.previousTrackCommand.isEnabled = false
}

Cleanup

func teardownRemoteCommands() {
    let commandCenter = MPRemoteCommandCenter.shared()
    commandCenter.playCommand.removeTarget(nil)
    commandCenter.pauseCommand.removeTarget(nil)
    commandCenter.togglePlayPauseCommand.removeTarget(nil)
    commandCenter.skipForwardCommand.removeTarget(nil)
    commandCenter.skipBackwardCommand.removeTarget(nil)
    commandCenter.changePlaybackPositionCommand.removeTarget(nil)
}

Picture-in-Picture

AVPictureInPictureController enables floating video playback that continues when the user navigates away. Requires the audio background mode.

Docs: AVPictureInPictureController, Adopting Picture in Picture in a Custom Player

With AVPlayerViewController (Automatic)

AVPlayerViewController supports PiP automatically when the background audio capability is enabled. No extra code needed.

let controller = AVPlayerViewController()
controller.player = player
controller.allowsPictureInPicturePlayback = true  // true by default

With a Custom Player

import AVKit

@Observable
@MainActor
final class PiPManager: NSObject, AVPictureInPictureControllerDelegate {
    private var pipController: AVPictureInPictureController?
    var isPiPActive = false
    var isPiPPossible = false

    func setup(playerLayer: AVPlayerLayer) {
        guard AVPictureInPictureController.isPictureInPictureSupported() else {
            return
        }

        pipController = AVPictureInPictureController(playerLayer: playerLayer)
        pipController?.delegate = self

        // Auto-start PiP when app goes to background
        pipController?.canStartPictureInPictureAutomaticallyFromInline = true
    }

    func togglePiP() {
        guard let pipController else { return }
        if pipController.isPictureInPictureActive {
            pipController.stopPictureInPicture()
        } else {
            pipController.startPictureInPicture()
        }
    }

    // MARK: - AVPictureInPictureControllerDelegate

    nonisolated func pictureInPictureControllerWillStartPictureInPicture(
        _ controller: AVPictureInPictureController
    ) {
        Task { @MainActor in isPiPActive = true }
    }

    nonisolated func pictureInPictureControllerDidStopPictureInPicture(
        _ controller: AVPictureInPictureController
    ) {
        Task { @MainActor in isPiPActive = false }
    }

    nonisolated func pictureInPictureController(
        _ controller: AVPictureInPictureController,
        restoreUserInterfaceForPictureInPictureStopWithCompletionHandler
        completionHandler: @escaping (Bool) -> Void
    ) {
        // Restore your player UI here, then call the handler
        Task { @MainActor in
            // Navigate back to the player view
            completionHandler(true)
        }
    }
}

PiP Requirements Checklist

• [ ] UIBackgroundModes includes audio in Info.plist
• [ ] AVAudioSession category set to .playback
• [ ] Check AVPictureInPictureController.isPictureInPictureSupported() before setup
• [ ] Implement restoreUserInterfaceForPictureInPictureStop delegate method
• [ ] Call completion handler in the restore delegate method (failure to call causes hangs)

Camera Capture

Complete patterns for AVCaptureSession setup, photo capture, video recording, and camera features in SwiftUI. All patterns use a dedicated @Observable model that owns the session; the SwiftUI view only displays the preview and triggers actions.

---

Contents

• 1. Complete Camera Manager with Photo Capture
• 2. Camera Preview (UIViewRepresentable)
• 3. Complete Camera Screen in SwiftUI
• 4. Video Recording
• 5. Flash and Torch Control
• 6. Focus and Exposure
• 7. Barcode and QR Code Scanning
• 8. Camera Preview Orientation
• 9. Dual Camera and Device Discovery
• 10. Restricting Scan Region

1. Complete Camera Manager with Photo Capture

A full-featured camera model with photo capture using the delegate pattern.

import AVFoundation
import UIKit

@available(iOS 17.0, *)
@Observable
@MainActor
final class CameraManager: NSObject {
    let session = AVCaptureSession()

    private let photoOutput = AVCapturePhotoOutput()
    private var currentInput: AVCaptureDeviceInput?
    private var photoContinuation: CheckedContinuation<Data?, Never>?

    var isRunning = false
    var cameraPosition: AVCaptureDevice.Position = .back
    var flashMode: AVCaptureDevice.FlashMode = .auto
    var lastCapturedPhoto: Data?
    var error: String?

    // MARK: - Configuration

    func configure() async {
        guard await requestAccess() else {
            error = "Camera access denied"
            return
        }

        session.beginConfiguration()
        session.sessionPreset = .photo

        // Add camera input
        guard let device = cameraDevice(for: cameraPosition),
              let input = try? AVCaptureDeviceInput(device: device),
              session.canAddInput(input) else {
            error = "Failed to configure camera input"
            session.commitConfiguration()
            return
        }
        session.addInput(input)
        currentInput = input

        // Add photo output
        guard session.canAddOutput(photoOutput) else {
            error = "Failed to configure photo output"
            session.commitConfiguration()
            return
        }
        session.addOutput(photoOutput)

        // Enable maximum quality (iOS 16+)
        if let maxDimensions = photoOutput.maxPhotoDimensions(for: .photo) {
            photoOutput.maxPhotoDimensions = maxDimensions
        }
        photoOutput.maxPhotoQualityPrioritization = .quality

        session.commitConfiguration()
    }

    // MARK: - Session Control

    func start() {
        guard !session.isRunning else { return }
        Task.detached { [session] in
            session.startRunning()
        }
        isRunning = true
    }

    func stop() {
        guard session.isRunning else { return }
        Task.detached { [session] in
            session.stopRunning()
        }
        isRunning = false
    }

    // MARK: - Photo Capture

    func capturePhoto() async -> Data? {
        let settings = AVCapturePhotoSettings()
        settings.flashMode = flashMode

        if photoOutput.availablePhotoCodecTypes.contains(.hevc) {
            settings.photoQualityPrioritization = .quality
        }

        return await withCheckedContinuation { continuation in
            photoContinuation = continuation
            photoOutput.capturePhoto(with: settings, delegate: self)
        }
    }

    // MARK: - Camera Switching

    func switchCamera() {
        let newPosition: AVCaptureDevice.Position = (cameraPosition == .back) ? .front : .back

        guard let device = cameraDevice(for: newPosition),
              let newInput = try? AVCaptureDeviceInput(device: device) else { return }

        session.beginConfiguration()
        if let currentInput {
            session.removeInput(currentInput)
        }
        if session.canAddInput(newInput) {
            session.addInput(newInput)
            currentInput = newInput
            cameraPosition = newPosition
        }
        session.commitConfiguration()
    }

    // MARK: - Helpers

    private func cameraDevice(for position: AVCaptureDevice.Position) -> AVCaptureDevice? {
        AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: position)
    }

    private func requestAccess() async -> Bool {
        let status = AVCaptureDevice.authorizationStatus(for: .video)
        if status == .notDetermined {
            return await AVCaptureDevice.requestAccess(for: .video)
        }
        return status == .authorized
    }
}

// MARK: - AVCapturePhotoCaptureDelegate

@available(iOS 17.0, *)
extension CameraManager: AVCapturePhotoCaptureDelegate {
    nonisolated func photoOutput(
        _ output: AVCapturePhotoOutput,
        didFinishProcessingPhoto photo: AVCapturePhoto,
        error: Error?
    ) {
        let data = photo.fileDataRepresentation()
        Task { @MainActor in
            lastCapturedPhoto = data
            photoContinuation?.resume(returning: data)
            photoContinuation = nil
        }
    }
}

The capturePhoto() method bridges the delegate-based API to async/await using CheckedContinuation. Store only one continuation at a time -- overlapping captures are not supported.

---

2. Camera Preview (UIViewRepresentable)

import SwiftUI
import AVFoundation

struct CameraPreview: UIViewRepresentable {
    let session: AVCaptureSession

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

    func updateUIView(_ uiView: CameraPreviewView, context: Context) {
        if uiView.previewLayer.session !== session {
            uiView.previewLayer.session = session
        }
    }
}

/// Custom UIView that uses AVCaptureVideoPreviewLayer as its backing layer.
/// Overriding layerClass ensures the preview layer resizes automatically with the view.
final class CameraPreviewView: UIView {
    override class var layerClass: AnyClass { AVCaptureVideoPreviewLayer.self }

    var previewLayer: AVCaptureVideoPreviewLayer {
        layer as! AVCaptureVideoPreviewLayer
    }
}

Never add AVCaptureVideoPreviewLayer as a sublayer manually. Using layerClass avoids manual frame management in layoutSubviews.

---

3. Complete Camera Screen in SwiftUI

import SwiftUI

@available(iOS 17.0, *)
struct CameraScreen: View {
    @State private var camera = CameraManager()
    @State private var showCapturedPhoto = false

    var body: some View {
        ZStack {
            CameraPreview(session: camera.session)
                .ignoresSafeArea()

            VStack {
                // Top controls
                HStack {
                    Button {
                        camera.switchCamera()
                    } label: {
                        Image(systemName: "camera.rotate")
                            .font(.title2)
                            .padding()
                            .background(.ultraThinMaterial, in: Circle())
                    }

                    Spacer()

                    // Flash toggle
                    Button {
                        camera.flashMode = (camera.flashMode == .off) ? .auto : .off
                    } label: {
                        Image(systemName: camera.flashMode == .off
                              ? "bolt.slash.fill" : "bolt.fill")
                            .font(.title2)
                            .padding()
                            .background(.ultraThinMaterial, in: Circle())
                    }
                }
                .padding(.horizontal)

                Spacer()

                // Bottom controls
                HStack {
                    // Thumbnail of last capture
                    if let data = camera.lastCapturedPhoto,
                       let uiImage = UIImage(data: data) {
                        Button { showCapturedPhoto = true } label: {
                            Image(uiImage: uiImage)
                                .resizable()
                                .scaledToFill()
                                .frame(width: 50, height: 50)
                                .clipShape(.rect(cornerRadius: 8))
                        }
                    } else {
                        Color.clear.frame(width: 50, height: 50)
                    }

                    Spacer()

                    // Shutter button
                    Button {
                        Task { _ = await camera.capturePhoto() }
                    } label: {
                        ZStack {
                            Circle().fill(.white).frame(width: 72, height: 72)
                            Circle().stroke(.gray, lineWidth: 3).frame(width: 78, height: 78)
                        }
                    }

                    Spacer()

                    Color.clear.frame(width: 50, height: 50)
                }
                .padding(.horizontal)
                .padding(.bottom)
            }
        }
        .task {
            await camera.configure()
            camera.start()
        }
        .onDisappear {
            camera.stop()
        }
        .sheet(isPresented: $showCapturedPhoto) {
            if let data = camera.lastCapturedPhoto,
               let uiImage = UIImage(data: data) {
                Image(uiImage: uiImage)
                    .resizable()
                    .scaledToFit()
            }
        }
    }
}

---

4. Video Recording

Add AVCaptureMovieFileOutput for video capture. Video recording requires NSMicrophoneUsageDescription in Info.plist for audio.

import AVFoundation

@available(iOS 17.0, *)
@Observable
@MainActor
final class VideoRecorder: NSObject {
    let session = AVCaptureSession()

    private let movieOutput = AVCaptureMovieFileOutput()
    private var videoContinuation: CheckedContinuation<URL?, Never>?

    var isRecording = false
    var recordedVideoURL: URL?
    var error: String?

    func configure() async {
        guard await requestAccess() else {
            error = "Camera access denied"
            return
        }

        session.beginConfiguration()
        session.sessionPreset = .high

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

        // Audio input
        if let audioDevice = AVCaptureDevice.default(for: .audio),
           let audioInput = try? AVCaptureDeviceInput(device: audioDevice),
           session.canAddInput(audioInput) {
            session.addInput(audioInput)
        }

        // Movie output
        guard session.canAddOutput(movieOutput) else {
            session.commitConfiguration()
            return
        }
        session.addOutput(movieOutput)

        session.commitConfiguration()
    }

    func startRecording() {
        guard !isRecording else { return }

        let outputURL = FileManager.default.temporaryDirectory
            .appendingPathComponent(UUID().uuidString)
            .appendingPathExtension("mov")

        movieOutput.startRecording(to: outputURL, recordingDelegate: self)
        isRecording = true
    }

    func stopRecording() async -> URL? {
        guard isRecording else { return nil }

        return await withCheckedContinuation { continuation in
            videoContinuation = continuation
            movieOutput.stopRecording()
        }
    }

    func start() {
        Task.detached { [session] in session.startRunning() }
    }

    func stop() {
        Task.detached { [session] in session.stopRunning() }
    }

    private func requestAccess() async -> Bool {
        let videoStatus = AVCaptureDevice.authorizationStatus(for: .video)
        let videoGranted: Bool
        if videoStatus == .notDetermined {
            videoGranted = await AVCaptureDevice.requestAccess(for: .video)
        } else {
            videoGranted = videoStatus == .authorized
        }

        // Also request audio for video recording
        let audioStatus = AVCaptureDevice.authorizationStatus(for: .audio)
        if audioStatus == .notDetermined {
            _ = await AVCaptureDevice.requestAccess(for: .audio)
        }

        return videoGranted
    }
}

@available(iOS 17.0, *)
extension VideoRecorder: AVCaptureFileOutputRecordingDelegate {
    nonisolated func fileOutput(
        _ output: AVCaptureFileOutput,
        didFinishRecordingTo outputFileURL: URL,
        from connections: [AVCaptureConnection],
        error: Error?
    ) {
        Task { @MainActor in
            isRecording = false
            recordedVideoURL = error == nil ? outputFileURL : nil
            videoContinuation?.resume(returning: error == nil ? outputFileURL : nil)
            videoContinuation = nil
        }
    }
}

Clean up temporary video files when they are no longer needed. Recorded videos can be large and the temporary directory is not automatically cleaned during the app's lifetime.

---

5. Flash and Torch Control

Flash applies to photo capture settings. Torch provides continuous illumination for video or preview.

import AVFoundation

func toggleTorch(on device: AVCaptureDevice, enabled: Bool) throws {
    guard device.hasTorch, device.isTorchAvailable else { return }

    try device.lockForConfiguration()
    device.torchMode = enabled ? .on : .off
    if enabled {
        try device.setTorchModeOn(level: AVCaptureDevice.maxAvailableTorchLevel)
    }
    device.unlockForConfiguration()
}

Always wrap device configuration in lockForConfiguration() / unlockForConfiguration(). Multiple clients may attempt to configure the device simultaneously.

---

6. Focus and Exposure

Implement tap-to-focus by converting a SwiftUI tap location to the camera coordinate system.

import AVFoundation

func setFocusAndExposure(
    at point: CGPoint,
    in previewLayer: AVCaptureVideoPreviewLayer,
    device: AVCaptureDevice
) throws {
    let devicePoint = previewLayer.captureDevicePointConverted(fromLayerPoint: point)

    try device.lockForConfiguration()

    if device.isFocusPointOfInterestSupported {
        device.focusPointOfInterest = devicePoint
        device.focusMode = .autoFocus
    }

    if device.isExposurePointOfInterestSupported {
        device.exposurePointOfInterest = devicePoint
        device.exposureMode = .autoExpose
    }

    device.unlockForConfiguration()
}

Integrating Tap-to-Focus in SwiftUI

struct FocusableCameraPreview: UIViewRepresentable {
    let session: AVCaptureSession
    var onTapToFocus: ((CGPoint, AVCaptureVideoPreviewLayer) -> Void)?

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

        let tap = UITapGestureRecognizer(
            target: context.coordinator,
            action: #selector(Coordinator.handleTap(_:))
        )
        view.addGestureRecognizer(tap)

        return view
    }

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

    func makeCoordinator() -> Coordinator { Coordinator(self) }

    final class Coordinator: NSObject {
        var parent: FocusableCameraPreview

        init(_ parent: FocusableCameraPreview) { self.parent = parent }

        @objc func handleTap(_ gesture: UITapGestureRecognizer) {
            guard let view = gesture.view as? CameraPreviewView else { return }
            let point = gesture.location(in: view)
            parent.onTapToFocus?(point, view.previewLayer)
        }
    }
}

---

7. Barcode and QR Code Scanning

Use AVCaptureMetadataOutput to detect barcodes and QR codes from the camera feed.

import AVFoundation

@available(iOS 17.0, *)
@Observable
@MainActor
final class QRCodeScanner: NSObject {
    let session = AVCaptureSession()

    private let metadataOutput = AVCaptureMetadataOutput()

    var scannedCode: String?
    var isScanning = false

    func configure() async {
        guard await requestAccess() else { return }

        session.beginConfiguration()

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

        guard session.canAddOutput(metadataOutput) else {
            session.commitConfiguration()
            return
        }
        session.addOutput(metadataOutput)

        // Set metadata types AFTER adding to session -- available types depend on session config
        metadataOutput.metadataObjectTypes = [.qr, .ean8, .ean13, .code128, .code39]
        metadataOutput.setMetadataObjectsDelegate(self, queue: .main)

        session.commitConfiguration()
    }

    func start() {
        scannedCode = nil
        isScanning = true
        Task.detached { [session] in session.startRunning() }
    }

    func stop() {
        isScanning = false
        Task.detached { [session] in session.stopRunning() }
    }

    private func requestAccess() async -> Bool {
        let status = AVCaptureDevice.authorizationStatus(for: .video)
        if status == .notDetermined {
            return await AVCaptureDevice.requestAccess(for: .video)
        }
        return status == .authorized
    }
}

@available(iOS 17.0, *)
extension QRCodeScanner: AVCaptureMetadataOutputObjectsDelegate {
    nonisolated func metadataOutput(
        _ output: AVCaptureMetadataOutput,
        didOutput metadataObjects: [AVMetadataObject],
        from connection: AVCaptureConnection
    ) {
        guard let object = metadataObjects.first as? AVMetadataMachineReadableCodeObject,
              let value = object.stringValue else { return }

        Task { @MainActor in
            scannedCode = value
            stop()
        }
    }
}

Scanner View

@available(iOS 17.0, *)
struct QRScannerView: View {
    @State private var scanner = QRCodeScanner()

    var body: some View {
        ZStack {
            CameraPreview(session: scanner.session)
                .ignoresSafeArea()

            // Scanning overlay
            RoundedRectangle(cornerRadius: 12)
                .stroke(.white, lineWidth: 2)
                .frame(width: 250, height: 250)

            if let code = scanner.scannedCode {
                VStack {
                    Spacer()
                    Text(code)
                        .font(.headline)
                        .padding()
                        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 12))
                        .padding(.bottom)
                }
            }
        }
        .task {
            await scanner.configure()
            scanner.start()
        }
        .onDisappear {
            scanner.stop()
        }
    }
}

Set metadataObjectTypes after adding the output to the session. Setting types before causes a runtime crash because the available types are not yet determined.

---

8. Camera Preview Orientation

Handle device rotation so the preview and captured photos have correct orientation.

Preview Layer Rotation

import AVFoundation
import UIKit

func updatePreviewOrientation(
    _ previewLayer: AVCaptureVideoPreviewLayer,
    for interfaceOrientation: UIInterfaceOrientation
) {
    guard let connection = previewLayer.connection else { return }

    // iOS 17+: use videoRotationAngle
    if #available(iOS 17.0, *) {
        let angle: CGFloat
        switch interfaceOrientation {
        case .portrait: angle = 90
        case .portraitUpsideDown: angle = 270
        case .landscapeLeft: angle = 180
        case .landscapeRight: angle = 0
        default: angle = 90
        }
        if connection.isVideoRotationAngleSupported(angle) {
            connection.videoRotationAngle = angle
        }
    }
}

Photo Output Orientation

Set the rotation angle on the photo output connection before each capture to ensure the captured image matches the device orientation:

func capturePhotoWithOrientation() {
    if let connection = photoOutput.connection(with: .video) {
        // iOS 17+
        if #available(iOS 17.0, *) {
            let angle = currentVideoRotationAngle()
            if connection.isVideoRotationAngleSupported(angle) {
                connection.videoRotationAngle = angle
            }
        }
    }

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

private func currentVideoRotationAngle() -> CGFloat {
    guard let scene = UIApplication.shared.connectedScenes.first as? UIWindowScene else {
        return 90
    }
    switch scene.interfaceOrientation {
    case .portrait: return 90
    case .portraitUpsideDown: return 270
    case .landscapeLeft: return 180
    case .landscapeRight: return 0
    default: return 90
    }
}

Use videoRotationAngle (iOS 17+) instead of the deprecated videoOrientation property. The angle is measured in degrees clockwise from landscape-right (the natural sensor orientation).

---

9. Dual Camera and Device Discovery

Select specific camera hardware using AVCaptureDevice.DiscoverySession.

import AVFoundation

func availableCameras() -> [AVCaptureDevice] {
    let discoverySession = AVCaptureDevice.DiscoverySession(
        deviceTypes: [
            .builtInWideAngleCamera,
            .builtInUltraWideCamera,
            .builtInTelephotoCamera,
            .builtInDualCamera,
            .builtInTripleCamera
        ],
        mediaType: .video,
        position: .unspecified
    )
    return discoverySession.devices
}

func preferredBackCamera() -> AVCaptureDevice? {
    // Prefer triple > dual > wide angle
    let session = AVCaptureDevice.DiscoverySession(
        deviceTypes: [.builtInTripleCamera, .builtInDualCamera, .builtInWideAngleCamera],
        mediaType: .video,
        position: .back
    )
    return session.devices.first
}

---

10. Restricting Scan Region

Limit the metadata detection area to improve performance and UX:

// Restrict detection to center 60% of the preview
metadataOutput.rectOfInterest = CGRect(x: 0.2, y: 0.2, width: 0.6, height: 0.6)

Note that rectOfInterest uses the camera coordinate system (landscape, origin top-left). Convert from preview coordinates using previewLayer.metadataOutputRectConverted(fromLayerRect:).

Image Loading and Caching Patterns

Complete patterns for efficient image handling in iOS apps, from basic AsyncImage usage through production-ready caching and loading pipelines. All patterns use modern Swift async/await and target iOS 26 with Swift 6.3, backward-compatible to iOS 16 unless noted.

Contents

• AsyncImage Patterns
• NSCache-Based In-Memory Cache
• URLCache-Based Disk Caching
• Image Downsampling with CGImageSource
• Image Prefetching for Lists and Grids
• HEIF/HEIC Handling
• Compression Before Upload
• Memory Budget Management
• Complete Image Loading Pipeline

AsyncImage Patterns

AsyncImage (iOS 15+) provides built-in async image loading from a URL. Suitable for simple cases but has significant limitations for production use.

Basic Usage

AsyncImage(url: URL(string: "https://example.com/photo.jpg"))

Phase Handling

AsyncImage(url: imageURL) { phase in
    switch phase {
    case .empty:
        ProgressView()
            .frame(width: 200, height: 200)
    case .success(let image):
        image
            .resizable()
            .aspectRatio(contentMode: .fill)
            .frame(width: 200, height: 200)
            .clipped()
    case .failure:
        Image(systemName: "photo")
            .font(.largeTitle)
            .foregroundStyle(.secondary)
            .frame(width: 200, height: 200)
    @unknown default:
        EmptyView()
    }
}

Custom Transition

AsyncImage(url: imageURL, transaction: Transaction(animation: .easeIn(duration: 0.3))) { phase in
    switch phase {
    case .success(let image):
        image
            .resizable()
            .aspectRatio(contentMode: .fill)
            .transition(.opacity)
    default:
        Color.secondary.opacity(0.2)
    }
}
.frame(width: 200, height: 200)
.clipShape(.rect(cornerRadius: 12))

Limitations

AsyncImage has several shortcomings for production apps:

• No caching across redraws: images re-download when the view is recreated.
• No prefetching: cannot load images ahead of scroll position.
• No custom URLSession: uses the shared session with no cache policy control.
• No access to raw data: cannot process, downsample, or persist the image data.
• No cancellation control: tied entirely to the view lifecycle.

For anything beyond simple, low-volume image display, use a custom loading pipeline.

---

NSCache-Based In-Memory Cache

An actor-isolated in-memory image cache backed by NSCache. Thread-safe and automatically evicts entries under memory pressure.

import UIKit

actor ImageCache {
    static let shared = ImageCache()

    private let cache = NSCache<NSString, UIImage>()
    private var inFlightTasks: [URL: Task<UIImage?, Never>] = [:]

    init(countLimit: Int = 100, totalCostLimit: Int = 50 * 1024 * 1024) {
        cache.countLimit = countLimit
        cache.totalCostLimit = totalCostLimit  // 50 MB default
    }

    func image(for url: URL) -> UIImage? {
        cache.object(forKey: url.absoluteString as NSString)
    }

    func store(_ image: UIImage, for url: URL) {
        let cost = image.jpegData(compressionQuality: 1.0)?.count ?? 0
        cache.setObject(image, forKey: url.absoluteString as NSString, cost: cost)
    }

    func removeImage(for url: URL) {
        cache.removeObject(forKey: url.absoluteString as NSString)
    }

    func removeAll() {
        cache.removeAllObjects()
        inFlightTasks.removeAll()
    }

    /// Fetch an image with request coalescing. Multiple callers for the same URL
    /// share a single network request.
    func fetch(from url: URL, session: URLSession = .shared) async -> UIImage? {
        // Return cached image immediately
        if let cached = image(for: url) {
            return cached
        }

        // Coalesce duplicate in-flight requests
        if let existingTask = inFlightTasks[url] {
            return await existingTask.value
        }

        let task = Task<UIImage?, Never> {
            defer { inFlightTasks[url] = nil }

            guard let (data, response) = try? await session.data(from: url),
                  let httpResponse = response as? HTTPURLResponse,
                  httpResponse.statusCode == 200,
                  let image = UIImage(data: data) else {
                return nil
            }

            store(image, for: url)
            return image
        }

        inFlightTasks[url] = task
        return await task.value
    }
}

Usage in SwiftUI

struct CachedImageView: View {
    let url: URL
    @State private var image: UIImage?

    var body: some View {
        Group {
            if let image {
                Image(uiImage: image)
                    .resizable()
                    .aspectRatio(contentMode: .fill)
            } else {
                Color.secondary.opacity(0.2)
                    .overlay(ProgressView())
            }
        }
        .task(id: url) {
            image = await ImageCache.shared.fetch(from: url)
        }
    }
}

---

URLCache-Based Disk Caching

Configure URLCache for persistent image caching that survives app restarts. URLCache handles HTTP cache headers automatically.

Configuring a Dedicated URLSession

enum ImageSessionConfiguration {
    static func makeSession() -> URLSession {
        let config = URLSessionConfiguration.default

        // 50 MB memory / 200 MB disk
        config.urlCache = URLCache(
            memoryCapacity: 50 * 1024 * 1024,
            diskCapacity: 200 * 1024 * 1024,
            directory: cacheDirectory
        )

        config.requestCachePolicy = .returnCacheDataElseLoad
        config.httpMaximumConnectionsPerHost = 6

        return URLSession(configuration: config)
    }

    private static var cacheDirectory: URL {
        FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask)[0]
            .appendingPathComponent("ImageCache", isDirectory: true)
    }
}

Cache-Aware Request

func cachedImageData(from url: URL, session: URLSession) async throws -> Data {
    let request = URLRequest(url: url, cachePolicy: .returnCacheDataElseLoad)
    let (data, _) = try await session.data(for: request)
    return data
}

Force Refresh (Bypass Cache)

func refreshImageData(from url: URL, session: URLSession) async throws -> Data {
    let request = URLRequest(url: url, cachePolicy: .reloadIgnoringLocalCacheData)
    let (data, _) = try await session.data(for: request)
    return data
}

Cache Cleanup

func cleanImageCache(session: URLSession) {
    session.configuration.urlCache?.removeAllCachedResponses()
}

func removeCachedImage(for url: URL, session: URLSession) {
    let request = URLRequest(url: url)
    session.configuration.urlCache?.removeCachedResponse(for: request)
}

---

Image Downsampling with CGImageSource

Loading a full-resolution image into memory then scaling it in the view wastes significant memory. Downsampling at decode time creates a smaller bitmap directly.

Downsample Function

import ImageIO
import UIKit

func downsample(data: Data, to pointSize: CGSize, scale: CGFloat = UITraitCollection.current.displayScale) -> UIImage? {
    let maxDimensionInPixels = max(pointSize.width, pointSize.height) * scale

    let options: [CFString: Any] = [
        kCGImageSourceCreateThumbnailFromImageAlways: true,
        kCGImageSourceShouldCacheImmediately: true,
        kCGImageSourceCreateThumbnailWithTransform: true,
        kCGImageSourceThumbnailMaxPixelSize: maxDimensionInPixels
    ]

    guard let source = CGImageSourceCreateWithData(data as CFData, nil),
          let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else {
        return nil
    }

    return UIImage(cgImage: cgImage)
}

Downsample from URL

func downsample(url: URL, to pointSize: CGSize, scale: CGFloat = UITraitCollection.current.displayScale) -> UIImage? {
    let maxDimensionInPixels = max(pointSize.width, pointSize.height) * scale

    let options: [CFString: Any] = [
        kCGImageSourceCreateThumbnailFromImageAlways: true,
        kCGImageSourceShouldCacheImmediately: true,
        kCGImageSourceCreateThumbnailWithTransform: true,
        kCGImageSourceThumbnailMaxPixelSize: maxDimensionInPixels
    ]

    guard let source = CGImageSourceCreateWithURL(url as CFURL, nil),
          let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else {
        return nil
    }

    return UIImage(cgImage: cgImage)
}

When to Downsample

• Displaying thumbnails in a list or grid (a 4032x3024 photo for a 100x100 cell wastes ~46 MB per image).
• User-selected photos from the photo library.
• Images fetched from a server that are larger than the display size.
• Any time the source image dimensions exceed 2x the display point size.

Memory Savings

---

Image Prefetching for Lists and Grids

Prefetch images before they scroll into view. Works with both UICollectionView data source prefetching and SwiftUI List.

Prefetch Coordinator

@Observable
@MainActor
final class ImagePrefetcher {
    private let cache: ImageCache
    private let session: URLSession
    private var prefetchTasks: [URL: Task<Void, Never>] = [:]

    init(cache: ImageCache = .shared,
         session: URLSession = ImageSessionConfiguration.makeSession()) {
        self.cache = cache
        self.session = session
    }

    func prefetch(urls: [URL]) {
        for url in urls {
            guard prefetchTasks[url] == nil else { continue }

            prefetchTasks[url] = Task {
                _ = await cache.fetch(from: url, session: session)
                prefetchTasks[url] = nil
            }
        }
    }

    func cancelPrefetch(urls: [URL]) {
        for url in urls {
            prefetchTasks[url]?.cancel()
            prefetchTasks[url] = nil
        }
    }

    func cancelAll() {
        prefetchTasks.values.forEach { $0.cancel() }
        prefetchTasks.removeAll()
    }
}

SwiftUI Integration with ScrollView and LazyVGrid

struct PhotoGrid: View {
    let photos: [Photo]
    @State private var prefetcher = ImagePrefetcher()

    private let columns = [GridItem(.adaptive(minimum: 100), spacing: 2)]

    var body: some View {
        ScrollView {
            LazyVGrid(columns: columns, spacing: 2) {
                ForEach(photos) { photo in
                    CachedImageView(url: photo.thumbnailURL)
                        .aspectRatio(1, contentMode: .fill)
                        .clipped()
                        .onAppear {
                            prefetchNearby(photo)
                        }
                }
            }
        }
        .onDisappear {
            prefetcher.cancelAll()
        }
    }

    private func prefetchNearby(_ photo: Photo) {
        guard let index = photos.firstIndex(where: { $0.id == photo.id }) else { return }
        let prefetchRange = (index + 1)..<min(index + 10, photos.count)
        let urls = prefetchRange.map { photos[$0].thumbnailURL }
        prefetcher.prefetch(urls: urls)
    }
}

UICollectionView Prefetching (UIKit Interop)

final class PhotoCollectionPrefetcher: NSObject, UICollectionViewDataSourcePrefetching {
    private let prefetcher = ImagePrefetcher()
    private let photos: [Photo]

    init(photos: [Photo]) {
        self.photos = photos
    }

    func collectionView(_ collectionView: UICollectionView,
                        prefetchItemsAt indexPaths: [IndexPath]) {
        let urls = indexPaths.map { photos[$0.item].thumbnailURL }
        prefetcher.prefetch(urls: urls)
    }

    func collectionView(_ collectionView: UICollectionView,
                        cancelPrefetchingForItemsAt indexPaths: [IndexPath]) {
        let urls = indexPaths.map { photos[$0.item].thumbnailURL }
        prefetcher.cancelPrefetch(urls: urls)
    }
}

---

HEIF/HEIC Handling

HEIF (High Efficiency Image Format) is the default camera format on modern iPhones. Handle detection, display, and conversion.

Detection

import UniformTypeIdentifiers

func isHEIF(data: Data) -> Bool {
    guard data.count >= 12 else { return false }
    // Check for 'ftyp' box at byte 4
    let ftypRange = data[4..<8]
    return ftypRange.elementsEqual("ftyp".utf8)
}

func isHEIF(url: URL) -> Bool {
    guard let type = UTType(filenameExtension: url.pathExtension) else { return false }
    return type.conforms(to: .heif) || type.conforms(to: .heic)
}

Conversion to JPEG

func convertHEICToJPEG(data: Data, compressionQuality: CGFloat = 0.9) -> Data? {
    guard let image = UIImage(data: data) else { return nil }
    return image.jpegData(compressionQuality: compressionQuality)
}

Conversion to PNG

func convertHEICToPNG(data: Data) -> Data? {
    guard let image = UIImage(data: data) else { return nil }
    return image.pngData()
}

Conversion with CGImageDestination (More Control)

import ImageIO

func convertHEICToJPEG(sourceData: Data,
                        quality: CGFloat = 0.9,
                        preserveMetadata: Bool = true) -> Data? {
    guard let source = CGImageSourceCreateWithData(sourceData as CFData, nil),
          let cgImage = CGImageSourceCreateImageAtIndex(source, 0, nil) else {
        return nil
    }

    let mutableData = NSMutableData()
    guard let destination = CGImageDestinationCreateWithData(
        mutableData, UTType.jpeg.identifier as CFString, 1, nil
    ) else {
        return nil
    }

    var options: [CFString: Any] = [
        kCGImageDestinationLossyCompressionQuality: quality
    ]

    // Preserve EXIF, GPS, and other metadata
    if preserveMetadata,
       let metadata = CGImageSourceCopyPropertiesAtIndex(source, 0, nil) {
        options[kCGImageDestinationMergeMetadata] = true
        CGImageDestinationAddImage(destination, cgImage, metadata)
    } else {
        CGImageDestinationAddImage(destination, cgImage, options as CFDictionary)
    }

    guard CGImageDestinationFinalize(destination) else { return nil }
    return mutableData as Data
}

---

Compression Before Upload

Reduce file size before uploading to a server. Balance quality and size based on the use case.

JPEG Compression with Target Size

func compressForUpload(image: UIImage,
                       maxBytes: Int = 1_000_000,
                       initialQuality: CGFloat = 0.9) -> Data? {
    var quality = initialQuality

    while quality > 0.1 {
        guard let data = image.jpegData(compressionQuality: quality) else { return nil }
        if data.count <= maxBytes {
            return data
        }
        quality -= 0.1
    }

    // Final attempt at minimum quality
    return image.jpegData(compressionQuality: 0.1)
}

Resize and Compress

func resizeAndCompress(image: UIImage,
                       maxDimension: CGFloat = 1920,
                       compressionQuality: CGFloat = 0.8) -> Data? {
    let size = image.size
    let scale: CGFloat

    if max(size.width, size.height) > maxDimension {
        scale = maxDimension / max(size.width, size.height)
    } else {
        scale = 1.0
    }

    let newSize = CGSize(width: size.width * scale, height: size.height * scale)

    let renderer = UIGraphicsImageRenderer(size: newSize)
    let resized = renderer.image { _ in
        image.draw(in: CGRect(origin: .zero, size: newSize))
    }

    return resized.jpegData(compressionQuality: compressionQuality)
}

HEIF Compression (Smaller Files)

func compressAsHEIF(image: UIImage, quality: CGFloat = 0.8) -> Data? {
    guard let cgImage = image.cgImage else { return nil }

    let mutableData = NSMutableData()
    guard let destination = CGImageDestinationCreateWithData(
        mutableData, UTType.heic.identifier as CFString, 1, nil
    ) else {
        return nil
    }

    let options: [CFString: Any] = [
        kCGImageDestinationLossyCompressionQuality: quality
    ]

    CGImageDestinationAddImage(destination, cgImage, options as CFDictionary)
    guard CGImageDestinationFinalize(destination) else { return nil }

    return mutableData as Data
}

---

Memory Budget Management

Monitor and respond to memory pressure to keep your image pipeline stable.

Memory Warning Observer

@Observable
@MainActor
final class MemoryMonitor {
    var isUnderPressure = false

    init() {
        NotificationCenter.default.addObserver(
            forName: UIApplication.didReceiveMemoryWarningNotification,
            object: nil,
            queue: .main
        ) { [weak self] _ in
            self?.handleMemoryWarning()
        }
    }

    private func handleMemoryWarning() {
        isUnderPressure = true

        Task {
            await ImageCache.shared.removeAll()
        }

        // Reset after a delay
        Task {
            try? await Task.sleep(for: .seconds(10))
            isUnderPressure = false
        }
    }
}

Process Memory Usage

func currentMemoryUsageMB() -> Double {
    var info = mach_task_basic_info()
    var count = mach_msg_type_number_t(MemoryLayout<mach_task_basic_info>.size) / 4
    let result = withUnsafeMutablePointer(to: &info) {
        $0.withMemoryRebound(to: integer_t.self, capacity: Int(count)) {
            task_info(mach_task_self_, task_flavor_t(MACH_TASK_BASIC_INFO), $0, &count)
        }
    }
    guard result == KERN_SUCCESS else { return 0 }
    return Double(info.resident_size) / (1024 * 1024)
}

Adaptive Cache Sizing

actor AdaptiveImageCache {
    private let cache = NSCache<NSString, UIImage>()

    init() {
        let totalMemory = ProcessInfo.processInfo.physicalMemory
        // Use at most 10% of physical memory for image cache
        let budgetBytes = Int(totalMemory / 10)
        cache.totalCostLimit = budgetBytes
        cache.countLimit = 200
    }

    func image(for url: URL) -> UIImage? {
        cache.object(forKey: url.absoluteString as NSString)
    }

    func store(_ image: UIImage, for url: URL) {
        let cost = cgImageMemorySize(image)
        cache.setObject(image, forKey: url.absoluteString as NSString, cost: cost)
    }

    /// Estimate the decoded bitmap size in bytes.
    private func cgImageMemorySize(_ image: UIImage) -> Int {
        guard let cgImage = image.cgImage else { return 0 }
        return cgImage.bytesPerRow * cgImage.height
    }

    func purge() {
        cache.removeAllObjects()
    }
}

---

Complete Image Loading Pipeline

A production-ready pipeline that combines in-memory caching, disk caching via URLCache, downsampling, and request coalescing.

ImageLoader Actor

import UIKit
import ImageIO

actor ImageLoader {
    static let shared = ImageLoader()

    private let memoryCache = NSCache<NSString, UIImage>()
    private let session: URLSession
    private var inFlightTasks: [URL: Task<UIImage?, Never>] = [:]

    init() {
        let config = URLSessionConfiguration.default
        config.urlCache = URLCache(
            memoryCapacity: 50 * 1024 * 1024,
            diskCapacity: 200 * 1024 * 1024
        )
        config.requestCachePolicy = .returnCacheDataElseLoad
        config.httpMaximumConnectionsPerHost = 6
        session = URLSession(configuration: config)

        let totalMemory = ProcessInfo.processInfo.physicalMemory
        memoryCache.totalCostLimit = Int(totalMemory / 10)
        memoryCache.countLimit = 200
    }

    /// Load an image, optionally downsampling to the given display size.
    func load(from url: URL, displaySize: CGSize? = nil) async -> UIImage? {
        let cacheKey = cacheKey(url: url, size: displaySize)

        // 1. Check memory cache
        if let cached = memoryCache.object(forKey: cacheKey as NSString) {
            return cached
        }

        // 2. Coalesce duplicate in-flight requests
        if let existing = inFlightTasks[url] {
            return await existing.value
        }

        let task = Task<UIImage?, Never> {
            defer { inFlightTasks[url] = nil }

            guard let (data, response) = try? await session.data(from: url),
                  let httpResponse = response as? HTTPURLResponse,
                  httpResponse.statusCode == 200 else {
                return nil
            }

            // 3. Downsample if a display size is provided
            let image: UIImage?
            if let displaySize {
                image = Self.downsample(data: data, to: displaySize)
            } else {
                image = UIImage(data: data)
            }

            // 4. Store in memory cache
            if let image {
                let cost = Self.bitmapSize(of: image)
                memoryCache.setObject(image, forKey: cacheKey as NSString, cost: cost)
            }

            return image
        }

        inFlightTasks[url] = task
        return await task.value
    }

    /// Remove a specific URL from the memory cache.
    func evict(url: URL, displaySize: CGSize? = nil) {
        let key = cacheKey(url: url, size: displaySize)
        memoryCache.removeObject(forKey: key as NSString)
    }

    /// Purge all in-memory cached images.
    func purgeMemoryCache() {
        memoryCache.removeAllObjects()
        inFlightTasks.values.forEach { $0.cancel() }
        inFlightTasks.removeAll()
    }

    // MARK: - Private

    private func cacheKey(url: URL, size: CGSize?) -> String {
        if let size {
            return "\(url.absoluteString)_\(Int(size.width))x\(Int(size.height))"
        }
        return url.absoluteString
    }

    private static func downsample(data: Data, to pointSize: CGSize) -> UIImage? {
        let scale = UITraitCollection.current.displayScale
        let maxDimension = max(pointSize.width, pointSize.height) * scale

        let options: [CFString: Any] = [
            kCGImageSourceCreateThumbnailFromImageAlways: true,
            kCGImageSourceShouldCacheImmediately: true,
            kCGImageSourceCreateThumbnailWithTransform: true,
            kCGImageSourceThumbnailMaxPixelSize: maxDimension
        ]

        guard let source = CGImageSourceCreateWithData(data as CFData, nil),
              let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else {
            return nil
        }

        return UIImage(cgImage: cgImage)
    }

    private static func bitmapSize(of image: UIImage) -> Int {
        guard let cgImage = image.cgImage else { return 0 }
        return cgImage.bytesPerRow * cgImage.height
    }
}

SwiftUI View Using the Pipeline

struct PipelineImageView: View {
    let url: URL
    var displaySize: CGSize = CGSize(width: 300, height: 300)

    @State private var image: UIImage?
    @State private var isLoading = true

    var body: some View {
        ZStack {
            if let image {
                Image(uiImage: image)
                    .resizable()
                    .aspectRatio(contentMode: .fill)
            } else if isLoading {
                Color.secondary.opacity(0.15)
                    .overlay(ProgressView())
            } else {
                Color.secondary.opacity(0.15)
                    .overlay {
                        Image(systemName: "photo")
                            .font(.title2)
                            .foregroundStyle(.secondary)
                    }
            }
        }
        .frame(width: displaySize.width, height: displaySize.height)
        .clipped()
        .task(id: url) {
            isLoading = true
            image = await ImageLoader.shared.load(from: url, displaySize: displaySize)
            isLoading = false
        }
    }
}

Memory Warning Integration

struct PhotoGridView: View {
    let photos: [Photo]

    var body: some View {
        ScrollView {
            LazyVGrid(columns: [GridItem(.adaptive(minimum: 100), spacing: 2)], spacing: 2) {
                ForEach(photos) { photo in
                    PipelineImageView(
                        url: photo.thumbnailURL,
                        displaySize: CGSize(width: 100, height: 100)
                    )
                }
            }
        }
        .onReceive(NotificationCenter.default.publisher(
            for: UIApplication.didReceiveMemoryWarningNotification
        )) { _ in
            Task {
                await ImageLoader.shared.purgeMemoryCache()
            }
        }
    }
}

When to Use Each Layer

PhotosPicker Patterns

Complete recipes for photo and video selection, loading, saving, and processing. All patterns target iOS 16+ with SwiftUI and async/await.

---

Contents

• 1. Single Photo Selection with Loading State
• 2. Multi-Selection with Progress Tracking
• 3. Loading Videos from PhotosPicker
• 4. Loading Live Photos
• 5. PHPickerViewController Wrapping (UIKit Interop)
• 6. Saving Images to Photo Library
• 7. Thumbnail Generation with ImageIO Downsampling
• 8. HEIC/HEIF Handling
• 9. Custom PhotosPicker Appearance
• 10. Image Cropping Pattern

1. Single Photo Selection with Loading State

Handle the full lifecycle: idle, loading, loaded, and error.

import SwiftUI
import PhotosUI

struct ProfilePhotoPicker: View {
    @State private var selectedItem: PhotosPickerItem?
    @State private var loadState: LoadState = .idle

    enum LoadState {
        case idle, loading, loaded(Image), error(String)
    }

    var body: some View {
        VStack {
            switch loadState {
            case .idle:
                Image(systemName: "person.crop.circle.fill")
                    .resizable()
                    .frame(width: 120, height: 120)
                    .foregroundStyle(.secondary)
            case .loading:
                ProgressView()
                    .frame(width: 120, height: 120)
            case .loaded(let image):
                image
                    .resizable()
                    .scaledToFill()
                    .frame(width: 120, height: 120)
                    .clipShape(Circle())
            case .error(let message):
                ContentUnavailableView(message, systemImage: "exclamationmark.triangle")
            }

            PhotosPicker("Choose Photo", selection: $selectedItem, matching: .images)
                .buttonStyle(.borderedProminent)
        }
        .onChange(of: selectedItem) { _, newItem in
            guard let newItem else {
                loadState = .idle
                return
            }
            loadState = .loading
            Task {
                do {
                    if let data = try await newItem.loadTransferable(type: Data.self),
                       let uiImage = UIImage(data: data) {
                        loadState = .loaded(Image(uiImage: uiImage))
                    } else {
                        loadState = .error("Unable to load image")
                    }
                } catch {
                    loadState = .error(error.localizedDescription)
                }
            }
        }
    }
}

---

2. Multi-Selection with Progress Tracking

Load multiple images sequentially and report progress back to the UI.

import SwiftUI
import PhotosUI

struct MultiPhotoLoader: View {
    @State private var selectedItems: [PhotosPickerItem] = []
    @State private var loadedImages: [UIImage] = []
    @State private var loadProgress: Double = 0
    @State private var isLoading = false

    var body: some View {
        VStack {
            if isLoading {
                ProgressView(value: loadProgress)
                    .padding()
            }

            ScrollView(.horizontal) {
                LazyHStack {
                    ForEach(loadedImages.indices, id: \.self) { index in
                        Image(uiImage: loadedImages[index])
                            .resizable()
                            .scaledToFill()
                            .frame(width: 100, height: 100)
                            .clipShape(.rect(cornerRadius: 8))
                    }
                }
                .padding(.horizontal)
            }
            .frame(height: loadedImages.isEmpty ? 0 : 116)

            PhotosPicker(
                "Select Photos",
                selection: $selectedItems,
                maxSelectionCount: 10,
                matching: .images
            )
        }
        .onChange(of: selectedItems) { _, newItems in
            Task { await loadImages(from: newItems) }
        }
    }

    private func loadImages(from items: [PhotosPickerItem]) async {
        isLoading = true
        loadProgress = 0
        var images: [UIImage] = []

        for (index, item) in items.enumerated() {
            if let data = try? await item.loadTransferable(type: Data.self),
               let uiImage = UIImage(data: data) {
                images.append(uiImage)
            }
            loadProgress = Double(index + 1) / Double(items.count)
        }

        loadedImages = images
        isLoading = false
    }
}

Load sequentially rather than concurrently to control memory usage. Each full-resolution image can be large; loading ten simultaneously risks memory termination.

---

3. Loading Videos from PhotosPicker

Use a Transferable wrapper that writes video data to a temporary file, since videos are too large to hold in memory as Data.

import SwiftUI
import PhotosUI
import AVKit

struct PickedMovie: Transferable {
    let url: URL

    static var transferRepresentation: some TransferRepresentation {
        FileRepresentation(contentType: .movie) { movie in
            SentTransferredFile(movie.url)
        } importing: { received in
            // Copy to a temporary location the app controls
            let tempURL = FileManager.default.temporaryDirectory
                .appendingPathComponent(UUID().uuidString)
                .appendingPathExtension("mov")
            try FileManager.default.copyItem(at: received.file, to: tempURL)
            return PickedMovie(url: tempURL)
        }
    }
}

struct VideoPickerView: View {
    @State private var selectedItem: PhotosPickerItem?
    @State private var player: AVPlayer?

    var body: some View {
        VStack {
            if let player {
                VideoPlayer(player: player)
                    .frame(height: 300)
            }

            PhotosPicker("Select Video", selection: $selectedItem, matching: .videos)
        }
        .onChange(of: selectedItem) { _, newItem in
            Task {
                if let movie = try? await newItem?.loadTransferable(type: PickedMovie.self) {
                    player = AVPlayer(url: movie.url)
                }
            }
        }
    }
}

Always copy the received file to a temporary directory you control. The system may delete the original transfer file at any time.

---

4. Loading Live Photos

import SwiftUI
import PhotosUI

@available(iOS 17.0, *)
struct LivePhotoPickerView: View {
    @State private var selectedItem: PhotosPickerItem?
    @State private var livePhoto: PHLivePhoto?

    var body: some View {
        VStack {
            if let livePhoto {
                LivePhotoView(livePhoto: livePhoto)
                    .frame(height: 300)
            }

            PhotosPicker(
                "Select Live Photo",
                selection: $selectedItem,
                matching: .livePhotos
            )
        }
        .onChange(of: selectedItem) { _, newItem in
            Task {
                livePhoto = try? await newItem?.loadTransferable(type: PHLivePhoto.self)
            }
        }
    }
}

PHLivePhoto conforms to Transferable on iOS 17+. On iOS 16, load the Live Photo components manually using PHAsset.

---

5. PHPickerViewController Wrapping (UIKit Interop)

Use PHPickerViewController when you need UIKit-level control or are integrating into an existing UIKit codebase. Prefer PhotosPicker for pure SwiftUI apps.

import SwiftUI
import PhotosUI

struct PHPickerWrapper: UIViewControllerRepresentable {
    @Binding var selectedImages: [UIImage]
    var selectionLimit: Int = 0
    @Environment(\.dismiss) private var dismiss

    func makeCoordinator() -> Coordinator { Coordinator(self) }

    func makeUIViewController(context: Context) -> PHPickerViewController {
        var config = PHPickerConfiguration(photoLibrary: .shared())
        config.filter = .images
        config.selectionLimit = selectionLimit
        config.preferredAssetRepresentationMode = .current

        let picker = PHPickerViewController(configuration: config)
        picker.delegate = context.coordinator
        return picker
    }

    func updateUIViewController(_ uiViewController: PHPickerViewController, context: Context) {
        // Configuration is immutable after creation
    }

    final class Coordinator: NSObject, PHPickerViewControllerDelegate {
        let parent: PHPickerWrapper

        init(_ parent: PHPickerWrapper) { self.parent = parent }

        func picker(
            _ picker: PHPickerViewController,
            didFinishPicking results: [PHPickerResult]
        ) {
            parent.dismiss()
            guard !results.isEmpty else { return }

            Task { @MainActor in
                var images: [UIImage] = []
                for result in results {
                    if let image = await loadImage(from: result.itemProvider) {
                        images.append(image)
                    }
                }
                parent.selectedImages = images
            }
        }

        private func loadImage(from provider: NSItemProvider) async -> UIImage? {
            await withCheckedContinuation { continuation in
                if provider.canLoadObject(ofClass: UIImage.self) {
                    provider.loadObject(ofClass: UIImage.self) { image, _ in
                        continuation.resume(returning: image as? UIImage)
                    }
                } else {
                    continuation.resume(returning: nil)
                }
            }
        }
    }
}

Always call parent.dismiss() in picker(_:didFinishPicking:) -- this delegate method fires for both selection and cancellation (with empty results).

---

6. Saving Images to Photo Library

Saving requires NSPhotoLibraryAddUsageDescription in Info.plist. Use PHPhotoLibrary for saving with metadata, or UIImageWriteToSavedPhotosAlbum for simple saves.

Using PHPhotoLibrary (Preferred)

import Photos

func saveImageToLibrary(_ image: UIImage) async throws {
    try await PHPhotoLibrary.shared().performChanges {
        let request = PHAssetCreationRequest.forAsset()
        request.addResource(with: .photo, data: image.jpegData(compressionQuality: 0.9)!, options: nil)
    }
}

func saveImageDataToLibrary(_ data: Data) async throws {
    try await PHPhotoLibrary.shared().performChanges {
        let request = PHAssetCreationRequest.forAsset()
        let options = PHAssetResourceCreationOptions()
        request.addResource(with: .photo, data: data, options: options)
    }
}

Saving to a Specific Album

import Photos

func saveToAlbum(image: UIImage, albumName: String) async throws {
    let album = try await findOrCreateAlbum(named: albumName)

    try await PHPhotoLibrary.shared().performChanges {
        let assetRequest = PHAssetCreationRequest.forAsset()
        assetRequest.addResource(
            with: .photo,
            data: image.jpegData(compressionQuality: 0.9)!,
            options: nil
        )

        guard let placeholder = assetRequest.placeholderForCreatedAsset,
              let albumChangeRequest = PHAssetCollectionChangeRequest(for: album) else { return }
        albumChangeRequest.addAssets([placeholder] as NSArray)
    }
}

private func findOrCreateAlbum(named name: String) async throws -> PHAssetCollection {
    let fetchOptions = PHFetchOptions()
    fetchOptions.predicate = NSPredicate(format: "title = %@", name)
    let result = PHAssetCollection.fetchAssetCollections(with: .album, subtype: .any, options: fetchOptions)

    if let existing = result.firstObject {
        return existing
    }

    // Create the album
    var placeholder: PHObjectPlaceholder?
    try await PHPhotoLibrary.shared().performChanges {
        let request = PHAssetCollectionChangeRequest.creationRequestForAssetCollection(withTitle: name)
        placeholder = request.placeholderForCreatedAssetCollection
    }

    guard let placeholder,
          let collection = PHAssetCollection.fetchAssetCollections(
              withLocalIdentifiers: [placeholder.localIdentifier],
              options: nil
          ).firstObject else {
        throw PhotoLibraryError.albumCreationFailed
    }

    return collection
}

enum PhotoLibraryError: Error {
    case albumCreationFailed
}

---

7. Thumbnail Generation with ImageIO Downsampling

Generate thumbnails efficiently without decoding the full image into memory. This is critical for grids and lists displaying many photos.

import ImageIO
import UIKit

/// Downsample image data to a target display size.
/// Use this instead of UIImage(data:) followed by resizing, which decodes the full image.
func downsample(
    data: Data,
    to pointSize: CGSize,
    scale: CGFloat = UITraitCollection.current.displayScale
) -> UIImage? {
    let maxDimension = max(pointSize.width, pointSize.height) * scale

    let options: [CFString: Any] = [
        kCGImageSourceCreateThumbnailFromImageAlways: true,
        kCGImageSourceShouldCacheImmediately: true,
        kCGImageSourceCreateThumbnailWithTransform: true,
        kCGImageSourceThumbnailMaxPixelSize: maxDimension
    ]

    guard let source = CGImageSourceCreateWithData(data as CFData, nil),
          let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else {
        return nil
    }

    return UIImage(cgImage: cgImage)
}

/// Downsample from a file URL (avoids loading full data into memory).
func downsample(
    url: URL,
    to pointSize: CGSize,
    scale: CGFloat = UITraitCollection.current.displayScale
) -> UIImage? {
    let maxDimension = max(pointSize.width, pointSize.height) * scale

    let sourceOptions: [CFString: Any] = [kCGImageSourceShouldCache: false]
    guard let source = CGImageSourceCreateWithURL(url as CFURL, sourceOptions as CFDictionary) else {
        return nil
    }

    let downsampleOptions: [CFString: Any] = [
        kCGImageSourceCreateThumbnailFromImageAlways: true,
        kCGImageSourceShouldCacheImmediately: true,
        kCGImageSourceCreateThumbnailWithTransform: true,
        kCGImageSourceThumbnailMaxPixelSize: maxDimension
    ]

    guard let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, downsampleOptions as CFDictionary) else {
        return nil
    }

    return UIImage(cgImage: cgImage)
}

Usage in a Photo Grid

struct PhotoGridItem: View {
    let imageData: Data
    let thumbnailSize = CGSize(width: 100, height: 100)

    @State private var thumbnail: UIImage?

    var body: some View {
        Group {
            if let thumbnail {
                Image(uiImage: thumbnail)
                    .resizable()
                    .scaledToFill()
            } else {
                Rectangle()
                    .fill(.quaternary)
                    .overlay(ProgressView())
            }
        }
        .frame(width: 100, height: 100)
        .clipShape(.rect(cornerRadius: 6))
        .task {
            thumbnail = downsample(data: imageData, to: thumbnailSize)
        }
    }
}

---

8. HEIC/HEIF Handling

Modern iPhones capture photos in HEIC format by default. Handle both HEIC and JPEG transparently.

Checking Image Format

import UniformTypeIdentifiers

func imageContentType(data: Data) -> UTType? {
    guard let source = CGImageSourceCreateWithData(data as CFData, nil),
          let uti = CGImageSourceGetType(source) as? String else {
        return nil
    }
    return UTType(uti)
}

Converting HEIC to JPEG

import UIKit

func convertToJPEG(heicData: Data, compressionQuality: CGFloat = 0.9) -> Data? {
    guard let image = UIImage(data: heicData) else { return nil }
    return image.jpegData(compressionQuality: compressionQuality)
}

Preserving HEIC When Possible

When saving or uploading, prefer keeping the original HEIC format to preserve quality and reduce file size. Convert to JPEG only when the destination requires it (e.g., a server that rejects HEIC).

import PhotosUI

// Request the current representation to avoid transcoding
var config = PHPickerConfiguration(photoLibrary: .shared())
config.preferredAssetRepresentationMode = .current  // Keeps HEIC as-is
// vs .compatible which transcodes to JPEG

---

9. Custom PhotosPicker Appearance

Customize the picker trigger with any SwiftUI view using the label closure:

PhotosPicker(selection: $selectedItems, maxSelectionCount: 3, matching: .images) {
    Label("Add Photos", systemImage: "photo.on.rectangle.angled")
        .font(.headline)
        .padding()
        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 12))
}

Inline PhotosPicker (iOS 17+)

Display the picker inline rather than as a sheet:

@available(iOS 17.0, *)
PhotosPicker(
    selection: $selectedItems,
    maxSelectionCount: 5,
    matching: .images
)
.photosPickerStyle(.inline)
.frame(height: 300)

Photos Picker Access Behavior (iOS 17+)

Control how the picker interacts with limited library access:

@available(iOS 17.0, *)
PhotosPicker(selection: $selectedItems, matching: .images)
    .photosPickerAccessBehavior(.limited)  // Only show user-approved photos
    // .automatic (default) -- system decides
    // .limited -- only previously approved photos

---

10. Image Cropping Pattern

A basic square crop using Core Graphics after selecting a photo:

import UIKit

func cropToSquare(_ image: UIImage) -> UIImage? {
    guard let cgImage = image.cgImage else { return nil }

    let side = min(cgImage.width, cgImage.height)
    let x = (cgImage.width - side) / 2
    let y = (cgImage.height - side) / 2
    let cropRect = CGRect(x: x, y: y, width: side, height: side)

    guard let cropped = cgImage.cropping(to: cropRect) else { return nil }
    return UIImage(cgImage: cropped, scale: image.scale, orientation: image.imageOrientation)
}

For interactive cropping, consider wrapping a third-party crop view or building a gesture-based crop overlay in SwiftUI. The system does not provide a built-in crop controller.