SPB Git

Repository Public

RecordingEngine.swift 20.0 KB 409 lines swift

1// SP Lecture Studio — LectureCapture2// File: Packages/LectureCapture/Sources/RecordingEngine.swift3// Description: Capture coordinator: clock, segmented audio, event stream, pause/resume with pre-roll, automatic policies, atomic checkpoints.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai7import Foundation8import AVFoundation9import LectureCore10import LectureStorage1112public enum RecordingState: String, Sendable { case idle, recording, paused }1314public enum SystemWarning: Sendable, Hashable {15    case lowDisk(availableBytes: Int64)16    case criticalDisk(availableBytes: Int64)17    case thermal(serious: Bool)18    case lowBattery(percent: Int)19    case audioWriteFailed(String)20}2122public struct RecordingConfiguration: Sendable {23    public var segmentSeconds: Double = 3024    public var policy = AutoPausePolicy()25    /// Below this free space a warning is raised.26    public var lowDiskBytes: Int64 = 1_000_000_00027    /// Below this free space the recording is paused and everything is finalized (nothing is lost).28    public var criticalDiskBytes: Int64 = 200_000_00029    public init() {}30}3132/// Callbacks are invoked on the main queue.33public struct RecordingCallbacks {34    public var stateChanged: (RecordingState) -> Void = { _ in }35    /// Input level: RMS in dBFS and peak 0…1, about 20 times per second (also while paused, for the meter).36    public var level: (Double, Float) -> Void = { _, _ in }37    public var auto: (AutoPauseEngine.Output) -> Void = { _ in }38    public var warning: (SystemWarning) -> Void = { _ in }39    public var sourceEvent: (AudioSourceEvent) -> Void = { _ in }40    /// A checkpoint was written (segment finalized, pause, stop).41    public var manifestSaved: (ProjectManifest) -> Void = { _ in }42    public init() {}43}4445public final class RecordingEngine: @unchecked Sendable {46    public let package: ProjectPackage47    public let log: EventLogWriter48    public let clock: RecordingClock49    public var callbacks = RecordingCallbacks()50    /// Receives every captured buffer while recording (used for optional on-device phrase spotting). Called on the audio queue.51    public var bufferTap: ((AVAudioPCMBuffer) -> Void)?52    public private(set) var configuration: RecordingConfiguration5354    private let lock = NSRecursiveLock()55    private var manifest: ProjectManifest56    private var session: RecordingSession?57    private var writer: SegmentedAudioWriter?58    private var source: AudioSource?59    private var _state: RecordingState = .idle60    private var auto: AutoPauseEngine61    private var pauseWall: Date?62    private var pauseReason: PauseReason?63    private var preRoll: [(AVAudioPCMBuffer, TimeInterval)] = []64    private var preRollSeconds = 0.065    private var liveEnvelope = Envelope()66    private var envelopeCarry: [Float] = []67    private var envelopeRate = 0.068    private var lastDiskCheck = Date.distantPast69    private var raisedWarnings = Set<String>()70    private var hostOverride: (() -> TimeInterval)?7172    /// - Parameter audio: nil records without sound (PDF-only mode, or microphone permission denied).73    public init(package: ProjectPackage, manifest: ProjectManifest, log: EventLogWriter, audio: AudioSource?, configuration: RecordingConfiguration = RecordingConfiguration()) {74        self.package = package; self.manifest = manifest; self.log = log; self.source = audio; self.configuration = configuration75        clock = RecordingClock(at: manifest.duration)76        auto = AutoPauseEngine(policy: configuration.policy, now: RecordingClock.hostNow())77    }7879    /// Tests drive time explicitly.80    public func useHostClock(_ provider: @escaping () -> TimeInterval) { hostOverride = provider }81    private func host() -> TimeInterval { hostOverride?() ?? RecordingClock.hostNow() }8283    public var state: RecordingState { lock.lock(); defer { lock.unlock() }; return _state }84    public var currentManifest: ProjectManifest { lock.lock(); defer { lock.unlock() }; return manifest }85    public var hasAudio: Bool { source != nil }86    /// Current timeline position (end of the timeline when idle).87    public var position: MediaTime { clock.now(host: host()) }88    public var sessionElapsed: MediaTime { lock.lock(); defer { lock.unlock() }; return session.map { clock.now(host: host()) - $0.timelineStart } ?? .zero }89    public var envelopeSnapshot: Envelope { lock.lock(); defer { lock.unlock() }; return liveEnvelope }9091    public func updatePolicy(_ policy: AutoPausePolicy) { lock.lock(); configuration.policy = policy; auto.updatePolicy(policy); lock.unlock() }9293    private func setState(_ s: RecordingState) {94        _state = s95        let cb = callbacks.stateChanged96        DispatchQueue.main.async { cb(s) }97    }9899    // MARK: Lifecycle100101    /// Starts a new recording session appended at the end of the timeline.102    public func start(currentPage: Int) throws {103        lock.lock(); defer { lock.unlock() }104        guard _state == .idle else { return }105        var s = RecordingSession(timelineStart: manifest.duration)106        s.audioOnly = false107        session = s108        manifest.sessions.append(s)109        try package.saveManifest(manifest)                       // an open session on disk is what recovery looks for after a crash110        let now = host()111        clock.start(at: s.timelineStart, host: now)112        auto = AutoPauseEngine(policy: configuration.policy, now: now)113        log.append(.sessionStart(id: s.id), at: s.timelineStart)114        log.append(.page(index: currentPage), at: s.timelineStart)115        if let source {116            let w = SegmentedAudioWriter(package: package, session: s, segmentDuration: configuration.segmentSeconds)117            w.onOpen = { [weak self] seg in self?.segmentOpened(seg) }118            w.onFinalize = { [weak self] seg in self?.segmentFinalized(seg) }119            writer = w120            source.onBuffer = { [weak self] buffer, hostTime in self?.ingest(buffer, host: hostTime) }121            source.onEvent = { [weak self] event in self?.handle(event) }122            do { try source.start() } catch {123                // Roll back: no half-open session is left behind.124                manifest.sessions.removeAll { $0.id == s.id }; try? package.saveManifest(manifest)125                session = nil; writer = nil; clock.freeze(at: manifest.duration)126                throw error127            }128        }129        log.flush()130        setState(.recording)131    }132133    public func pause(reason: PauseReason = .manual) {134        lock.lock(); defer { lock.unlock() }135        guard _state == .recording else { return }136        let end = writer?.position137        let t = clock.freeze(at: source != nil ? end : nil, host: host())138        writer?.closeCurrent()                                   // everything captured so far is finalized before waiting139        pauseWall = Date(); pauseReason = reason140        preRoll.removeAll(); preRollSeconds = 0141        log.append(.pause(reason: reason), at: t)142        if reason == .manual { for o in auto.userPaused() { emit(o, at: t) } } else { _ = auto.userPaused() }143        checkpoint()144        setState(.paused)145    }146147    public func resume() {148        lock.lock(); defer { lock.unlock() }149        guard _state == .paused, let s = session else { return }150        let gap = pauseWall.map { Date().timeIntervalSince($0) } ?? 0151        let t = clock.now(host: host())152        log.append(.resume(gapSeconds: (gap * 1000).rounded() / 1000), at: t)153        let now = host()154        if source != nil, let writer {155            // Pre-roll: the last fraction of a second heard before "resume" is kept so that the first syllable is not clipped.156            var first = true157            for (buffer, hostTime) in preRoll {158                guard let start = writer.append(buffer) else { continue }159                accumulateEnvelope(buffer)160                if first { clock.start(at: start, host: hostTime); first = false }161            }162            if first { clock.start(at: writer.position, host: now) }163        } else {164            clock.start(at: max(t, s.timelineStart), host: now)165        }166        preRoll.removeAll(); preRollSeconds = 0167        auto.userResumed(now: now)168        pauseWall = nil; pauseReason = nil169        setState(.recording)170    }171172    /// Stops the session, finalizes every file and writes the manifest. Returns the updated manifest.173    @discardableResult174    public func stop() -> ProjectManifest {175        lock.lock(); defer { lock.unlock() }176        guard _state != .idle, var s = session else { return manifest }177        if _state == .recording {178            let end = writer?.position179            clock.freeze(at: source != nil ? end : nil, host: host())180        }181        source?.stop(); source?.onBuffer = nil; source?.onEvent = nil182        let segs = writer?.finish() ?? []183        let end = clock.now(host: host())184        if let i = manifest.sessions.firstIndex(where: { $0.id == s.id }) { s = manifest.sessions[i] }185        if !segs.isEmpty {186            var others = s.segments.filter { $0.kind != .audio }187            others.append(contentsOf: segs); s.segments = others.sorted { ($0.kind.rawValue, $0.index) < ($1.kind.rawValue, $1.index) }188        }189        s.duration = max(end - s.timelineStart, .zero); s.endedAt = Date()190        if let i = manifest.sessions.firstIndex(where: { $0.id == s.id }) { manifest.sessions[i] = s }191        // An empty session (stopped immediately) leaves no trace.192        if s.duration == .zero && s.segments.isEmpty { manifest.sessions.removeAll { $0.id == s.id } }193        manifest.recomputeDuration()194        log.append(.sessionEnd(id: s.id), at: manifest.duration)195        log.flush()196        flushEnvelope()197        if var existing = package.loadEnvelope(), existing.hop == liveEnvelope.hop {198            // Keep the cached envelope aligned with the timeline (pad if an earlier session had no audio).199            let expected = Int(s.timelineStart.ns / existing.hop.ns)200            if existing.rms.count < expected { existing.rms += [Float](repeating: -120, count: expected - existing.rms.count); existing.peak += [Float](repeating: 0, count: expected - existing.peak.count) }201            if existing.rms.count > expected { existing.rms = Array(existing.rms.prefix(expected)); existing.peak = Array(existing.peak.prefix(expected)) }202            existing.append(liveEnvelope); try? package.saveEnvelope(existing)203        } else if s.timelineStart == .zero { try? package.saveEnvelope(liveEnvelope) }204        try? package.saveManifest(manifest)205        session = nil; writer = nil; liveEnvelope = Envelope(); envelopeCarry = []206        let m = manifest, cb = callbacks.manifestSaved207        DispatchQueue.main.async { cb(m) }208        setState(.idle)209        return manifest210    }211212    // MARK: Events213214    /// Stamps an interaction event with the recording clock and appends it to the log.215    /// While idle, events are stamped at the end of the timeline (annotations made before / after recording).216    @discardableResult217    public func record(_ payload: EventPayload, interaction: Bool = true) -> TimelineEvent {218        let now = host()219        let event = log.append(payload, at: clock.now(host: now))220        if interaction { lock.lock(); auto.noteInteraction(now: now); lock.unlock() }221        return event222    }223224    /// Adds a camera segment produced by the camera recorder to the current session.225    public func attach(cameraSegment: MediaSegment) {226        lock.lock(); defer { lock.unlock() }227        guard let s = session, let i = manifest.sessions.firstIndex(where: { $0.id == s.id }) else { return }228        manifest.sessions[i].segments.removeAll { $0.path == cameraSegment.path }229        manifest.sessions[i].segments.append(cameraSegment)230        log.append(.segment(kind: .camera, file: (cameraSegment.path as NSString).lastPathComponent, index: cameraSegment.index), at: cameraSegment.start)231        checkpoint()232    }233234    public var activeSession: RecordingSession? { lock.lock(); defer { lock.unlock() }; return session }235236    // MARK: Audio path (audio queue)237238    private func ingest(_ buffer: AVAudioPCMBuffer, host hostTime: TimeInterval) {239        lock.lock(); defer { lock.unlock() }240        let (rms, peak) = Self.level(buffer)241        let cb = callbacks.level242        DispatchQueue.main.async { cb(Double(rms), peak) }243        switch _state {244        case .recording:245            guard let writer else { return }246            bufferTap?(buffer)247            if let start = writer.append(buffer) {248                clock.anchor(host: hostTime, timeline: start)249                auto.ingest(levelDB: Double(rms), now: hostTime)250                accumulateEnvelope(buffer)251            } else if let err = writer.lastError {252                warn(.audioWriteFailed(err), key: "audio-write")253            }254        case .paused:255            let keep = configuration.policy.preRollSeconds256            guard keep > 0 else { return }257            preRoll.append((buffer, hostTime)); preRollSeconds += Double(buffer.frameLength) / buffer.format.sampleRate258            while preRollSeconds > keep, let first = preRoll.first, preRoll.count > 1 {259                preRollSeconds -= Double(first.0.frameLength) / first.0.format.sampleRate; preRoll.removeFirst()260            }261        case .idle: break262        }263    }264265    static func level(_ buffer: AVAudioPCMBuffer) -> (Float, Float) {266        guard let p = buffer.floatChannelData?[0], buffer.frameLength > 0 else { return (-120, 0) }267        var sum: Float = 0, pk: Float = 0268        for i in 0..<Int(buffer.frameLength) { let v = p[i]; sum += v * v; pk = max(pk, abs(v)) }269        return (Envelope.dB((sum / Float(buffer.frameLength)).squareRoot()), pk)270    }271272    private func accumulateEnvelope(_ buffer: AVAudioPCMBuffer) {273        guard let p = buffer.floatChannelData?[0] else { return }274        let rate = buffer.format.sampleRate275        if rate != envelopeRate { envelopeCarry.removeAll(); envelopeRate = rate }276        envelopeCarry.append(contentsOf: UnsafeBufferPointer(start: p, count: Int(buffer.frameLength)))277        let hop = Int((liveEnvelope.hop.seconds * rate).rounded())278        let usable = envelopeCarry.count - envelopeCarry.count % hop279        guard usable > 0 else { return }280        envelopeCarry.withUnsafeBufferPointer { liveEnvelope.append(Envelope.compute(samples: UnsafeBufferPointer(rebasing: $0[0..<usable]), sampleRate: rate, hop: liveEnvelope.hop)) }281        envelopeCarry.removeFirst(usable)282    }283    private func flushEnvelope() { envelopeCarry.removeAll() }284285    private func segmentOpened(_ seg: MediaSegment) {286        log.append(.segment(kind: .audio, file: (seg.path as NSString).lastPathComponent, index: seg.index), at: seg.start)287    }288289    private func segmentFinalized(_ seg: MediaSegment) {290        lock.lock(); defer { lock.unlock() }291        guard let s = session, let i = manifest.sessions.firstIndex(where: { $0.id == s.id }) else { return }292        manifest.sessions[i].segments.removeAll { $0.path == seg.path }293        manifest.sessions[i].segments.append(seg)294        checkpoint()295    }296297    /// Atomic manifest update + event log flush: after this, everything finalized so far survives a crash.298    private func checkpoint() {299        manifest.recomputeDuration()300        try? package.saveManifest(manifest)301        log.flush()302        let m = manifest, cb = callbacks.manifestSaved303        DispatchQueue.main.async { cb(m) }304    }305306    private func handle(_ event: AudioSourceEvent) {307        let cb = callbacks.sourceEvent308        switch event {309        case .interruptionBegan:310            log.append(.note("audio interruption began"), at: clock.now(host: host()))311            pause(reason: .interruption)312        case .interruptionEnded(let shouldResume):313            log.append(.note("audio interruption ended (shouldResume: \(shouldResume))"), at: clock.now(host: host()))314            // Resuming is left to the instructor: an interrupted lecture must not restart recording on its own.315        case .routeChanged(let description):316            log.append(.note("audio route changed: \(description)"), at: clock.now(host: host()))317        case .failed(let message):318            log.append(.note("audio failure: \(message)"), at: clock.now(host: host()))319            pause(reason: .routeChange)320        }321        DispatchQueue.main.async { cb(event) }322    }323324    // MARK: Automatic policies and system monitoring325326    private func emit(_ output: AutoPauseEngine.Output, at t: MediaTime) {327        let decision: AutoDecision328        switch output {329        case .suggestPause(let k): decision = AutoDecision(policy: k, action: .suggestedPause)330        case .withdrawSuggestion: decision = AutoDecision(policy: .silence, action: .suggestionWithdrawn)331        case .countdownStarted(let k, let s): decision = AutoDecision(policy: k, action: .countdownStarted, detail: "\(Int(s)) s")332        case .countdownCancelled(let k): decision = AutoDecision(policy: k, action: .countdownCancelled)333        case .countdownFinished(let k, let stop): decision = AutoDecision(policy: k, action: stop ? .stopped : .paused)334        }335        log.append(.auto(decision), at: t)                        // audit log of every automatic decision336        let cb = callbacks.auto337        DispatchQueue.main.async { cb(output) }338    }339340    /// Call about four times per second while a session is open. Evaluates the automatic policies and system health.341    /// Returns true when an automatic stop was performed.342    @discardableResult343    public func tick(wall: Date = Date()) -> Bool {344        lock.lock(); defer { lock.unlock() }345        guard _state == .recording, let s = session else { return false }346        let now = host()347        let t = clock.now(host: now)348        if source == nil { auto.ingest(levelDB: -120, now: now) }349        for output in auto.tick(now: now, recordedSeconds: (t - s.timelineStart).seconds, wall: wall) {350            emit(output, at: t)351            if case .countdownFinished(let kind, let stop) = output {352                let reason: PauseReason = switch kind {353                case .inactivity: .autoInactivity354                case .maxDuration: .autoMaxDuration355                case .endTime: .autoEndTime356                case .endPhrase: .autoEndPhrase357                default: .autoSilence358                }359                pause(reason: reason)360                if stop { stop_(); return true }361            }362        }363        monitorSystem()364        return false365    }366    private func stop_() { _ = stop() }367368    /// "Continue recording" on a suggestion or a countdown.369    public func userContinued() {370        lock.lock(); defer { lock.unlock() }371        let now = host(), t = clock.now(host: now)372        for o in auto.userContinued(now: now, recordedSeconds: session.map { (t - $0.timelineStart).seconds } ?? 0, wall: Date()) { emit(o, at: t) }373    }374375    public func endPhraseHeard() {376        lock.lock(); defer { lock.unlock() }377        let now = host()378        for o in auto.endPhraseHeard(now: now) { emit(o, at: clock.now(host: now)) }379    }380381    public func countdownRemaining() -> Double? { lock.lock(); defer { lock.unlock() }; return auto.remaining(now: host()) }382383    private func warn(_ w: SystemWarning, key: String) {384        guard !raisedWarnings.contains(key) else { return }385        raisedWarnings.insert(key)386        log.append(.auto(AutoDecision(policy: .system, action: .warning, detail: key)), at: clock.now(host: host()))387        let cb = callbacks.warning388        DispatchQueue.main.async { cb(w) }389    }390391    private func monitorSystem() {392        guard Date().timeIntervalSince(lastDiskCheck) > 5 else { return }393        lastDiskCheck = Date()394        let free = ProjectPackage.freeDiskSpace(at: package.url)395        if free > 0, free < configuration.criticalDiskBytes {396            warn(.criticalDisk(availableBytes: free), key: "disk-critical")397            pause(reason: .lowDisk)398        } else if free > 0, free < configuration.lowDiskBytes {399            warn(.lowDisk(availableBytes: free), key: "disk-low")400        }401        switch ProcessInfo.processInfo.thermalState {402        case .serious: warn(.thermal(serious: false), key: "thermal-serious")403        case .critical: warn(.thermal(serious: true), key: "thermal-critical")404        default: break405        }406        if let battery = SystemStatus.batteryPercent(), battery <= 10, !SystemStatus.isCharging() { warn(.lowBattery(percent: battery), key: "battery") }407    }408}409
Files main
Menu

Theme