Repository Public
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