Repository Public
1// SP Lecture Studio — LectureStorage2// File: Packages/LectureStorage/Sources/Recovery.swift3// Description: Crash recovery: validates media found on disk, re-attaches orphaned segments, closes interrupted sessions. Never deletes anything.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai7import Foundation8import AVFoundation9import LectureCore1011public struct SegmentProbe: Sendable, Hashable {12 public var frames: Int6413 public var sampleRate: Double14 public var channels: Int15 public var duration: MediaTime16}1718public enum MediaProbe {19 /// Opens a media file and measures what can actually be decoded. Returns nil when the file is unreadable or empty.20 public static func probe(_ url: URL, kind: MediaKind) -> SegmentProbe? {21 switch kind {22 case .audio:23 guard let file = try? AVAudioFile(forReading: url), file.length > 0 else { return nil }24 let rate = file.fileFormat.sampleRate25 return SegmentProbe(frames: file.length, sampleRate: rate, channels: Int(file.fileFormat.channelCount),26 duration: MediaTime(frames: file.length, sampleRate: rate))27 case .camera, .screen:28 let asset = AVURLAsset(url: url)29 let sem = DispatchSemaphore(value: 0)30 nonisolated(unsafe) var result: SegmentProbe?31 Task.detached {32 defer { sem.signal() }33 guard let d = try? await asset.load(.duration), d.isNumeric, d.seconds > 0,34 let tracks = try? await asset.loadTracks(withMediaType: .video), !tracks.isEmpty else { return }35 result = SegmentProbe(frames: 0, sampleRate: 0, channels: 0, duration: MediaTime(seconds: d.seconds))36 }37 sem.wait()38 return result39 }40 }41}4243/// CAF repair for a recording interrupted before the file was closed: the audio bytes are on disk but the size field of44/// the `data` chunk was never updated. Setting it to -1 ("until end of file", allowed by the CAF specification) makes45/// every flushed sample readable. Only those 8 header bytes are rewritten; no audio byte is touched.46public enum CAFRepair {47 public static func repairIfNeeded(_ url: URL) -> Bool {48 guard let handle = try? FileHandle(forUpdating: url) else { return false }49 defer { try? handle.close() }50 guard let head = try? handle.read(upToCount: 8), head.count == 8, head.prefix(4) == Data("caff".utf8) else { return false }51 let fileSize = (try? handle.seekToEnd()) ?? 052 var offset: UInt64 = 853 while offset + 12 <= fileSize {54 try? handle.seek(toOffset: offset)55 guard let header = try? handle.read(upToCount: 12), header.count == 12 else { return false }56 let type = String(decoding: header.prefix(4), as: UTF8.self)57 let size = header.suffix(8).reduce(Int64(0)) { ($0 << 8) | Int64($1) }58 if type == "data" {59 let available = Int64(fileSize) - Int64(offset) - 1260 if size == -1 || size == available { return false } // already consistent61 try? handle.seek(toOffset: offset + 4)62 try? handle.write(contentsOf: Data(repeating: 0xFF, count: 8))63 try? handle.synchronize()64 return true65 }66 guard size >= 0 else { return false }67 offset += 12 + UInt64(size)68 }69 return false70 }71}7273public struct RecoveryReport: Sendable, Hashable {74 /// Segments found on disk, validated and attached to the manifest.75 public var recoveredSegments: [MediaSegment] = []76 /// Files present but not decodable (kept on disk, listed for the user; nothing is claimed about their content).77 public var unreadableFiles: [String] = []78 public var closedSessions: [UUID] = []79 public var repairedHeaders: [String] = []80 public var recoveredDuration: MediaTime = .zero81 public var didChange: Bool { !recoveredSegments.isEmpty || !closedSessions.isEmpty }82}8384public enum ProjectRecovery {85 /// Brings the manifest back in line with what is really on disk after an interrupted recording.86 /// Only bytes that reached the disk are recovered; the report never claims more.87 public static func recover(_ package: ProjectPackage, save: Bool = true) throws -> (manifest: ProjectManifest, report: RecoveryReport) {88 var manifest = try package.loadManifest()89 var report = RecoveryReport()90 let fm = FileManager.default91 let before = manifest.duration92 let files = ((try? fm.contentsOfDirectory(atPath: package.mediaURL.path)) ?? []).sorted()93 let events = package.loadEvents().events9495 for name in files {96 guard let parsed = ProjectLayout.parseSegmentFileName(name) else { continue }97 let relative = ProjectLayout.mediaDirectory + "/" + name98 let known = manifest.sessions.flatMap(\.segments).first { $0.path == relative }99 if let known, known.finalized { continue }100 let fileURL = package.url(relative)101 if parsed.kind == .audio, MediaProbe.probe(fileURL, kind: .audio) == nil, CAFRepair.repairIfNeeded(fileURL) { report.repairedHeaders.append(name) }102 guard let probe = MediaProbe.probe(fileURL, kind: parsed.kind) else { report.unreadableFiles.append(name); continue }103104 // Find (or recreate) the session this file belongs to.105 var si = manifest.sessions.firstIndex { $0.shortID == parsed.session }106 if si == nil {107 let start = events.first { if case .sessionStart(let id) = $0.e { return String(id.uuidString.prefix(8)).lowercased() == parsed.session }; return false }108 var s = RecordingSession(startedAt: start?.wall ?? Date(), timelineStart: start?.t ?? manifest.duration)109 if case .sessionStart(let id)? = start?.e { s.id = id }110 s.recovered = true111 manifest.sessions.append(s); si = manifest.sessions.count - 1112 }113 guard let sessionIndex = si else { continue }114 var session = manifest.sessions[sessionIndex]115 var segment = known ?? MediaSegment(kind: parsed.kind, path: relative, index: parsed.index, start: .zero, duration: .zero, finalized: false)116 if known == nil || parsed.kind == .audio {117 // Audio segments are contiguous: the start is the end of the previous segment of the session.118 let previous = session.segments.filter { $0.kind == parsed.kind && $0.index < parsed.index }.max { $0.index < $1.index }119 segment.start = parsed.kind == .audio ? (previous.map { $0.start + $0.duration } ?? session.timelineStart)120 : (segmentStart(from: events, file: name) ?? previous.map { $0.start + $0.duration } ?? session.timelineStart)121 }122 segment.duration = probe.duration; segment.frames = probe.frames; segment.sampleRate = probe.sampleRate; segment.channels = probe.channels123 segment.sha256 = try? Hashing.sha256(of: fileURL)124 segment.finalized = true; segment.recovered = true125 session.segments.removeAll { $0.path == relative }126 session.segments.append(segment); session.segments.sort { ($0.kind.rawValue, $0.index) < ($1.kind.rawValue, $1.index) }127 manifest.sessions[sessionIndex] = session128 report.recoveredSegments.append(segment)129 }130131 for i in manifest.sessions.indices where manifest.sessions[i].endedAt == nil {132 let last = manifest.sessions[i].segments.compactMap { try? fm.attributesOfItem(atPath: package.url($0.path).path)[.modificationDate] as? Date }.max()133 manifest.sessions[i].endedAt = last ?? manifest.sessions[i].startedAt134 manifest.sessions[i].recovered = true135 report.closedSessions.append(manifest.sessions[i].id)136 }137 manifest.sessions.sort { $0.timelineStart < $1.timelineStart }138 manifest.recomputeDuration()139 report.recoveredDuration = manifest.duration - before140 if report.didChange && save { try package.saveManifest(manifest) }141 return (manifest, report)142 }143144 private static func segmentStart(from events: [TimelineEvent], file: String) -> MediaTime? {145 for ev in events { if case .segment(_, let f, _) = ev.e, f == file { return ev.t } }146 return nil147 }148149 /// True when the package shows signs of an interrupted recording (cheap check used when opening a project).150 public static func needsRecovery(_ package: ProjectPackage, manifest: ProjectManifest) -> Bool {151 if manifest.sessions.contains(where: { $0.endedAt == nil }) { return true }152 if manifest.sessions.flatMap(\.segments).contains(where: { !$0.finalized }) { return true }153 let known = Set(manifest.sessions.flatMap(\.segments).map { ($0.path as NSString).lastPathComponent })154 let files = (try? FileManager.default.contentsOfDirectory(atPath: package.mediaURL.path)) ?? []155 return files.contains { ProjectLayout.parseSegmentFileName($0) != nil && !known.contains($0) }156 }157}158