Repository Public
1// SP Lecture Studio — LectureCore2// File: Packages/LectureCore/Sources/TimelineIndex.swift3// Description: Derived, queryable view of the event stream: page, ink, pointer and viewport state at any timeline time.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai7import Foundation89/// Non destructive per-stroke adjustments made in the editing studio.10public struct InkAdjustments: Hashable, Sendable, Codable {11 /// Time shift applied to a stroke (nanoseconds, may be negative).12 public var offsets: [UUID: Int64]13 /// Strokes kept in the project but left out of the video and of the annotated PDF.14 public var hidden: Set<UUID>15 public init(offsets: [UUID: Int64] = [:], hidden: Set<UUID> = []) { self.offsets = offsets; self.hidden = hidden }16 public static let none = InkAdjustments()17 public var isEmpty: Bool { offsets.isEmpty && hidden.isEmpty }18}1920public struct PageChange: Hashable, Sendable {21 public var t: MediaTime; public var page: Int22 public init(t: MediaTime, page: Int) { self.t = t; self.page = page }23}24public struct MarkerAt: Hashable, Sendable, Identifiable { public var t: MediaTime; public var marker: Marker; public var id: UUID { marker.id } }25public struct PauseRecord: Hashable, Sendable { public var t: MediaTime; public var reason: PauseReason; public var gapSeconds: Double? }26public struct PointerSample: Hashable, Sendable { public var t: MediaTime; public var x: Double; public var y: Double; public var visible: Bool }27public struct ViewportSample: Hashable, Sendable { public var t: MediaTime; public var viewport: Viewport }28public struct CameraSample: Hashable, Sendable { public var t: MediaTime; public var enabled: Bool; public var placement: CameraPlacement }2930/// Life of one stroke on the timeline.31public struct StrokeLife: Sendable, Hashable {32 public var stroke: Stroke33 /// Intervals during which the stroke is removed (erased / undone). An open removal ends at `.max`.34 public var removed: [TimeRange]35 public func isRemoved(at t: MediaTime) -> Bool { removed.contains { $0.contains(t) } }36}3738public struct VisibleStroke: Sendable, Hashable {39 public var stroke: Stroke40 /// Number of points drawn so far; equals `stroke.points.count` when `complete`.41 public var pointCount: Int42 public var complete: Bool43}4445/// Cheap, hashable description of everything the compositor draws at one instant. Two instants with the same46/// signature produce the same picture, which lets the exporter reuse a rendered frame.47public struct FrameSignature: Hashable, Sendable {48 public var page: Int49 public var inkVersion: Int50 public var inProgress: [Int] // point counts of the strokes being drawn, flattened as [strokeOrdinal, count, …]51 public var pointer: PointerSample?52 public var viewport: Viewport53 public var camera: CameraSample?54}5556public struct TimelineIndex: Sendable {57 public static let farFuture = MediaTime(ns: Int64.max / 4)5859 public private(set) var pageChanges: [PageChange] = []60 public private(set) var strokes: [Int: [StrokeLife]] = [:] // per page, in drawing order (by begin time)61 public private(set) var pointer: [PointerSample] = []62 public private(set) var viewports: [ViewportSample] = []63 public private(set) var markers: [MarkerAt] = []64 public private(set) var pauses: [PauseRecord] = []65 public private(set) var camera: [CameraSample] = []66 public private(set) var autoDecisions: [(t: MediaTime, wall: Date, decision: AutoDecision)] = []67 public private(set) var lastEventTime: MediaTime = .zero68 private var inkChangeTimes: [Int: [MediaTime]] = [:]69 private var maxStrokeDuration: [Int: MediaTime] = [:]70 public let initialPage: Int7172 public init(events: [TimelineEvent], adjustments: InkAdjustments = .none, initialPage: Int = 0) {73 self.initialPage = initialPage74 var lives: [UUID: StrokeLife] = [:]75 var order: [UUID] = []76 for ev in events.sorted(by: { ($0.t, $0.seq) < ($1.t, $1.seq) }) {77 lastEventTime = max(lastEventTime, ev.t)78 switch ev.e {79 case .page(let index):80 if pageChanges.last?.t == ev.t { pageChanges.removeLast() }81 if pageChanges.last?.page != index || pageChanges.isEmpty { pageChanges.append(PageChange(t: ev.t, page: index)) }82 case .strokeAdded(var s):83 if adjustments.hidden.contains(s.id) { continue }84 if let off = adjustments.offsets[s.id] { s.begin = MediaTime(ns: max(0, s.begin.ns + off)) }85 if lives[s.id] == nil { order.append(s.id) }86 lives[s.id] = StrokeLife(stroke: s, removed: [])87 case .strokesRemoved(let ids):88 for id in ids {89 guard var l = lives[id] else { continue }90 if let last = l.removed.last, last.end == Self.farFuture { continue } // already removed91 l.removed.append(TimeRange(start: ev.t, end: Self.farFuture)); lives[id] = l92 }93 case .strokesRestored(let ids):94 for id in ids {95 guard var l = lives[id], let last = l.removed.last, last.end == Self.farFuture else { continue }96 l.removed[l.removed.count - 1] = TimeRange(start: last.start, end: max(last.start, ev.t)); lives[id] = l97 }98 case .viewport(let v): viewports.append(ViewportSample(t: ev.t, viewport: v))99 case .pointer(let x, let y): pointer.append(PointerSample(t: ev.t, x: x, y: y, visible: true))100 case .pointerHidden: pointer.append(PointerSample(t: ev.t, x: 0, y: 0, visible: false))101 case .marker(let m): markers.append(MarkerAt(t: ev.t, marker: m))102 case .pause(let reason): pauses.append(PauseRecord(t: ev.t, reason: reason, gapSeconds: nil))103 case .resume(let gap): if !pauses.isEmpty, pauses[pauses.count - 1].gapSeconds == nil { pauses[pauses.count - 1].gapSeconds = gap }104 case .camera(let enabled, let placement): camera.append(CameraSample(t: ev.t, enabled: enabled, placement: placement))105 case .auto(let d): autoDecisions.append((ev.t, ev.wall, d))106 case .sessionStart, .sessionEnd, .segment, .note: break107 }108 }109 var perPage: [Int: [StrokeLife]] = [:]110 for id in order { if let l = lives[id] { perPage[l.stroke.page, default: []].append(l) } }111 for (page, list) in perPage {112 let sorted = list.enumerated().sorted { ($0.element.stroke.begin, $0.offset) < ($1.element.stroke.begin, $1.offset) }.map(\.element)113 strokes[page] = sorted114 var times: [MediaTime] = []115 var longest = MediaTime.zero116 for l in sorted {117 times.append(l.stroke.end); longest = max(longest, l.stroke.duration)118 for r in l.removed { times.append(r.start); if r.end != Self.farFuture { times.append(r.end) } }119 }120 inkChangeTimes[page] = times.sorted()121 maxStrokeDuration[page] = longest122 }123 }124125 // MARK: Queries126127 public func page(at t: MediaTime) -> Int {128 Self.lastIndex(in: pageChanges, at: t, time: \.t).map { pageChanges[$0].page } ?? initialPage129 }130131 /// Pages shown at least once, with the first time they appear.132 public var pagesInOrder: [PageChange] { pageChanges }133134 public func visibleStrokes(page: Int, at t: MediaTime) -> [VisibleStroke] {135 guard let list = strokes[page] else { return [] }136 var out: [VisibleStroke] = []137 for l in list {138 if l.stroke.begin > t { break }139 if l.isRemoved(at: t) { continue }140 let n = l.stroke.pointCount(at: t)141 if n > 0 { out.append(VisibleStroke(stroke: l.stroke, pointCount: n, complete: n == l.stroke.points.count && t >= l.stroke.end)) }142 }143 return out144 }145146 /// Final annotation state of a page (what the annotated PDF contains).147 public func finalStrokes(page: Int) -> [Stroke] {148 (strokes[page] ?? []).filter { !$0.isRemoved(at: Self.farFuture - MediaTime(ns: 1)) }.map(\.stroke)149 }150151 public var annotatedPages: [Int] { strokes.keys.sorted() }152 public var allStrokes: [StrokeLife] { strokes.keys.sorted().flatMap { strokes[$0] ?? [] } }153154 /// Laser pointer position; it disappears when hidden or `linger` seconds after its last movement.155 public func pointer(at t: MediaTime, linger: MediaTime = MediaTime(seconds: 1.2)) -> PointerSample? {156 guard let i = Self.lastIndex(in: pointer, at: t, time: \.t) else { return nil }157 let s = pointer[i]158 return s.visible && t - s.t <= linger ? s : nil159 }160161 public func viewport(at t: MediaTime) -> Viewport {162 Self.lastIndex(in: viewports, at: t, time: \.t).map { viewports[$0].viewport } ?? .fit163 }164165 public func camera(at t: MediaTime) -> CameraSample? {166 Self.lastIndex(in: camera, at: t, time: \.t).map { camera[$0] }167 }168169 public func signature(at t: MediaTime) -> FrameSignature {170 let p = page(at: t)171 var version = 0172 if let times = inkChangeTimes[p] {173 var lo = 0, hi = times.count174 while lo < hi { let mid = (lo + hi) / 2; if times[mid] <= t { lo = mid + 1 } else { hi = mid } }175 version = lo176 }177 var progress: [Int] = []178 if let list = strokes[p], let longest = maxStrokeDuration[p], longest > .zero {179 for (i, l) in list.enumerated() {180 if l.stroke.begin > t { break }181 if l.stroke.end > t && !l.isRemoved(at: t) { progress.append(i); progress.append(l.stroke.pointCount(at: t)) }182 }183 }184 var ptr = pointer(at: t)185 if var q = ptr { q.t = .zero; ptr = q }186 var cam = camera(at: t)187 if var c = cam { c.t = .zero; cam = c.enabled ? c : nil }188 return FrameSignature(page: p, inkVersion: version, inProgress: progress, pointer: ptr, viewport: viewport(at: t), camera: cam)189 }190191 /// Times of the last interaction (ink or slide change) before `t`; used by the inactivity policy and by retake suggestions.192 public func interactionTimes() -> [MediaTime] {193 var out = pageChanges.map(\.t)194 for l in allStrokes { out.append(l.stroke.begin); out.append(l.stroke.end) }195 return out.sorted()196 }197198 static func lastIndex<T>(in array: [T], at t: MediaTime, time: KeyPath<T, MediaTime>) -> Int? {199 var lo = 0, hi = array.count200 while lo < hi { let mid = (lo + hi) / 2; if array[mid][keyPath: time] <= t { lo = mid + 1 } else { hi = mid } }201 return lo > 0 ? lo - 1 : nil202 }203}204