SPB Git

Repository Public

Transcription.swift 11.0 KB 238 lines swift

1// =============================================================================2//                  SP BOUCHER | SOFTWARE & RESEARCH3//             ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project          : SP Lecture Studio9// File             : Packages/LectureTranscription/Sources/Transcription.swift10// Description      : Transcription provider abstraction, chunk planning at11//                    silences, word grouping into caption segments, phrase12//                    matching.13// Module           : Packages14// Repository       : https://git.spboucher.ai/sp-lecture-studio15// Created          : 2026-11-1816// Last Modified    : 2026-11-1817//18// =============================================================================19// AUTHOR & PROFESSIONAL AFFILIATION20// =============================================================================21//22// Author           : Simon-Pierre Boucher23// Position         : Professor of Finance24// Institution      : Université du Québec en Outaouais (UQO)25// Department       : Département des sciences administratives26// Organization     : SP Boucher27//28// Website          : https://spboucher.ai29// Git              : https://git.spboucher.ai30//31// =============================================================================32// OFFICIAL CONTACT DIRECTORY33// =============================================================================34//35// General          : info@spboucher.ai36// Professional     : contact@spboucher.ai37// Direct           : simon@spboucher.ai38// Research         : research@spboucher.ai39// Development      : dev@spboucher.ai40// Support          : support@spboucher.ai41// Security/Admin   : admin@spboucher.ai42// Notifications    : notifications@spboucher.ai43//44// Preferred Contact: support@spboucher.ai45//46// =============================================================================47// COPYRIGHT & INTELLECTUAL PROPERTY48// =============================================================================49//50// Copyright (c) 202651// Simon-Pierre Boucher52//53// All rights reserved where applicable.54//55// This file is governed by the applicable project license,56// copyright notices, institutional agreements and relevant law.57//58// Unless expressly authorized by the applicable license or59// rights holder, copying, redistribution, sublicensing,60// publication and commercial exploitation are not permitted.61//62// Existing third-party rights and notices remain unaffected.63//64// =============================================================================65// CONFIDENTIALITY & SECURITY66// =============================================================================67//68// Classification   : Public69// Distribution     : Public repository; use is governed by the project license70// Security Contact : admin@spboucher.ai71//72// Access to this source does not independently grant permission73// to redistribute or disclose confidential materials.74//75// Do not embed credentials, private keys, access tokens,76// certificates or confidential personal information.77//78// =============================================================================79// LICENSE & MAINTENANCE80// =============================================================================81//82// License          : None specified (no license file in this repository)83// Maintainer       : Simon-Pierre Boucher84// Technical Contact: dev@spboucher.ai85//86// =============================================================================87// END OF SP BOUCHER SOURCE HEADER88// =============================================================================8990import Foundation91import LectureCore9293public enum ProviderAvailability: Sendable, Equatable {94    case available95    /// Machine-readable reason, localized by the app: "permission", "unsupportedLocale", "modelNotInstalled", "notConfigured", "insecureEndpoint".96    case unavailable(String)97    public var isAvailable: Bool { self == .available }98}99100public enum TranscriptionError: Error, Equatable, CustomStringConvertible {101    case unavailable(String), cancelled, failed(String), server(Int, String)102    public var description: String {103        switch self {104        case .unavailable(let r): "transcription unavailable: \(r)"105        case .cancelled: "cancelled"106        case .failed(let m): m107        case .server(let code, let m): "server answered \(code): \(m)"108        }109    }110}111112public struct RecognizedWord: Sendable, Hashable {113    public var text: String114    /// Seconds from the beginning of the chunk.115    public var start: Double116    public var duration: Double117    public var confidence: Double118    public init(text: String, start: Double, duration: Double, confidence: Double) { self.text = text; self.start = start; self.duration = duration; self.confidence = confidence }119}120121/// One piece of audio handed to a provider: mono Float32 samples and where they sit on the source timeline.122public struct AudioChunk: Sendable {123    public var range: TimeRange124    public var samples: [Float]125    public var sampleRate: Double126    public init(range: TimeRange, samples: [Float], sampleRate: Double) { self.range = range; self.samples = samples; self.sampleRate = sampleRate }127}128129public protocol TranscriptionProvider: Sendable {130    /// Stable identifier stored in the transcript ("apple.speech.ondevice", "remote.openai-compatible").131    var id: String { get }132    /// True when audio leaves the device. The app asks for explicit consent before using such a provider.133    var sendsAudioOffDevice: Bool { get }134    func availability(locale: Locale) async -> ProviderAvailability135    /// Transcribes one chunk. Returned segment times are relative to the chunk start.136    func transcribe(_ chunk: AudioChunk, locale: Locale) async throws -> [TranscriptSegment]137}138139public enum ChunkPlanner {140    /// Splits `[0, duration)` into chunks of at most `maxChunk` seconds, cutting at the quietest moment of the last third141    /// of each window so that words are not split. Without an envelope the cuts fall on fixed boundaries.142    public static func plan(duration: MediaTime, envelope: Envelope?, target: Double = 45, maxChunk: Double = 55) -> [TimeRange] {143        var out: [TimeRange] = []144        var cursor = 0.0145        let total = duration.seconds146        while cursor < total - 0.001 {147            if total - cursor <= maxChunk { out.append(TimeRange(seconds: cursor, total)); break }148            var cut = cursor + target149            if let env = envelope, env.hop.seconds > 0 {150                let hop = env.hop.seconds151                let lo = Int((cursor + maxChunk * 0.6) / hop), hi = min(env.rms.count, Int((cursor + maxChunk) / hop))152                if lo < hi {153                    // Quietest 200 ms window in the search zone.154                    let w = max(1, Int(0.2 / hop))155                    var best = Float.greatestFiniteMagnitude, bestIndex = lo156                    var i = lo157                    while i + w <= hi {158                        let mean = env.rms[i..<(i + w)].reduce(0, +) / Float(w)159                        if mean < best { best = mean; bestIndex = i + w / 2 }160                        i += max(1, w / 2)161                    }162                    cut = Double(bestIndex) * hop163                }164            }165            out.append(TimeRange(seconds: cursor, cut)); cursor = cut166        }167        return out168    }169}170171public enum TranscriptAssembler {172    /// Groups recognized words into caption-sized segments: a new segment starts after a pause, after sentence-ending173    /// punctuation once long enough, or when the segment gets too long.174    public static func group(_ words: [RecognizedWord], offset: MediaTime, maxWords: Int = 16, maxSeconds: Double = 7, pause: Double = 0.7) -> [TranscriptSegment] {175        var out: [TranscriptSegment] = []176        var current: [RecognizedWord] = []177        func flush() {178            guard let first = current.first, let last = current.last else { return }179            let text = current.map(\.text).joined(separator: " ").replacingOccurrences(of: " ,", with: ",").replacingOccurrences(of: " .", with: ".")180            let conf = current.map(\.confidence).reduce(0, +) / Double(current.count)181            out.append(TranscriptSegment(range: TimeRange(start: offset + MediaTime(seconds: first.start), end: offset + MediaTime(seconds: max(last.start + last.duration, first.start + 0.2))),182                                         text: text, confidence: conf))183            current = []184        }185        for w in words {186            if let last = current.last, let first = current.first {187                let gap = w.start - (last.start + last.duration)188                let sentenceEnd = last.text.hasSuffix(".") || last.text.hasSuffix("?") || last.text.hasSuffix("!")189                if gap >= pause || current.count >= maxWords || w.start + w.duration - first.start > maxSeconds || (sentenceEnd && current.count >= 5) { flush() }190            }191            current.append(w)192        }193        flush()194        return out195    }196197    /// Merges per-chunk results into one transcript on the source timeline.198    public static func assemble(chunks: [(range: TimeRange, segments: [TranscriptSegment])], locale: String, provider: String) -> Transcript {199        var all: [TranscriptSegment] = []200        for c in chunks.sorted(by: { $0.range.start < $1.range.start }) {201            for var s in c.segments {202                s.range = TimeRange(start: c.range.start + s.range.start, end: min(c.range.end, c.range.start + s.range.end))203                if !s.text.trimmingCharacters(in: .whitespaces).isEmpty, !s.range.isEmpty { all.append(s) }204            }205        }206        return Transcript(locale: locale, provider: provider, segments: all)207    }208}209210/// Detects a spoken command in a stream of partial transcriptions, once per utterance.211public struct PhraseMatcher: Sendable {212    public let phrase: String213    private let needle: [String]214    private var matchedUpTo = 0215216    public init(phrase: String) { self.phrase = phrase; needle = Self.normalize(phrase) }217218    public static func normalize(_ s: String) -> [String] {219        s.folding(options: [.diacriticInsensitive, .caseInsensitive], locale: nil)220            .components(separatedBy: CharacterSet.alphanumerics.inverted).filter { !$0.isEmpty }221    }222223    /// Feed the full partial transcription of the current recognition task. Returns true when the phrase newly appears.224    public mutating func feed(_ partial: String) -> Bool {225        guard !needle.isEmpty else { return false }226        let words = Self.normalize(partial)227        if words.count < matchedUpTo { matchedUpTo = 0 }                   // a new recognition task started228        guard words.count >= needle.count else { return false }229        var i = max(0, matchedUpTo - needle.count + 1)230        while i + needle.count <= words.count {231            if Array(words[i..<(i + needle.count)]) == needle, i + needle.count > matchedUpTo { matchedUpTo = i + needle.count; return true }232            i += 1233        }234        return false235    }236    public mutating func reset() { matchedUpTo = 0 }237}238
Files main
Menu

Theme