Repository Public
1// SP Lecture Studio — LectureCore2// File: Packages/LectureCore/Sources/Analysis.swift3// Description: Deterministic (non AI) analysis: loudness envelope, long-silence detection, retake suggestions, chapters from slides.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai7import Foundation89/// Loudness envelope of the recorded audio: one RMS and one peak value per `hop`.10public struct Envelope: Sendable, Codable, Hashable {11 public var hop: MediaTime12 /// RMS level in dBFS per hop (-120 = digital silence).13 public var rms: [Float]14 /// Peak amplitude 0…1 per hop (for waveform drawing).15 public var peak: [Float]16 public init(hop: MediaTime = MediaTime(milliseconds: 10), rms: [Float] = [], peak: [Float] = []) { self.hop = hop; self.rms = rms; self.peak = peak }17 public var duration: MediaTime { MediaTime(ns: hop.ns * Int64(rms.count)) }18 public static func dB(_ amplitude: Float) -> Float { amplitude > 0.000001 ? 20 * log10(amplitude) : -120 }1920 /// Builds an envelope from mono float samples.21 public static func compute(samples: UnsafeBufferPointer<Float>, sampleRate: Double, hop: MediaTime = MediaTime(milliseconds: 10)) -> Envelope {22 let n = max(1, Int((hop.seconds * sampleRate).rounded()))23 var env = Envelope(hop: hop)24 var i = 025 while i + n <= samples.count {26 var sum: Float = 0, pk: Float = 027 for j in i..<(i + n) { let v = samples[j]; sum += v * v; pk = max(pk, abs(v)) }28 env.rms.append(dB((sum / Float(n)).squareRoot())); env.peak.append(pk)29 i += n30 }31 return env32 }3334 public mutating func append(_ other: Envelope) { rms.append(contentsOf: other.rms); peak.append(contentsOf: other.peak) }3536 public func percentile(_ p: Double) -> Float {37 guard !rms.isEmpty else { return -120 }38 let sorted = rms.sorted()39 return sorted[min(sorted.count - 1, max(0, Int(Double(sorted.count - 1) * p)))]40 }41}4243public struct SilenceRange: Sendable, Hashable {44 public var range: TimeRange45 public var meanDB: Float46 public var confidence: Double47}4849public enum SilenceDetector {50 public struct Config: Sendable, Hashable, Codable {51 /// Only silences at least this long are reported: natural pauses between sentences are left alone.52 public var minSilence: Double = 3.053 /// Speech kept on each side of a suggested cut.54 public var padding: Double = 0.455 /// Absolute ceiling of the silence threshold (dBFS).56 public var maxThresholdDB: Float = -3857 /// Margin above the measured noise floor.58 public var floorMarginDB: Float = 959 /// A hop must rise this much above the threshold to end a silence (hysteresis).60 public var hysteresisDB: Float = 461 /// Sounds shorter than this inside a silence (click, cough tail) do not interrupt it.62 public var bridge: Double = 0.1563 public init() {}64 }6566 public struct Result: Sendable {67 public var silences: [SilenceRange]68 public var thresholdDB: Float69 public var noiseFloorDB: Float70 public var speechDB: Float71 /// False when speech and background cannot be told apart reliably (no suggestion is made).72 public var reliable: Bool73 }7475 public static func detect(_ env: Envelope, config: Config = Config()) -> Result {76 // The floor is taken low in the distribution: a lecture can be almost continuous speech.77 let floor = env.percentile(0.03), speech = env.percentile(0.90)78 let separation = speech - floor79 var threshold = min(config.maxThresholdDB, floor + config.floorMarginDB)80 threshold = min(threshold, speech - 10)81 guard separation >= 14, !env.rms.isEmpty else {82 return Result(silences: [], thresholdDB: threshold, noiseFloorDB: floor, speechDB: speech, reliable: false)83 }84 let hop = env.hop.seconds85 let bridgeHops = max(0, Int(config.bridge / hop))86 var silences: [SilenceRange] = []87 var start: Int? = nil88 var loudRun = 089 var sum: Float = 0, count = 090 func close(_ endIndex: Int) {91 guard let s = start else { return }92 let dur = Double(endIndex - s) * hop93 if dur >= config.minSilence {94 let mean = count > 0 ? sum / Float(count) : -12095 let depth = Double(min(20, max(0, threshold - mean))) / 2096 let length = min(1, dur / (config.minSilence * 3))97 let conf = min(0.99, 0.55 + 0.25 * depth + 0.2 * length)98 silences.append(SilenceRange(range: TimeRange(start: MediaTime(ns: env.hop.ns * Int64(s)), end: MediaTime(ns: env.hop.ns * Int64(endIndex))),99 meanDB: mean, confidence: conf))100 }101 }102 for (i, level) in env.rms.enumerated() {103 if start == nil {104 if level < threshold { start = i; loudRun = 0; sum = level; count = 1 }105 } else if level < threshold + config.hysteresisDB {106 loudRun = 0; sum += level; count += 1107 } else {108 loudRun += 1109 if loudRun > bridgeHops { close(i - loudRun + 1); start = nil; loudRun = 0; sum = 0; count = 0 }110 }111 }112 close(env.rms.count - loudRun)113 return Result(silences: silences, thresholdDB: threshold, noiseFloorDB: floor, speechDB: speech, reliable: true)114 }115116 /// Cut suggestions for long silences, shrunk by the padding so that the surrounding speech is never clipped.117 public static func suggestions(_ env: Envelope, config: Config = Config()) -> [Cut] {118 let pad = MediaTime(seconds: config.padding)119 return detect(env, config: config).silences.compactMap { s in120 let r = TimeRange(start: s.range.start + pad, end: s.range.end - pad)121 guard s.range.duration > pad + pad, r.duration.seconds >= 0.5 else { return nil }122 return Cut(range: r, origin: .silence, note: String(format: "%.1f s", r.duration.seconds), confidence: s.confidence)123 }124 }125}126127public enum RetakeSuggester {128 /// For every retake marker, suggests cutting from the beginning of the failed attempt to the marker.129 /// The attempt is assumed to start at the latest of: the previous retake/chapter marker, the last slide change,130 /// or the end of the last long silence before the marker; never more than `maxLookback` earlier.131 public static func suggestions(index: TimelineIndex, envelope: Envelope?, duration: MediaTime,132 maxLookback: Double = 120, minPause: Double = 1.2) -> [Cut] {133 var cfg = SilenceDetector.Config(); cfg.minSilence = minPause134 let silences = envelope.map { SilenceDetector.detect($0, config: cfg).silences } ?? []135 var out: [Cut] = []136 let retakes = index.markers.filter { $0.marker.kind == .retake }137 for m in retakes {138 let floor = max(.zero, m.t - MediaTime(seconds: maxLookback))139 var candidates: [(MediaTime, Double, String)] = [(floor, 0.35, "lookback")]140 if let prev = index.markers.last(where: { $0.t < m.t && $0.id != m.id }), prev.t >= floor { candidates.append((prev.t, 0.7, "marker")) }141 if let page = index.pageChanges.last(where: { $0.t < m.t }), page.t >= floor { candidates.append((page.t, 0.6, "slide")) }142 // The silence that precedes the failed sentence: the last one ending at least 1 s before the marker.143 if let s = silences.last(where: { $0.range.end <= m.t - MediaTime(seconds: 1) && $0.range.end >= floor }) {144 candidates.append((s.range.end - MediaTime(seconds: 0.2), 0.8, "pause"))145 }146 guard let best = candidates.max(by: { $0.0 < $1.0 }) else { continue }147 // The cut ends where speech resumes after the marker (end of the silence containing it), else at the marker.148 var end = m.t149 if let s = silences.first(where: { $0.range.contains(m.t) || ($0.range.start >= m.t && $0.range.start - m.t < MediaTime(seconds: 1.5)) }) {150 end = max(m.t, s.range.end - MediaTime(seconds: 0.2))151 }152 let range = TimeRange(start: max(.zero, best.0), end: min(duration, end))153 if range.duration.seconds >= 0.3 { out.append(Cut(range: range, origin: .retake, note: best.2, confidence: best.1)) }154 }155 return out156 }157}158159public enum ChapterGenerator {160 /// One chapter per slide shown for at least `minDwell` seconds; consecutive visits of the same slide are merged.161 public static func fromSlides(index: TimelineIndex, duration: MediaTime, minDwell: Double = 5,162 title: (Int) -> String) -> [Chapter] {163 var changes = index.pageChanges164 if changes.first?.t != .zero { changes.insert(PageChange(t: .zero, page: index.initialPage), at: 0) }165 var out: [Chapter] = []166 for (i, c) in changes.enumerated() {167 let end = i + 1 < changes.count ? changes[i + 1].t : duration168 guard (end - c.t).seconds >= minDwell || i == 0 else { continue }169 if let last = out.last, last.title == title(c.page) { continue }170 out.append(Chapter(time: c.t, title: title(c.page)))171 }172 for m in index.markers where m.marker.kind == .chapter {173 out.append(Chapter(time: m.t, title: m.marker.label.isEmpty ? title(index.page(at: m.t)) : m.marker.label))174 }175 return out.sorted { $0.time < $1.time }176 }177178 /// Chapters on the edited timeline (chapters inside a cut move to the join; duplicates at the same time are dropped).179 public static func mapped(_ chapters: [Chapter], map: TimeMap) -> [Chapter] {180 var out: [Chapter] = []181 for c in chapters.sorted(by: { $0.time < $1.time }) {182 let t = map.toOutput(c.time)183 if let last = out.last, last.time == t { out[out.count - 1] = Chapter(id: c.id, time: t, title: c.title) }184 else if t < map.outputDuration || out.isEmpty { out.append(Chapter(id: c.id, time: t, title: c.title)) }185 }186 return out187 }188}189