@kaeawc/auto-mobile 0.0.44 → 0.0.45

package/README.md

@@ -8,9 +8,9 @@
 ![Platform: macOS](https://img.shields.io/badge/platform-macOS-lightgrey)
 ![Platform: Linux](https://img.shields.io/badge/platform-Linux-lightgrey)
 
-![TypeScript tests: 7,202](https://img.shields.io/badge/TypeScript_tests-7%2C202-3178C6)
-![Kotlin tests: 1,448](https://img.shields.io/badge/Kotlin_tests-1%2C448-7F52FF)
-![Swift tests: 722](https://img.shields.io/badge/Swift_tests-722-F05138)
+![TypeScript tests: 8,345](https://img.shields.io/badge/TypeScript_tests-8%2C345-3178C6)
+![Kotlin tests: 1,707](https://img.shields.io/badge/Kotlin_tests-1%2C707-7F52FF)
+![Swift tests: 806](https://img.shields.io/badge/Swift_tests-806-F05138)
 ![Kotlin coverage](https://img.shields.io/endpoint?url=https://kaeawc.github.io/auto-mobile/kotlin-coverage-badge.json)
 ![Swift coverage](https://img.shields.io/endpoint?url=https://kaeawc.github.io/auto-mobile/swift-coverage-badge.json)
 

package/README.md.backup

@@ -8,9 +8,9 @@
 ![Platform: macOS](https://img.shields.io/badge/platform-macOS-lightgrey)
 ![Platform: Linux](https://img.shields.io/badge/platform-Linux-lightgrey)
 
-![TypeScript tests: 7,202](https://img.shields.io/badge/TypeScript_tests-7%2C202-3178C6)
-![Kotlin tests: 1,448](https://img.shields.io/badge/Kotlin_tests-1%2C448-7F52FF)
-![Swift tests: 722](https://img.shields.io/badge/Swift_tests-722-F05138)
+![TypeScript tests: 8,345](https://img.shields.io/badge/TypeScript_tests-8%2C345-3178C6)
+![Kotlin tests: 1,707](https://img.shields.io/badge/Kotlin_tests-1%2C707-7F52FF)
+![Swift tests: 806](https://img.shields.io/badge/Swift_tests-806-F05138)
 ![Kotlin coverage](https://img.shields.io/endpoint?url=https://kaeawc.github.io/auto-mobile/kotlin-coverage-badge.json)
 ![Swift coverage](https://img.shields.io/endpoint?url=https://kaeawc.github.io/auto-mobile/swift-coverage-badge.json)
 

package/dist/ios/screen-capture/Package.swift

@@ -0,0 +1,35 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "ScreenCaptureHelper",
+    platforms: [
+        .macOS(.v14),
+    ],
+    products: [
+        .executable(
+            name: "screen-capture-helper",
+            targets: ["ScreenCaptureHelper"]
+        ),
+        .library(
+            name: "ScreenCaptureCore",
+            targets: ["ScreenCaptureCore"]
+        ),
+    ],
+    targets: [
+        .target(
+            name: "ScreenCaptureCore",
+            path: "Sources/ScreenCaptureCore"
+        ),
+        .executableTarget(
+            name: "ScreenCaptureHelper",
+            dependencies: ["ScreenCaptureCore"],
+            path: "Sources/ScreenCaptureHelper"
+        ),
+        .testTarget(
+            name: "ScreenCaptureCoreTests",
+            dependencies: ["ScreenCaptureCore"],
+            path: "Tests/ScreenCaptureCoreTests"
+        ),
+    ]
+)

package/dist/ios/screen-capture/Sources/ScreenCaptureCore/AudioPcm16Encoder.swift

@@ -0,0 +1,22 @@
+import Foundation
+
+/// Converts the Float32 little-endian PCM emitted by ScreenCaptureKit into
+/// signed little-endian PCM16 for the shared WebRTC PCMU packetizer.
+public enum AudioPcm16Encoder {
+    public static func encodeFloat32LE(_ input: Data) -> Data? {
+        guard input.count.isMultiple(of: MemoryLayout<Float>.size) else { return nil }
+
+        var output = Data(count: input.count / 2)
+        input.withUnsafeBytes { source in
+            output.withUnsafeMutableBytes { destination in
+                guard let sourceBase = source.baseAddress, let destinationBase = destination.baseAddress else { return }
+                for index in 0..<(input.count / MemoryLayout<Float>.size) {
+                    let float = sourceBase.advanced(by: index * 4).loadUnaligned(as: Float.self)
+                    let sample = Int16(max(-1, min(1, float)) * Float(Int16.max))
+                    destinationBase.advanced(by: index * 2).storeBytes(of: sample.littleEndian, as: Int16.self)
+                }
+            }
+        }
+        return output
+    }
+}

package/dist/ios/screen-capture/Sources/ScreenCaptureCore/CommandLineOptions.swift

@@ -0,0 +1,152 @@
+import Foundation
+
+/// Parsed CLI arguments for the screen-capture helper.
+public struct CommandLineOptions: Equatable {
+    public enum Mode: Equatable {
+        case listDevices
+        case capture(deviceID: String?)
+        case listSimulators
+        case captureSimulator(windowID: UInt32, fps: Int, audio: Bool)
+        case help
+    }
+
+    public let mode: Mode
+
+    public init(mode: Mode) {
+        self.mode = mode
+    }
+
+    public enum ParseError: Error, Equatable {
+        case missingValue(flag: String)
+        case unknownArgument(String)
+        case invalidValue(flag: String, value: String)
+        case conflictingFlags(String)
+    }
+
+    public static let defaultSimulatorFPS = 5
+    public static let minSimulatorFPS = 5
+    public static let maxSimulatorFPS = 60
+
+    public static func parse(_ arguments: [String]) throws -> CommandLineOptions {
+        var iterator = arguments.makeIterator()
+        _ = iterator.next()
+
+        var listDevices = false
+        var deviceID: String?
+        var listSimulators = false
+        var simulatorWindowID: UInt32?
+        var simulatorFPS: Int?
+        var audio = false
+        var help = false
+
+        while let arg = iterator.next() {
+            switch arg {
+            case "--list-devices":
+                listDevices = true
+            case "--device-id":
+                guard let value = iterator.next() else {
+                    throw ParseError.missingValue(flag: arg)
+                }
+                deviceID = value
+            case "--list-simulators":
+                listSimulators = true
+            case "--simulator-window":
+                guard let value = iterator.next() else {
+                    throw ParseError.missingValue(flag: arg)
+                }
+                guard let parsed = UInt32(value) else {
+                    throw ParseError.invalidValue(flag: arg, value: value)
+                }
+                simulatorWindowID = parsed
+            case "--simulator-fps":
+                guard let value = iterator.next() else {
+                    throw ParseError.missingValue(flag: arg)
+                }
+                guard
+                    let parsed = Int(value),
+                    parsed >= minSimulatorFPS,
+                    parsed <= maxSimulatorFPS
+                else {
+                    throw ParseError.invalidValue(flag: arg, value: value)
+                }
+                simulatorFPS = parsed
+            case "--audio":
+                audio = true
+            case "-h", "--help":
+                help = true
+            default:
+                throw ParseError.unknownArgument(arg)
+            }
+        }
+
+        if help {
+            return CommandLineOptions(mode: .help)
+        }
+
+        let modeFlagCount = [
+            listDevices,
+            listSimulators,
+            simulatorWindowID != nil,
+            deviceID != nil,
+        ].filter { $0 }.count
+        if modeFlagCount > 1 {
+            throw ParseError.conflictingFlags(
+                "choose one of --list-devices, --device-id, --list-simulators, --simulator-window"
+            )
+        }
+
+        if simulatorFPS != nil && simulatorWindowID == nil {
+            throw ParseError.conflictingFlags(
+                "--simulator-fps requires --simulator-window"
+            )
+        }
+        if audio && simulatorWindowID == nil {
+            throw ParseError.conflictingFlags("--audio requires --simulator-window")
+        }
+
+        if listDevices {
+            return CommandLineOptions(mode: .listDevices)
+        }
+        if listSimulators {
+            return CommandLineOptions(mode: .listSimulators)
+        }
+        if let windowID = simulatorWindowID {
+            return CommandLineOptions(
+                mode: .captureSimulator(
+                    windowID: windowID,
+                    fps: simulatorFPS ?? defaultSimulatorFPS,
+                    audio: audio
+                )
+            )
+        }
+        return CommandLineOptions(mode: .capture(deviceID: deviceID))
+    }
+
+    public static let helpText = """
+    screen-capture-helper — AutoMobile iOS screen-capture helper
+
+    USAGE:
+        screen-capture-helper [--device-id <id>]
+        screen-capture-helper --list-devices
+        screen-capture-helper --simulator-window <windowID> [--simulator-fps <n>] [--audio]
+        screen-capture-helper --list-simulators
+
+    DEVICE OPTIONS (USB-connected iOS devices via AVFoundation):
+        --list-devices          Emit discovered devices as JSON to stdout and exit.
+        --device-id <id>        uniqueID of the device to capture. If omitted,
+                                the first muxed external device is used.
+
+    SIMULATOR OPTIONS (macOS iOS Simulator windows via ScreenCaptureKit):
+        --list-simulators       Emit discovered simulator windows as JSON.
+        --simulator-window <n>  CGWindowID of the simulator window to capture.
+        --simulator-fps <n>     Target frame rate (5-60, default 5). Higher
+                                values waste CPU for typical MCP workloads.
+        --audio                 Capture Simulator window audio as 8 kHz mono PCM16LE.
+
+        -h, --help              Show this help.
+
+    Frames are written to stdout: 16-byte little-endian header
+    (width, height, bytesPerRow, timestampMs) followed by
+    height * bytesPerRow bytes of BGRA pixel data.
+    """
+}

package/dist/ios/screen-capture/Sources/ScreenCaptureCore/DeviceInfo.swift

@@ -0,0 +1,25 @@
+import Foundation
+
+/// Serializable description of a discovered capture device. Emitted to stdout
+/// in JSON form when `screen-capture-helper --list-devices` is invoked.
+public struct DeviceInfo: Codable, Equatable {
+    public let uniqueID: String
+    public let localizedName: String
+    public let modelID: String
+    public let manufacturer: String
+
+    public init(uniqueID: String, localizedName: String, modelID: String, manufacturer: String) {
+        self.uniqueID = uniqueID
+        self.localizedName = localizedName
+        self.modelID = modelID
+        self.manufacturer = manufacturer
+    }
+}
+
+public struct DeviceListResponse: Codable, Equatable {
+    public let devices: [DeviceInfo]
+
+    public init(devices: [DeviceInfo]) {
+        self.devices = devices
+    }
+}

package/dist/ios/screen-capture/Sources/ScreenCaptureCore/FrameProtocol.swift

@@ -0,0 +1,113 @@
+import Foundation
+
+/// Binary frame protocol matching docs/design-docs/plat/ios/screen-streaming.md.
+///
+/// Wire format (header = 24 bytes, little-endian UInt32):
+///
+///     ┌─────────┬─────────────┬──────────┬───────────┬─────────────┬─────────────┐
+///     │ magic(4)│ checksum(4) │ width(4) │ height(4) │ bytesPerRow │ timestampMs │
+///     └─────────┴─────────────┴──────────┴───────────┴─────────────┴─────────────┘
+///
+/// Followed by `height * bytesPerRow` bytes of BGRA pixel data. `magic` is a
+/// fixed sync marker ("AMF1" on the wire) and `checksum` is a CRC-32 (IEEE) over
+/// the 16 field bytes that follow it, so the decoder can recover frame
+/// boundaries deterministically after corruption (issue #4270). The TypeScript
+/// decoder (`src/features/screen-stream/frameProtocol.ts`) must agree byte for
+/// byte; the shared CRC-32 check vector pins that on both sides.
+public enum FrameProtocol {
+    public static let headerSize = 24
+    /// Sync marker; on the wire the bytes read "AMF1".
+    public static let magic: UInt32 = 0x3146_4D41
+    /// Offset where the checksummed field bytes begin.
+    static let fieldsOffset = 8
+    public static let audioSampleRate: UInt32 = 8_000
+    public static let audioChannelCount: UInt32 = 1
+
+    public struct Header: Equatable {
+        public let width: UInt32
+        public let height: UInt32
+        public let bytesPerRow: UInt32
+        public let timestampMs: UInt32
+
+        public init(width: UInt32, height: UInt32, bytesPerRow: UInt32, timestampMs: UInt32) {
+            self.width = width
+            self.height = height
+            self.bytesPerRow = bytesPerRow
+            self.timestampMs = timestampMs
+        }
+    }
+
+    public static func encodeHeader(_ header: Header) -> Data {
+        var data = Data(count: headerSize)
+        data.withUnsafeMutableBytes { ptr in
+            // `data` was allocated with `Data(count: headerSize)` (headerSize > 0), so
+            // the buffer is non-empty and baseAddress is non-nil. All offsets are
+            // multiples of 4, so the aligned stores are valid.
+            let base = ptr.baseAddress!  // swiftlint:disable:this force_unwrapping
+            base.storeBytes(of: magic.littleEndian, as: UInt32.self)
+            base.advanced(by: 8).storeBytes(of: header.width.littleEndian, as: UInt32.self)
+            base.advanced(by: 12).storeBytes(of: header.height.littleEndian, as: UInt32.self)
+            base.advanced(by: 16).storeBytes(of: header.bytesPerRow.littleEndian, as: UInt32.self)
+            base.advanced(by: 20).storeBytes(of: header.timestampMs.littleEndian, as: UInt32.self)
+        }
+        let checksum = crc32(data.subdata(in: fieldsOffset..<headerSize))
+        data.withUnsafeMutableBytes { ptr in
+            let base = ptr.baseAddress!  // swiftlint:disable:this force_unwrapping
+            base.advanced(by: 4).storeBytes(of: checksum.littleEndian, as: UInt32.self)
+        }
+        return data
+    }
+
+    public static func encodeAudioHeader(payloadLength: Int) -> Data {
+        encodeHeader(Header(
+            width: 0,
+            height: audioSampleRate,
+            bytesPerRow: audioChannelCount,
+            timestampMs: UInt32(payloadLength)
+        ))
+    }
+
+    /// Decode + validate a header. Returns nil when the marker or checksum does
+    /// not match — i.e. these bytes are not a real frame boundary.
+    public static func decodeHeader(_ data: Data) -> Header? {
+        guard data.count >= headerSize else { return nil }
+        return data.withUnsafeBytes { ptr -> Header? in
+            // Guarded above by `data.count >= headerSize` (headerSize > 0), so the
+            // buffer is non-empty and baseAddress is non-nil. `loadUnaligned` has no
+            // alignment requirement, so a header at an odd address is safe (#3627).
+            let base = ptr.baseAddress!  // swiftlint:disable:this force_unwrapping
+            let marker = UInt32(littleEndian: base.loadUnaligned(as: UInt32.self))
+            guard marker == magic else { return nil }
+            let stored = UInt32(littleEndian: base.advanced(by: 4).loadUnaligned(as: UInt32.self))
+            let fields = Data(bytes: base.advanced(by: fieldsOffset), count: headerSize - fieldsOffset)
+            guard stored == crc32(fields) else { return nil }
+            return Header(
+                width: UInt32(littleEndian: base.advanced(by: 8).loadUnaligned(as: UInt32.self)),
+                height: UInt32(littleEndian: base.advanced(by: 12).loadUnaligned(as: UInt32.self)),
+                bytesPerRow: UInt32(littleEndian: base.advanced(by: 16).loadUnaligned(as: UInt32.self)),
+                timestampMs: UInt32(littleEndian: base.advanced(by: 20).loadUnaligned(as: UInt32.self))
+            )
+        }
+    }
+
+    private static let crc32Table: [UInt32] = {
+        (0..<256).map { index -> UInt32 in
+            var remainder = UInt32(index)
+            for _ in 0..<8 {
+                remainder = (remainder & 1) != 0 ? 0xEDB8_8320 ^ (remainder >> 1) : remainder >> 1
+            }
+            return remainder
+        }
+    }()
+
+    /// CRC-32 (IEEE 802.3, reflected, polynomial 0xEDB88320) — the standard CRC
+    /// used by zip/gzip/PNG. Implemented here because Foundation ships no CRC-32
+    /// primitive and the TypeScript decoder must produce an identical checksum.
+    public static func crc32(_ data: Data) -> UInt32 {
+        var crc: UInt32 = 0xFFFF_FFFF
+        for byte in data {
+            crc = (crc >> 8) ^ crc32Table[Int((crc ^ UInt32(byte)) & 0xFF)]
+        }
+        return crc ^ 0xFFFF_FFFF
+    }
+}

package/dist/ios/screen-capture/Sources/ScreenCaptureCore/FrameWriter.swift

@@ -0,0 +1,62 @@
+import Foundation
+
+/// Sink that receives encoded frames. Implementations write to stdout, a file,
+/// a Unix socket, or an in-memory buffer for tests.
+public protocol FrameSink: AnyObject {
+    func write(_ data: Data)
+}
+
+/// Writes encoded frame header + BGRA payload to a `FrameSink`.
+public final class FrameWriter {
+    private let sink: FrameSink
+    private let startTime: Date
+
+    public init(sink: FrameSink, startTime: Date = Date()) {
+        self.sink = sink
+        self.startTime = startTime
+    }
+
+    public func write(
+        width: Int,
+        height: Int,
+        bytesPerRow: Int,
+        baseAddress: UnsafeRawPointer,
+        timestamp: Date = Date()
+    ) {
+        let elapsedMs = max(0, timestamp.timeIntervalSince(startTime) * 1000)
+        let header = FrameProtocol.Header(
+            width: UInt32(width),
+            height: UInt32(height),
+            bytesPerRow: UInt32(bytesPerRow),
+            timestampMs: UInt32(truncatingIfNeeded: UInt64(elapsedMs))
+        )
+        sink.write(FrameProtocol.encodeHeader(header))
+        // bytesNoCopy avoids copying the pixel buffer into a transient Data.
+        // The caller (DeviceCaptureSession.captureOutput) holds the underlying
+        // CVPixelBuffer locked for the duration of this synchronous write.
+        let payload = Data(
+            bytesNoCopy: UnsafeMutableRawPointer(mutating: baseAddress),
+            count: bytesPerRow * height,
+            deallocator: .none
+        )
+        sink.write(payload)
+    }
+
+    public func writeAudio(pcm16le: Data) {
+        sink.write(FrameProtocol.encodeAudioHeader(payloadLength: pcm16le.count))
+        sink.write(pcm16le)
+    }
+}
+
+/// Sink that writes to a `FileHandle` (e.g. `FileHandle.standardOutput`).
+public final class FileHandleFrameSink: FrameSink {
+    private let handle: FileHandle
+
+    public init(handle: FileHandle) {
+        self.handle = handle
+    }
+
+    public func write(_ data: Data) {
+        handle.write(data)
+    }
+}

package/dist/ios/screen-capture/Sources/ScreenCaptureCore/SimulatorWindowInfo.swift

@@ -0,0 +1,51 @@
+import Foundation
+
+/// Serializable description of an iOS Simulator window discovered via
+/// ScreenCaptureKit. Emitted as JSON by `screen-capture-helper --list-simulators`.
+public struct SimulatorWindowInfo: Codable, Equatable {
+    public let windowID: UInt32
+    public let title: String?
+    public let applicationName: String
+    public let bundleIdentifier: String
+    public let processID: Int32
+    public let width: Int
+    public let height: Int
+
+    public init(
+        windowID: UInt32,
+        title: String?,
+        applicationName: String,
+        bundleIdentifier: String,
+        processID: Int32,
+        width: Int,
+        height: Int
+    ) {
+        self.windowID = windowID
+        self.title = title
+        self.applicationName = applicationName
+        self.bundleIdentifier = bundleIdentifier
+        self.processID = processID
+        self.width = width
+        self.height = height
+    }
+}
+
+public struct SimulatorWindowListResponse: Codable, Equatable {
+    public let windows: [SimulatorWindowInfo]
+
+    public init(windows: [SimulatorWindowInfo]) {
+        self.windows = windows
+    }
+}
+
+/// Bundle identifier of the iOS Simulator host application on macOS.
+public let simulatorBundleIdentifier = "com.apple.iphonesimulator"
+
+/// ScreenCaptureKit cannot isolate a single Simulator window's audio from the
+/// Simulator host application, so audio capture is safe only with one window.
+public enum SimulatorAudioCaptureAvailability {
+    public static func errorMessage(for visibleSimulatorWindows: [SimulatorWindowInfo]) -> String? {
+        guard visibleSimulatorWindows.count > 1 else { return nil }
+        return "iOS Simulator audio capture requires exactly one visible Simulator window because ScreenCaptureKit cannot isolate audio to a selected Simulator window. Close other Simulator windows and try again."
+    }
+}

package/dist/ios/screen-capture/Sources/ScreenCaptureHelper/AudioSampleBuffer.swift

@@ -0,0 +1,41 @@
+import AudioToolbox
+import CoreMedia
+import Foundation
+import ScreenCaptureCore
+
+/// ScreenCaptureKit is configured for 8 kHz mono output. Convert its common
+/// Float32 or signed-16-bit linear PCM representation to signed PCM16LE.
+func pcm16leAudio(sampleBuffer: CMSampleBuffer) -> Data? {
+    guard let format = CMSampleBufferGetFormatDescription(sampleBuffer),
+          let asbd = CMAudioFormatDescriptionGetStreamBasicDescription(format)?.pointee,
+          asbd.mSampleRate == 8_000,
+          asbd.mChannelsPerFrame == 1,
+          asbd.mFormatID == kAudioFormatLinearPCM
+    else { return nil }
+
+    var audioBufferList = AudioBufferList()
+    var blockBuffer: CMBlockBuffer?
+    let result = CMSampleBufferGetAudioBufferListWithRetainedBlockBuffer(
+        sampleBuffer,
+        bufferListSizeNeededOut: nil,
+        bufferListOut: &audioBufferList,
+        bufferListSize: MemoryLayout<AudioBufferList>.size,
+        blockBufferAllocator: nil,
+        blockBufferMemoryAllocator: nil,
+        flags: 0,
+        blockBufferOut: &blockBuffer
+    )
+    guard result == noErr, let input = audioBufferList.mBuffers.mData else { return nil }
+
+    let sampleCount = CMSampleBufferGetNumSamples(sampleBuffer)
+    if asbd.mBitsPerChannel == 16 {
+        return Data(bytes: input, count: sampleCount * MemoryLayout<Int16>.size)
+    }
+    if asbd.mBitsPerChannel == 32,
+       (asbd.mFormatFlags & kAudioFormatFlagIsFloat) != 0 {
+        return AudioPcm16Encoder.encodeFloat32LE(
+            Data(bytes: input, count: sampleCount * MemoryLayout<Float>.size)
+        )
+    }
+    return nil
+}

package/dist/ios/screen-capture/Sources/ScreenCaptureHelper/CMIOSystem.swift

@@ -0,0 +1,26 @@
+import CoreMediaIO
+import Foundation
+
+/// Enables iOS device screen-capture devices to appear in AVFoundation. This
+/// is the same toggle QuickTime Player flips when you select an iOS device.
+///
+/// Per design doc: rapidly toggling this property can stall device discovery
+/// for up to 60 seconds, so we only flip it to `true` and leave it.
+enum CMIOSystem {
+    static func enableScreenCaptureDevices() {
+        var prop = CMIOObjectPropertyAddress(
+            mSelector: CMIOObjectPropertySelector(kCMIOHardwarePropertyAllowScreenCaptureDevices),
+            mScope: CMIOObjectPropertyScope(kCMIOObjectPropertyScopeGlobal),
+            mElement: CMIOObjectPropertyElement(kCMIOObjectPropertyElementMain)
+        )
+        var allow: UInt32 = 1
+        CMIOObjectSetPropertyData(
+            CMIOObjectID(kCMIOObjectSystemObject),
+            &prop,
+            0,
+            nil,
+            UInt32(MemoryLayout<UInt32>.size),
+            &allow
+        )
+    }
+}

package/dist/ios/screen-capture/Sources/ScreenCaptureHelper/DeviceCaptureSession.swift

@@ -0,0 +1,117 @@
+import AVFoundation
+import CoreVideo
+import Foundation
+import ScreenCaptureCore
+
+/// Wraps an `AVCaptureSession` configured to deliver BGRA frames from an iOS
+/// device to a `FrameWriter`.
+final class DeviceCaptureSession: NSObject, AVCaptureVideoDataOutputSampleBufferDelegate {
+    private let session = AVCaptureSession()
+    private let output = AVCaptureVideoDataOutput()
+    private let writer: FrameWriter
+    private let onFatalError: (Error) -> Void
+    private let queue = DispatchQueue(label: "automobile.screen-capture.frames")
+    private var observers: [NSObjectProtocol] = []
+    private var stopping = false
+
+    init(writer: FrameWriter, onFatalError: @escaping (Error) -> Void) {
+        self.writer = writer
+        self.onFatalError = onFatalError
+    }
+
+    deinit {
+        removeObservers()
+    }
+
+    func start(device: AVCaptureDevice) throws {
+        let input = try AVCaptureDeviceInput(device: device)
+
+        session.beginConfiguration()
+        guard session.canAddInput(input) else {
+            session.commitConfiguration()
+            throw CaptureError.couldNotAddInput
+        }
+        session.addInput(input)
+        output.alwaysDiscardsLateVideoFrames = true
+        output.videoSettings = [
+            kCVPixelBufferPixelFormatTypeKey as String: kCVPixelFormatType_32BGRA
+        ]
+        output.setSampleBufferDelegate(self, queue: queue)
+        guard session.canAddOutput(output) else {
+            session.commitConfiguration()
+            throw CaptureError.couldNotAddOutput
+        }
+        session.addOutput(output)
+        session.commitConfiguration()
+        installObservers()
+        session.startRunning()
+        guard session.isRunning else {
+            throw CaptureError.didNotStart
+        }
+    }
+
+    func stop() {
+        stopping = true
+        removeObservers()
+        session.stopRunning()
+    }
+
+    private func installObservers() {
+        let center = NotificationCenter.default
+        observers = [
+            center.addObserver(
+                forName: AVCaptureSession.runtimeErrorNotification,
+                object: session,
+                queue: .main
+            ) { [weak self] notification in
+                let error = notification.userInfo?[AVCaptureSessionErrorKey] as? Error
+                    ?? CaptureError.runtimeFailure
+                self?.reportFatal(error)
+            },
+            center.addObserver(
+                forName: AVCaptureSession.wasInterruptedNotification,
+                object: session,
+                queue: .main
+            ) { [weak self] _ in
+                self?.reportFatal(CaptureError.interrupted)
+            },
+        ]
+    }
+
+    private func removeObservers() {
+        let center = NotificationCenter.default
+        observers.forEach(center.removeObserver)
+        observers = []
+    }
+
+    private func reportFatal(_ error: Error) {
+        guard !stopping else { return }
+        onFatalError(error)
+    }
+
+    private enum CaptureError: LocalizedError {
+        case couldNotAddInput
+        case couldNotAddOutput
+        case didNotStart
+        case runtimeFailure
+        case interrupted
+
+        var errorDescription: String? {
+            switch self {
+            case .couldNotAddInput: return "Unable to add the iOS capture input."
+            case .couldNotAddOutput: return "Unable to add the iOS capture output."
+            case .didNotStart: return "The iOS capture session did not start."
+            case .runtimeFailure: return "The iOS capture session reported a runtime failure."
+            case .interrupted: return "The iOS capture session was interrupted."
+            }
+        }
+    }
+
+    func captureOutput(
+        _ output: AVCaptureOutput,
+        didOutput sampleBuffer: CMSampleBuffer,
+        from connection: AVCaptureConnection
+    ) {
+        writer.write(sampleBuffer: sampleBuffer)
+    }
+}