SPB Git

Repository Public

Analysis.swift 10.0 KB 189 lines swift

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
Files main
Menu

Theme