Repository Public
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