Repository Public
1// SP Lecture Studio — LectureCore2// Structured, append-only event stream of a lecture (events.jsonl: one JSON object per line).3// Author: Simon-Pierre Boucher — contact@spboucher.ai4import Foundation56public enum MarkerKind: String, Codable, Sendable { case generic, chapter, retake }78public struct Marker: Hashable, Sendable, Codable, Identifiable {9 public var id: UUID10 public var kind: MarkerKind11 public var label: String12 public init(id: UUID = UUID(), kind: MarkerKind, label: String = "") { self.id = id; self.kind = kind; self.label = label }13}1415public enum PauseReason: String, Codable, Sendable {16 case manual, autoSilence, autoInactivity, autoMaxDuration, autoEndTime, autoEndPhrase17 case interruption, routeChange, lowDisk, appBackground, thermal18}1920public enum AutoPolicyKind: String, Codable, Sendable { case silence, inactivity, maxDuration, endTime, endPhrase, retakePhrase, system }21public enum AutoAction: String, Codable, Sendable {22 case suggestedPause, suggestionWithdrawn, countdownStarted, countdownCancelled, paused, stopped, retakeMarked, warning23}2425/// Audit record of an automatic decision (also written to the event stream).26public struct AutoDecision: Hashable, Sendable, Codable {27 public var policy: AutoPolicyKind28 public var action: AutoAction29 public var detail: String30 public init(policy: AutoPolicyKind, action: AutoAction, detail: String = "") { self.policy = policy; self.action = action; self.detail = detail }31}3233public enum MediaKind: String, Codable, Sendable { case audio, camera, screen }3435public enum CameraCorner: String, Codable, Sendable, CaseIterable { case topLeft, topRight, bottomLeft, bottomRight }36public struct CameraPlacement: Hashable, Sendable, Codable {37 public var corner: CameraCorner38 /// Width of the picture-in-picture as a fraction of the frame width.39 public var size: Double40 public init(corner: CameraCorner = .bottomRight, size: Double = 0.22) { self.corner = corner; self.size = size }41}4243/// Payload of an event. Encoded by the compiler-synthesized `Codable` (`{"page":{"index":3}}`); see docs/PROJECT_FORMAT.md.44public enum EventPayload: Sendable, Codable, Hashable {45 case sessionStart(id: UUID)46 case sessionEnd(id: UUID)47 case page(index: Int)48 case strokeAdded(Stroke)49 /// Erase or undo: the strokes stop being visible at this time. They stay in the log (nothing is destroyed).50 case strokesRemoved(ids: [UUID])51 /// Redo / undo of an erase: the strokes are visible again from this time.52 case strokesRestored(ids: [UUID])53 case viewport(Viewport)54 case pointer(x: Double, y: Double)55 case pointerHidden56 case marker(Marker)57 case pause(reason: PauseReason)58 /// `gapSeconds` is the exact wall-clock length of the pause (the timeline itself does not advance while paused).59 case resume(gapSeconds: Double)60 case camera(enabled: Bool, placement: CameraPlacement)61 case segment(kind: MediaKind, file: String, index: Int)62 case auto(AutoDecision)63 case note(String)64}6566public struct TimelineEvent: Sendable, Codable, Hashable {67 /// Strictly increasing sequence number inside a project.68 public var seq: Int6469 /// Timeline (recorded) time.70 public var t: MediaTime71 /// Wall clock time, for audit only (never used for synchronisation).72 public var wall: Date73 public var e: EventPayload74 public init(seq: Int64, t: MediaTime, wall: Date = Date(), e: EventPayload) { self.seq = seq; self.t = t; self.wall = wall; self.e = e }75}7677public enum EventCoding {78 public static func encoder() -> JSONEncoder {79 let e = JSONEncoder(); e.dateEncodingStrategy = .millisecondsSince1970; e.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]; return e80 }81 public static func decoder() -> JSONDecoder {82 let d = JSONDecoder(); d.dateDecodingStrategy = .millisecondsSince1970; return d83 }8485 public static func line(for event: TimelineEvent) throws -> Data {86 var d = try encoder().encode(event); d.append(0x0A); return d87 }8889 public struct ParseResult: Sendable {90 public var events: [TimelineEvent] = []91 /// Lines that could not be decoded (truncated last line after a crash, or kinds written by a newer version). Never deleted.92 public var skippedLines = 093 public var truncatedTail = false94 public init() {}95 }9697 /// Tolerant reader: a damaged or unknown line is skipped and counted, the rest of the log is kept.98 public static func parse(_ data: Data) -> ParseResult {99 var result = ParseResult()100 let dec = decoder()101 let endsWithNewline = data.last == 0x0A102 let lines = data.split(separator: 0x0A, omittingEmptySubsequences: true)103 for (i, line) in lines.enumerated() {104 if let ev = try? dec.decode(TimelineEvent.self, from: Data(line)) {105 result.events.append(ev)106 } else {107 result.skippedLines += 1108 if i == lines.count - 1 && !endsWithNewline { result.truncatedTail = true }109 }110 }111 return result112 }113}114