Repository Public
1// SP Lecture Studio — LectureCapture2// File: Packages/LectureCapture/Sources/RecordingClock.swift3// Description: The authoritative recording clock: converts host time to timeline time, anchored on the audio sample clock, frozen while paused.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai7import Foundation8import AVFoundation9import LectureCore1011/// One clock for every stream of a recording.12///13/// The timeline advances only while recording. While audio is captured the clock is re-anchored on every audio buffer14/// (`host time of the buffer` ↔ `timeline position of its first sample`), so events are stamped on the audio sample15/// clock and cannot drift from it, however long the session. Without audio (PDF-only mode) it runs on the host clock.16public final class RecordingClock: @unchecked Sendable {17 private let lock = NSLock()18 private var anchorHost: TimeInterval = 019 private var anchorTimeline: MediaTime = .zero20 private var frozen: MediaTime?21 private var lastReturned: MediaTime = .zero2223 public init(at timeline: MediaTime = .zero) { frozen = timeline; lastReturned = timeline; anchorTimeline = timeline }2425 /// Host time in seconds on the same base as `AVAudioTime.hostTime` (mach absolute time).26 public static func hostNow() -> TimeInterval { AVAudioTime.seconds(forHostTime: mach_absolute_time()) }2728 public func start(at timeline: MediaTime, host: TimeInterval = RecordingClock.hostNow()) {29 lock.lock(); anchorHost = host; anchorTimeline = timeline; frozen = nil; lastReturned = max(lastReturned, timeline); lock.unlock()30 }3132 /// Re-anchors on an audio buffer: its first sample was captured at `host` and sits at `timeline`.33 public func anchor(host: TimeInterval, timeline: MediaTime) {34 lock.lock(); if frozen == nil { anchorHost = host; anchorTimeline = timeline }; lock.unlock()35 }3637 /// Freezes the clock (pause / stop) and returns the frozen time.38 @discardableResult39 public func freeze(at timeline: MediaTime? = nil, host: TimeInterval = RecordingClock.hostNow()) -> MediaTime {40 lock.lock(); defer { lock.unlock() }41 let t = timeline ?? currentLocked(host)42 frozen = max(t, lastReturned); lastReturned = frozen!43 return frozen!44 }4546 public var isRunning: Bool { lock.lock(); defer { lock.unlock() }; return frozen == nil }4748 /// Timeline time for a host time (now by default). Monotonic: never goes backwards.49 public func now(host: TimeInterval = RecordingClock.hostNow()) -> MediaTime {50 lock.lock(); defer { lock.unlock() }51 let t = max(currentLocked(host), lastReturned)52 lastReturned = t53 return t54 }5556 /// Timeline time of a past host timestamp (e.g. a camera frame), without affecting monotonicity.57 public func timeline(forHost host: TimeInterval) -> MediaTime {58 lock.lock(); defer { lock.unlock() }59 return currentLocked(host)60 }6162 private func currentLocked(_ host: TimeInterval) -> MediaTime {63 if let frozen { return frozen }64 return anchorTimeline + MediaTime(seconds: max(0, host - anchorHost))65 }66}67