capacitor-camera-view 2.4.0 → 3.0.0

package/ios/Sources/CameraViewPlugin/CameraViewManager+PhotoCapture.swift

@@ -1,16 +1,19 @@
 import AVFoundation
 import Foundation
-import UIKit
 
 extension CameraViewManager: AVCapturePhotoCaptureDelegate {
     /// Set up output for the capture session in case it's not configured yet
     /// Make sure to call `captureSession.beginConfiguration` before calling this
     ///
+    /// - Parameter prioritizeQuality: When `true`, the iOS 17+ responsive-capture
+    ///   optimizations are skipped so captures always prioritize quality.
     /// - Throws: An error if the output cannot be set.
-    internal func setupPhotoOutput() throws {
+    internal func setupPhotoOutput(prioritizeQuality: Bool = false) throws {
         if (captureSession.outputs.contains { $0 is AVCapturePhotoOutput }) {
-            // Nothing todo, we already have an output and since we only
-            // use outputs for taking photos here we don't need a new one
+            // The output already exists (session restart) - still reconfigure
+            // the responsiveness pipeline, since prioritizeQuality may have
+            // changed between sessions.
+            configureResponsiveCapture(prioritizeQuality: prioritizeQuality)
             return
         }
 
@@ -22,12 +25,67 @@ extension CameraViewManager: AVCapturePhotoCaptureDelegate {
         }
 
         captureSession.addOutput(avPhotoOutput)
+        deferStart(of: avPhotoOutput)
+
+        configureResponsiveCapture(prioritizeQuality: prioritizeQuality)
     }
 
-    /// Delegate method called when a photo has been captured via `AVCapturePhotoCaptureDelegate`
+    /// Applies the iOS 17+ capture-responsiveness state on the photo output where
+    /// supported, reducing shot-to-shot latency.
     ///
-    /// This method handles both the legacy UIImage-based callback and the optimized Data-based
-    /// callback to eliminate double JPEG encoding when possible.
+    /// Ordering matters: responsive capture requires zero-shutter-lag, and fast
+    /// capture prioritization requires responsive capture, so capabilities are
+    /// enabled prerequisite-first and disabled dependent-first.
+    ///
+    /// - Parameter prioritizeQuality: When `true`, the optimizations are turned
+    ///   off (not merely skipped) so a session restart that flips the option
+    ///   always prioritizes quality.
+    private func configureResponsiveCapture(prioritizeQuality: Bool) {
+        if #available(iOS 17.0, *) {
+            let enable = !prioritizeQuality
+
+            if enable {
+                if avPhotoOutput.isZeroShutterLagSupported {
+                    avPhotoOutput.isZeroShutterLagEnabled = true
+                }
+
+                if avPhotoOutput.isResponsiveCaptureSupported {
+                    avPhotoOutput.isResponsiveCaptureEnabled = true
+
+                    // Fast capture prioritization requires responsive capture
+                    // to be enabled first.
+                    if avPhotoOutput.isFastCapturePrioritizationSupported {
+                        avPhotoOutput.isFastCapturePrioritizationEnabled = true
+                    }
+                }
+            } else {
+                // Disable dependents before their prerequisites.
+                if avPhotoOutput.isFastCapturePrioritizationSupported {
+                    avPhotoOutput.isFastCapturePrioritizationEnabled = false
+                }
+                if avPhotoOutput.isResponsiveCaptureSupported {
+                    avPhotoOutput.isResponsiveCaptureEnabled = false
+                }
+                if avPhotoOutput.isZeroShutterLagSupported {
+                    avPhotoOutput.isZeroShutterLagEnabled = false
+                }
+            }
+        }
+    }
+
+    /// Atomically consumes the photo completion handler so a photo-output
+    /// delegate callback can never race handler assignment on the capture thread.
+    internal func consumePhotoDataHandler() -> ((Data?, Error?) -> Void)? {
+        captureHandlerLock.lock()
+        defer { captureHandlerLock.unlock() }
+
+        let dataHandler = photoDataCaptureHandler
+        photoDataCaptureHandler = nil
+        return dataHandler
+    }
+
+    /// Delegate method called when a photo has been captured via `AVCapturePhotoCaptureDelegate`.
+    /// Returns the camera's native JPEG data directly, avoiding a double JPEG encode.
     ///
     /// - Parameters:
     ///   - output: The photo output that captured the photo.
@@ -38,45 +96,19 @@ extension CameraViewManager: AVCapturePhotoCaptureDelegate {
         didFinishProcessingPhoto photo: AVCapturePhoto,
         error: Error?
     ) {
-        // Handle optimized Data-based callback first (avoids double encoding)
-        if let dataHandler = photoDataCaptureHandler {
-            photoDataCaptureHandler = nil
+        guard let dataHandler = consumePhotoDataHandler() else { return }
 
-            if let error = error {
-                dataHandler(nil, error)
-                return
-            }
-
-            guard let data = photo.fileDataRepresentation() else {
-                dataHandler(nil, CameraError.photoOutputError)
-                return
-            }
-
-            dataHandler(data, nil)
+        if let error = error {
+            dataHandler(nil, error)
             return
         }
 
-        // Handle legacy UIImage-based callback
-        if let imageHandler = photoCaptureHandler {
-            photoCaptureHandler = nil
-
-            if let error = error {
-                imageHandler(nil, error)
-                return
-            }
-
-            guard let data = photo.fileDataRepresentation() else {
-                imageHandler(nil, CameraError.photoOutputError)
-                return
-            }
-
-            guard let image = UIImage(data: data) else {
-                imageHandler(nil, CameraError.photoOutputError)
-                return
-            }
-
-            imageHandler(image, nil)
+        guard let data = photo.fileDataRepresentation() else {
+            dataHandler(nil, CameraError.photoOutputError)
+            return
         }
+
+        dataHandler(data, nil)
     }
 
 }

package/ios/Sources/CameraViewPlugin/CameraViewManager+ResolutionSelection.swift

@@ -0,0 +1,57 @@
+import AVFoundation
+import Foundation
+
+/// Resolution / aspect-ratio selection for preview and photo capture.
+///
+/// The session preset drives the active format and therefore the aspect ratio
+/// of both the preview stream and captured photos, keeping what the user sees
+/// consistent with what gets captured.
+extension CameraViewManager {
+
+    /// Applies the session preset matching the configured aspect ratio.
+    ///
+    /// "16:9" prefers the HD video presets (highest first); "4:3" and `nil` use
+    /// the `.photo` preset with the sensor's native 4:3 photo format.
+    ///
+    /// Must run inside a configuration transaction on the session queue.
+    ///
+    /// - Parameter aspectRatio: The configured aspect ratio ("4:3", "16:9" or `nil`).
+    internal func applySessionPreset(forAspectRatio aspectRatio: String?) {
+        let preferredPresets: [AVCaptureSession.Preset] =
+            aspectRatio == "16:9"
+            ? [.hd4K3840x2160, .hd1920x1080, .hd1280x720, .photo]
+            : [.photo]
+
+        for preset in preferredPresets where captureSession.canSetSessionPreset(preset) {
+            captureSession.sessionPreset = preset
+            return
+        }
+    }
+
+    /// Re-applies the configured capture-resolution hint to the photo output.
+    ///
+    /// Picks the largest supported photo dimensions whose longer edge does not
+    /// exceed the hint, falling back to the smallest supported dimensions.
+    ///
+    /// `maxPhotoDimensions` is only valid against the *current* active format's
+    /// `supportedMaxPhotoDimensions` and is reset by AVFoundation whenever the
+    /// active format changes, so it must be re-applied on the session queue
+    /// after every committed transaction that changes the format.
+    internal func applyConfiguredMaxPhotoDimensions() {
+        guard let maxDimension = configuredCaptureMaxDimension,
+              let device = currentCameraDevice else { return }
+
+        let supported = device.activeFormat.supportedMaxPhotoDimensions
+
+        let byArea: (CMVideoDimensions, CMVideoDimensions) -> Bool = {
+            Int64($0.width) * Int64($0.height) < Int64($1.width) * Int64($1.height)
+        }
+        let fitting = supported.filter { Int(max($0.width, $0.height)) <= maxDimension }
+
+        guard let chosen = fitting.max(by: byArea) ?? supported.min(by: byArea) else {
+            return
+        }
+
+        avPhotoOutput.maxPhotoDimensions = chosen
+    }
+}

package/ios/Sources/CameraViewPlugin/CameraViewManager+Rotation.swift

@@ -0,0 +1,195 @@
+import AVFoundation
+import Foundation
+import UIKit
+
+/// Rotation handling for the camera preview and capture outputs.
+///
+/// On iOS 17+ this adopts `AVCaptureDevice.RotationCoordinator`, which reports
+/// horizon-level rotation angles for the preview and for capture and updates
+/// them continuously without relying on `UIDevice` orientation notifications.
+/// On iOS 16 it falls back to the legacy `videoOrientation` API driven by device
+/// orientation changes (see `setupOrientationObserver`).
+extension CameraViewManager {
+
+    // MARK: - iOS 17+ Rotation Coordinator
+
+    /// Typed accessor over the `Any?`-backed coordinator storage.
+    ///
+    /// Takes `rotationCoordinatorLock`: the storage is written on the main queue
+    /// but read from the Capacitor call thread and the session queue, and an
+    /// unsynchronized ARC reassignment racing a read is undefined behavior.
+    @available(iOS 17.0, *)
+    internal var rotationCoordinator: AVCaptureDevice.RotationCoordinator? {
+        get {
+            rotationCoordinatorLock.lock()
+            defer { rotationCoordinatorLock.unlock() }
+            return rotationCoordinatorStorage as? AVCaptureDevice.RotationCoordinator
+        }
+        set {
+            rotationCoordinatorLock.lock()
+            defer { rotationCoordinatorLock.unlock() }
+            rotationCoordinatorStorage = newValue
+        }
+    }
+
+    /// (Re)configures rotation handling for the current camera device. Safe to
+    /// call whenever the active device changes (flip, triple-camera upgrade) or
+    /// once the preview becomes available.
+    internal func configureRotationHandling() {
+        if #available(iOS 17.0, *) {
+            setupRotationCoordinator()
+        } else {
+            DispatchQueue.main.async { [weak self] in
+                self?.updateLegacyPreviewOrientation()
+            }
+        }
+    }
+
+    /// Creates a rotation coordinator for the active device and observes its
+    /// preview angle to keep the preview level with the horizon. Recreated on
+    /// every device change so the angles track the physical camera in use.
+    @available(iOS 17.0, *)
+    private func setupRotationCoordinator() {
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self,
+                  let device = self.currentCameraDevice,
+                  self.videoPreviewLayer.session != nil else { return }
+
+            // Invalidate the previous observation before replacing the coordinator.
+            self.rotationObservation?.invalidate()
+
+            let coordinator = AVCaptureDevice.RotationCoordinator(
+                device: device,
+                previewLayer: self.videoPreviewLayer
+            )
+            self.rotationCoordinator = coordinator
+
+            // `.initial` applies the current angle immediately; subsequent
+            // changes keep the preview rotating continuously.
+            self.rotationObservation = coordinator.observe(
+                \.videoRotationAngleForHorizonLevelPreview,
+                options: [.initial, .new]
+            ) { [weak self] coordinator, _ in
+                self?.applyPreviewRotationAngle(
+                    coordinator.videoRotationAngleForHorizonLevelPreview
+                )
+            }
+        }
+    }
+
+    /// Applies a preview rotation angle to the preview layer's connection.
+    @available(iOS 17.0, *)
+    private func applyPreviewRotationAngle(_ angle: CGFloat) {
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self,
+                  let connection = self.videoPreviewLayer.connection,
+                  connection.isVideoRotationAngleSupported(angle) else { return }
+
+            connection.videoRotationAngle = angle
+
+            // Keep the preview layer filling the (possibly rotated) bounds.
+            if let view = self.webView {
+                self.videoPreviewLayer.frame = view.bounds
+            }
+        }
+    }
+
+    // MARK: - Capture Orientation
+
+    /// Applies the correct rotation to a capture output connection (photo,
+    /// sample, or movie) so captured media matches the device orientation.
+    internal func applyCaptureOrientation(to connection: AVCaptureConnection) {
+        if #available(iOS 17.0, *) {
+            // A nil coordinator only happens for a capture racing session
+            // teardown; leaving the connection at its default angle is harmless.
+            guard let coordinator = rotationCoordinator else { return }
+            let angle = coordinator.videoRotationAngleForHorizonLevelCapture
+            if connection.isVideoRotationAngleSupported(angle) {
+                connection.videoRotationAngle = angle
+            }
+        } else {
+            applyLegacyCaptureOrientation(to: connection)
+        }
+    }
+
+    // MARK: - iOS 16 Legacy Path
+
+    /// Sets up device orientation handling (called from `init`).
+    ///
+    /// No-op on iOS 17+, where the rotation coordinator takes over. On iOS 16
+    /// the plugin generates the device orientation notifications itself rather
+    /// than relying on the host app having started them.
+    internal func setupOrientationObserver() {
+        if #available(iOS 17.0, *) {
+            return
+        }
+
+        UIDevice.current.beginGeneratingDeviceOrientationNotifications()
+        orientationObserverToken = NotificationCenter.default.addObserver(
+            forName: UIDevice.orientationDidChangeNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            self?.updateLegacyPreviewOrientation()
+        }
+    }
+
+    /// Tears down the block-based orientation observer registered by
+    /// `setupOrientationObserver`. `NotificationCenter.removeObserver(self)`
+    /// does not remove block-based observers, so the token must be removed
+    /// explicitly or it leaks for the process lifetime.
+    internal func removeOrientationObserver() {
+        if let token = orientationObserverToken {
+            NotificationCenter.default.removeObserver(token)
+            orientationObserverToken = nil
+        }
+
+        if #unavailable(iOS 17.0) {
+            UIDevice.current.endGeneratingDeviceOrientationNotifications()
+        }
+    }
+
+    /// Legacy capture orientation: mirror the preview connection's
+    /// `videoOrientation` onto the capture connection.
+    @available(iOS, introduced: 16.0, deprecated: 17.0,
+               message: "Uses videoOrientation; replaced by RotationCoordinator on iOS 17+")
+    private func applyLegacyCaptureOrientation(to connection: AVCaptureConnection) {
+        guard let previewConnection = videoPreviewLayer.connection,
+              connection.isVideoOrientationSupported else { return }
+        connection.videoOrientation = previewConnection.videoOrientation
+    }
+
+    /// Legacy preview orientation: derive `videoOrientation` from the current
+    /// interface orientation. Driven by `UIDevice` orientation notifications.
+    @available(iOS, introduced: 16.0, deprecated: 17.0,
+               message: "Uses videoOrientation; replaced by RotationCoordinator on iOS 17+")
+    internal func updateLegacyPreviewOrientation() {
+        guard let connection = videoPreviewLayer.connection,
+              connection.isVideoOrientationSupported else { return }
+
+        let interfaceOrientation = UIApplication.shared.connectedScenes
+            .compactMap { $0 as? UIWindowScene }
+            .first?.interfaceOrientation ?? .portrait
+
+        let videoOrientation: AVCaptureVideoOrientation
+        switch interfaceOrientation {
+        case .portrait:
+            videoOrientation = .portrait
+        case .landscapeLeft:
+            videoOrientation = .landscapeLeft
+        case .landscapeRight:
+            videoOrientation = .landscapeRight
+        case .portraitUpsideDown:
+            videoOrientation = .portraitUpsideDown
+        default:
+            videoOrientation = .portrait
+        }
+
+        connection.videoOrientation = videoOrientation
+
+        // Update the frame of the preview layer to match the new bounds.
+        if let view = webView {
+            videoPreviewLayer.frame = view.bounds
+        }
+    }
+}

package/ios/Sources/CameraViewPlugin/CameraViewManager+VideoDataOutput.swift

@@ -31,6 +31,21 @@ extension CameraViewManager: AVCaptureVideoDataOutputSampleBufferDelegate {
         }
 
         captureSession.addOutput(avVideoDataOutput)
+        deferStart(of: avVideoDataOutput)
+    }
+
+    /// Atomically consumes the snapshot completion handler and cancels its
+    /// timeout. Returns the handler to the caller that wins the race (frame
+    /// delivery or timeout) and `nil` to any later caller.
+    internal func consumeSnapshotHandler() -> ((UIImage?, Error?) -> Void)? {
+        captureHandlerLock.lock()
+        defer { captureHandlerLock.unlock() }
+
+        guard let handler = snapshotCompletionHandler else { return nil }
+        snapshotCompletionHandler = nil
+        snapshotTimeoutWorkItem?.cancel()
+        snapshotTimeoutWorkItem = nil
+        return handler
     }
 
     /// Capture a snapshot from the camera feed using the shared Metal-backed CIContext.
@@ -39,12 +54,12 @@ extension CameraViewManager: AVCaptureVideoDataOutputSampleBufferDelegate {
         _ output: AVCaptureOutput, didOutput sampleBuffer: CMSampleBuffer,
         from connection: AVCaptureConnection
     ) {
-        // Only process if we have a completion handler set
-        guard let completionHandler = snapshotCompletionHandler else { return }
-
-        // Clear the completion handler to ensure we only capture one frame
-        snapshotCompletionHandler = nil
+        // Atomically claim the snapshot; returns nil if it was already consumed
+        // (e.g. by the timeout) or if no capture is in flight. This also cancels
+        // the timeout so the promise settles exactly once.
+        guard let completionHandler = consumeSnapshotHandler() else { return }
 
+        // Stop delivery to ensure we only capture one frame.
         avVideoDataOutput.setSampleBufferDelegate(nil, queue: nil)
 
         guard let imageBuffer = CMSampleBufferGetImageBuffer(sampleBuffer) else {
@@ -68,12 +83,9 @@ extension CameraViewManager: AVCaptureVideoDataOutputSampleBufferDelegate {
         _ output: AVCaptureOutput, didDrop sampleBuffer: CMSampleBuffer,
         from connection: AVCaptureConnection
     ) {
-        // If we have a completion handler and a frame was dropped, report the error
-        if let completionHandler = snapshotCompletionHandler {
-            snapshotCompletionHandler = nil
-            avVideoDataOutput.setSampleBufferDelegate(nil, queue: nil)
-
-            completionHandler(nil, CameraError.frameCaptureError)
-        }
+        // With `alwaysDiscardsLateVideoFrames` enabled a transient dropped frame
+        // is normal and must not fail the capture. Keep the delegate installed
+        // and wait for the next delivered frame; the timeout guards against the
+        // case where no frame ever arrives.
     }
 }

package/ios/Sources/CameraViewPlugin/CameraViewManager+VideoRecording.swift

@@ -29,14 +29,7 @@ extension CameraViewManager: AVCaptureFileOutputRecordingDelegate {
             guard let self = self else { return }
 
             guard self.captureSession.isRunning else {
-                // Session may be temporarily stopped (e.g. iOS stops the capture session
-                // when reconfiguring audio after a microphone permission grant). Wait for
-                // it to resume and retry rather than failing immediately.
-                self.waitForSessionThenStartRecording(
-                    enableAudio: enableAudio,
-                    videoQuality: videoQuality,
-                    completion: completion
-                )
+                DispatchQueue.main.async { completion(CameraError.sessionNotRunning) }
                 return
             }
 
@@ -64,6 +57,11 @@ extension CameraViewManager: AVCaptureFileOutputRecordingDelegate {
                     return
                 }
                 self.captureSession.addOutput(self.avMovieOutput)
+
+                // Never deferred: this output is added because a recording is
+                // starting right now, and file outputs default to deferred for
+                // host apps linked against the iOS 26 SDK.
+                self.deferStart(of: self.avMovieOutput, false)
             }
 
             // Add audio input if requested
@@ -83,11 +81,8 @@ extension CameraViewManager: AVCaptureFileOutputRecordingDelegate {
             self.captureSession.commitConfiguration()
 
             // Set orientation on the movie output connection
-            if let connection = self.avMovieOutput.connection(with: .video),
-               let previewConnection = self.videoPreviewLayer.connection {
-                if connection.isVideoOrientationSupported {
-                    connection.videoOrientation = previewConnection.videoOrientation
-                }
+            if let connection = self.avMovieOutput.connection(with: .video) {
+                self.applyCaptureOrientation(to: connection)
                 if connection.isVideoMirroringSupported {
                     connection.isVideoMirrored = self.currentCameraDevice?.position == .front
                 }
@@ -156,6 +151,11 @@ extension CameraViewManager: AVCaptureFileOutputRecordingDelegate {
             self.restoreSessionPreset()
             self.recordingWithAudio = false
             self.captureSession.commitConfiguration()
+
+            // Restoring the pre-recording preset may change the active format,
+            // which resets the photo output's maxPhotoDimensions; re-apply the
+            // session's capture-resolution hint.
+            self.applyConfiguredMaxPhotoDimensions()
         }
 
         if let error = error {
@@ -172,65 +172,6 @@ extension CameraViewManager: AVCaptureFileOutputRecordingDelegate {
 
     // MARK: - Private Helpers
 
-    /// Waits for the capture session to start running, then retries `startRecording`.
-    ///
-    /// Called when `startRecording` finds the session temporarily stopped (e.g. after
-    /// iOS reconfigures audio following a first-time microphone permission grant).
-    /// Both the notification path and the timeout path serialize through `sessionQueue`,
-    /// so `handled` is accessed on a single serial queue and needs no additional lock.
-    private func waitForSessionThenStartRecording(
-        enableAudio: Bool,
-        videoQuality: VideoRecordingQuality,
-        completion: @escaping (Error?) -> Void
-    ) {
-        let sessionQueue = self.sessionQueue
-        // Keep the token so we can remove the observer on success and timeout paths.
-        var observerToken: NSObjectProtocol?
-        var handled = false
-
-        observerToken = NotificationCenter.default.addObserver(
-            forName: .AVCaptureSessionDidStartRunning,
-            object: captureSession,
-            queue: nil
-        ) { [weak self] _ in
-            sessionQueue.async {
-                guard !handled else { return }
-                handled = true
-                if let token = observerToken {
-                    NotificationCenter.default.removeObserver(token)
-                    observerToken = nil
-                }
-                guard let self = self else { return }
-                self.startRecording(
-                    enableAudio: enableAudio,
-                    videoQuality: videoQuality,
-                    completion: completion
-                )
-            }
-        }
-
-        // Timeout: if the session hasn't restarted within 2 seconds, give up.
-        sessionQueue.asyncAfter(deadline: .now() + 2.0) { [weak self] in
-            guard !handled else { return }
-            handled = true
-            if let token = observerToken {
-                NotificationCenter.default.removeObserver(token)
-                observerToken = nil
-            }
-            guard let self = self else { return }
-            // One final check in case the session started just as we timed out.
-            if self.captureSession.isRunning {
-                self.startRecording(
-                    enableAudio: enableAudio,
-                    videoQuality: videoQuality,
-                    completion: completion
-                )
-            } else {
-                DispatchQueue.main.async { completion(CameraError.sessionNotRunning) }
-            }
-        }
-    }
-
     /// Resolves the appropriate AVCaptureSession.Preset for the given VideoRecordingQuality,
     private func resolveRecordingPreset(for videoQuality: VideoRecordingQuality) -> AVCaptureSession.Preset {
         let preferredPresets: [AVCaptureSession.Preset]
@@ -276,7 +217,15 @@ extension CameraViewManager: AVCaptureFileOutputRecordingDelegate {
             (input as? AVCaptureDeviceInput)?.device.hasMediaType(.audio) == true
         }
 
-        guard !hasAudioInput else { return }
+        guard !hasAudioInput else {
+            // An audio input is already attached (e.g. a leftover from a
+            // previous recording). Recording will still include audio, so
+            // `recordingWithAudio` must reflect that or the completion
+            // delegate won't remove the input afterwards, leaving it
+            // stray-attached to the session.
+            recordingWithAudio = true
+            return
+        }
 
         guard let microphone = AVCaptureDevice.default(for: .audio) else {
             throw CameraError.audioDeviceUnavailable