Repository Public License
1//2// ORIX Audio3// File: ORIXAudio/Services/AudioCaptureEngine.swift4// Description: Microphone capture: tap → ring buffers → writer thread (crash-safe CAF master) and analysis thread (live visuals).5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8//9import Accelerate10import AVFoundation11import Foundation12import ORIXAudioCore13import Synchronization1415struct LiveLevels: Sendable, Equatable {16 var rmsDB: Float = Decibels.floor17 var peakDB: Float = Decibels.floor18 var peakHoldDB: Float = Decibels.floor19 var isClipping = false20 var momentaryLUFS: Double?21}2223/// Visual data produced by the analysis thread and read by the UI at its own pace. The two sides never wait on each other24/// for longer than a memcpy; the capture path doesn't touch this at all.25final class LiveVisuals: Sendable {26 static let bucketHistory = 8192 // ≈ 87 s at 48 kHz27 static let columnHistory = 1024 // ≈ 11 s at 48 kHz with the live STFT settings28 static let spectrogramConfiguration = SpectrogramConfiguration(fftSize: 1024, hopSize: 512)2930 struct State: Sendable {31 var sampleRate = 48_000.032 var buckets: [WaveformBucket] = []33 var bucketBase = 0 // absolute index of buckets[0]34 var columns: [Float] = []35 var columnBase = 036 var binCount = LiveVisuals.spectrogramConfiguration.fftSize / 2 + 137 var spectrum: SpectrumFrame?38 var levels = LiveLevels()39 var recentSamples: [Float] = [] // last 4096 mono samples, for the oscilloscope-style view40 }41 private let state = Mutex(State())4243 func read<T: Sendable>(_ body: (State) -> T) -> T { state.withLock { body($0) } }44 func write(_ body: (inout State) -> Void) { state.withLock { body(&$0) } }45 func reset(sampleRate: Double) { state.withLock { $0 = State(); $0.sampleRate = sampleRate } }4647 /// New waveform buckets since absolute index `after`, plus the new total.48 func buckets(after: Int) -> (new: [WaveformBucket], total: Int) {49 state.withLock { s in50 let total = s.bucketBase + s.buckets.count51 let from = max(after, s.bucketBase) - s.bucketBase52 return (from < s.buckets.count ? Array(s.buckets[from...]) : [], total)53 }54 }5556 /// New spectrogram columns since absolute index `after`.57 func columns(after: Int) -> (new: [Float], total: Int, binCount: Int) {58 state.withLock { s in59 let total = s.columnBase + s.columns.count / s.binCount60 let from = (max(after, s.columnBase) - s.columnBase) * s.binCount61 return (from < s.columns.count ? Array(s.columns[from...]) : [], total, s.binCount)62 }63 }64}6566enum CaptureError: Error, LocalizedError {67 case noInput, engineStart(String), writer(String)68 var errorDescription: String? {69 switch self {70 case .noInput: String(localized: "The selected input isn't delivering audio.")71 case .engineStart(let m): String(localized: "Recording couldn't start (\(m)).")72 case .writer(let m): String(localized: "The recording file couldn't be written (\(m)).")73 }74 }75}7677/// Owns the AVAudioEngine input tap and the two worker threads.78///79/// Threading: the tap block only copies samples into two wait-free ring buffers. A writer thread drains one into the CAF80/// master (and fsyncs every two seconds); an analysis thread drains the other into the DSP used for meters and visuals.81/// A stalled UI or a slow FFT can therefore never delay a write, and a slow disk can never block the audio tap.82final class AudioCaptureEngine: @unchecked Sendable {83 enum Phase: Int { case idle, recording, paused, stopping }84 static let minimumFreeBytes: Int64 = 64 * 1024 * 10248586 let format: CaptureFormat87 let url: URL88 let visuals = LiveVisuals()89 /// Called on the analysis thread with each mono chunk (used by optional live transcription).90 var onMonoChunk: (@Sendable ([Float], Double) -> Void)?91 /// Called once, from the writer thread, when free space runs out or a write fails.92 var onFailure: (@Sendable (String) -> Void)?93 let spectrumConfiguration = Mutex(SpectrumConfiguration())9495 private let engine = AVAudioEngine()96 private let writer: CAFWriter97 private let writerRing: SPSCRingBuffer98 private let analysisRing: SPSCRingBuffer99 private let phase = Atomic<Int>(Phase.idle.rawValue)100 private let accepted = Atomic<Int>(0)101 private let written = Atomic<Int>(0)102 private let writerDone = DispatchSemaphore(value: 0)103 private let analysisDone = DispatchSemaphore(value: 0)104 private var converter: AVAudioConverter?105 private var conversionFormat: AVAudioFormat?106 private var interleaveScratch: [Float] = []107 private var monoScratch: [Float] = []108 private var configurationObserver: NSObjectProtocol?109 private var threadsStarted = false110111 var framesAccepted: Int { accepted.load(ordering: .relaxed) }112 var framesWritten: Int { written.load(ordering: .relaxed) }113 var droppedSamples: Int { writerRing.droppedSamples }114 var duration: Double { Double(framesAccepted) / format.sampleRate }115 var currentPhase: Phase { Phase(rawValue: phase.load(ordering: .relaxed)) ?? .idle }116 var isEngineRunning: Bool { engine.isRunning }117 var inputFormat: AVAudioFormat { engine.inputNode.outputFormat(forBus: 0) }118119 #if DEBUG120 /// Test harness only (never compiled into release builds): when set, audio comes from this file, paced in real time,121 /// and flows through exactly the same rings, writer and analysis threads as microphone audio.122 nonisolated(unsafe) static var debugInputFile: URL?123 private var debugFile: AVAudioFile?124 #endif125126 /// The audio session must already be active. The capture format follows what the hardware delivers.127 init(url: URL, preset: RecordingPreset) throws {128 #if DEBUG129 if let file = Self.debugInputFile.flatMap({ try? AVAudioFile(forReading: $0) }) { debugFile = file }130 let input = debugFile?.processingFormat ?? engine.inputNode.outputFormat(forBus: 0)131 #else132 let input = engine.inputNode.outputFormat(forBus: 0)133 #endif134 guard input.sampleRate > 0, input.channelCount > 0 else { throw CaptureError.noInput }135 let channels = preset.prefersStereo && input.channelCount >= 2 ? 2 : 1136 format = CaptureFormat(sampleRate: input.sampleRate, channels: channels, sampleFormat: preset.masterFormat)137 self.url = url138 do { writer = try CAFWriter(url: url, format: format, protection: LibraryFiles.protection) }139 catch { throw CaptureError.writer(error.localizedDescription) }140 writerRing = SPSCRingBuffer(minimumCapacity: Int(format.sampleRate) * channels * 4)141 analysisRing = SPSCRingBuffer(minimumCapacity: Int(format.sampleRate) * 2)142 visuals.reset(sampleRate: format.sampleRate)143 }144145 func start() throws {146 #if DEBUG147 if let debugFile {148 phase.store(Phase.recording.rawValue, ordering: .relaxed)149 let feeder = Thread { [self] in debugFeedLoop(debugFile) }; feeder.name = "ai.spboucher.orix.audio.debug-input"; feeder.start()150 } else {151 try installTapAndStart()152 phase.store(Phase.recording.rawValue, ordering: .relaxed)153 }154 #else155 try installTapAndStart()156 phase.store(Phase.recording.rawValue, ordering: .relaxed)157 #endif158 if !threadsStarted {159 threadsStarted = true160 let w = Thread { [self] in writerLoop() }; w.name = "ai.spboucher.orix.audio.writer"; w.qualityOfService = .userInitiated; w.start()161 let a = Thread { [self] in analysisLoop() }; a.name = "ai.spboucher.orix.audio.analysis"; a.qualityOfService = .userInteractive; a.start()162 }163 configurationObserver = NotificationCenter.default.addObserver(forName: .AVAudioEngineConfigurationChange, object: engine, queue: nil) { [weak self] _ in164 // The route changed (headphones, Bluetooth, USB…): the engine has stopped and its input format may differ.165 guard let self, self.currentPhase == .recording || self.currentPhase == .paused else { return }166 try? self.installTapAndStart()167 }168 }169170 private func installTapAndStart() throws {171 let input = engine.inputNode172 input.removeTap(onBus: 0)173 let tapFormat = input.outputFormat(forBus: 0)174 guard tapFormat.sampleRate > 0, tapFormat.channelCount > 0 else { throw CaptureError.noInput }175 if abs(tapFormat.sampleRate - format.sampleRate) > 0.5 {176 // Keep the master at its original rate: resample the new route's audio.177 let target = AVAudioFormat(commonFormat: .pcmFormatFloat32, sampleRate: format.sampleRate, channels: tapFormat.channelCount, interleaved: false)178 conversionFormat = target179 converter = target.flatMap { AVAudioConverter(from: tapFormat, to: $0) }180 } else { converter = nil; conversionFormat = nil }181 input.installTap(onBus: 0, bufferSize: 4096, format: tapFormat) { [weak self] buffer, _ in self?.ingest(buffer) }182 engine.prepare()183 do { try engine.start() } catch { throw CaptureError.engineStart(error.localizedDescription) }184 }185186 #if DEBUG187 private func debugFeedLoop(_ file: AVAudioFile) {188 let chunk: AVAudioFrameCount = 2048189 guard let buffer = AVAudioPCMBuffer(pcmFormat: file.processingFormat, frameCapacity: chunk) else { return }190 let interval = Double(chunk) / file.processingFormat.sampleRate191 var next = Date()192 while phase.load(ordering: .relaxed) != Phase.stopping.rawValue {193 if phase.load(ordering: .relaxed) == Phase.recording.rawValue {194 if file.framePosition >= file.length { file.framePosition = 0 }195 if (try? file.read(into: buffer, frameCount: chunk)) != nil, buffer.frameLength > 0 { ingest(buffer) }196 }197 next = next.addingTimeInterval(interval)198 let wait = next.timeIntervalSinceNow199 if wait > 0 { Thread.sleep(forTimeInterval: wait) } else if wait < -0.5 { next = Date() }200 }201 }202 #endif203204 func pause() { if currentPhase == .recording { phase.store(Phase.paused.rawValue, ordering: .relaxed) } }205206 /// Resumes after a pause or an interruption; restarts the engine when the system stopped it.207 func resume() throws {208 guard currentPhase == .paused || currentPhase == .recording else { return }209 #if DEBUG210 if debugFile == nil, !engine.isRunning { try installTapAndStart() }211 #else212 if !engine.isRunning { try installTapAndStart() }213 #endif214 phase.store(Phase.recording.rawValue, ordering: .relaxed)215 }216217 /// Stops capture, drains both rings, closes the master. Blocks briefly; call off the main thread.218 func stop() {219 guard currentPhase != .idle, currentPhase != .stopping else { return }220 engine.inputNode.removeTap(onBus: 0)221 engine.stop()222 if let configurationObserver { NotificationCenter.default.removeObserver(configurationObserver) }223 phase.store(Phase.stopping.rawValue, ordering: .relaxed)224 if threadsStarted { writerDone.wait(); analysisDone.wait() }225 }226227 // MARK: Tap thread228229 private func ingest(_ buffer: AVAudioPCMBuffer) {230 guard phase.load(ordering: .relaxed) == Phase.recording.rawValue else { return }231 var source = buffer232 if let converter, let conversionFormat {233 let capacity = AVAudioFrameCount(Double(buffer.frameLength) * conversionFormat.sampleRate / buffer.format.sampleRate) + 64234 guard let out = AVAudioPCMBuffer(pcmFormat: conversionFormat, frameCapacity: capacity) else { return }235 nonisolated(unsafe) var supplied = false236 nonisolated(unsafe) let input = buffer237 var error: NSError?238 converter.convert(to: out, error: &error) { _, status in239 if supplied { status.pointee = .noDataNow; return nil }240 supplied = true; status.pointee = .haveData; return input241 }242 guard error == nil else { return }243 source = out244 }245 let n = Int(source.frameLength)246 guard n > 0, let data = source.floatChannelData else { return }247 let sourceChannels = Int(source.format.channelCount), channels = format.channels248 if monoScratch.count < n { monoScratch = [Float](repeating: 0, count: n * 2) }249 if interleaveScratch.count < n * channels { interleaveScratch = [Float](repeating: 0, count: n * channels * 2) }250 // Mono mix for analysis (and for a mono master fed by a multichannel input).251 monoScratch.withUnsafeMutableBufferPointer { mono in252 mono.baseAddress!.update(from: data[0], count: n)253 if sourceChannels > 1 {254 for c in 1..<sourceChannels { vDSP_vadd(mono.baseAddress!, 1, data[c], 1, mono.baseAddress!, 1, vDSP_Length(n)) }255 var g = 1 / Float(sourceChannels)256 vDSP_vsmul(mono.baseAddress!, 1, &g, mono.baseAddress!, 1, vDSP_Length(n))257 }258 analysisRing.write(mono.baseAddress!, count: n)259 if channels == 1 { writerRing.write(mono.baseAddress!, count: n) }260 }261 if channels == 2 {262 interleaveScratch.withUnsafeMutableBufferPointer { out in263 var zero: Float = 0264 vDSP_vsadd(data[0], 1, &zero, out.baseAddress!, 2, vDSP_Length(n))265 vDSP_vsadd(data[min(1, sourceChannels - 1)], 1, &zero, out.baseAddress! + 1, 2, vDSP_Length(n))266 writerRing.write(out.baseAddress!, count: n * 2)267 }268 }269 accepted.add(n, ordering: .relaxed)270 }271272 // MARK: Writer thread273274 private func writerLoop() {275 let channels = format.channels276 var buffer = [Float](repeating: 0, count: 16_384 * channels)277 var lastSync = Date(), lastSpaceCheck = Date()278 var failed = false279 while true {280 let n = buffer.withUnsafeMutableBufferPointer { writerRing.read(into: $0.baseAddress!, maxCount: $0.count) }281 if n > 0 {282 if !failed {283 do {284 try buffer.withUnsafeBufferPointer { try writer.write(interleaved: $0.baseAddress!, frames: n / channels) }285 written.add(n / channels, ordering: .relaxed)286 } catch { failed = true; onFailure?(error.localizedDescription) }287 }288 } else if phase.load(ordering: .relaxed) == Phase.stopping.rawValue {289 break290 } else {291 Thread.sleep(forTimeInterval: 0.02)292 }293 let now = Date()294 if now.timeIntervalSince(lastSync) >= 2 { try? writer.synchronize(); lastSync = now } // checkpoint295 if now.timeIntervalSince(lastSpaceCheck) >= 5 {296 lastSpaceCheck = now297 if !failed, LibraryFiles.freeDiskSpace() < Self.minimumFreeBytes { failed = true; onFailure?(String(localized: "Storage is almost full. The recording was stopped and saved.")) }298 }299 }300 try? writer.close()301 writerDone.signal()302 }303304 // MARK: Analysis thread305306 private func analysisLoop() {307 let fs = format.sampleRate308 let waveform = WaveformProcessor(sampleRate: fs)309 let spectrogram = SpectrogramProcessor(sampleRate: fs, configuration: LiveVisuals.spectrogramConfiguration)310 var analyzer = SpectrumAnalyzer(sampleRate: fs, configuration: spectrumConfiguration.withLock { $0 })311 var loudness = LoudnessMeter(sampleRate: fs, channels: 1)312 var chunk = [Float](repeating: 0, count: 8192)313 var recent = [Float](repeating: 0, count: 32_768) // sliding window feeding the spectrum FFT314 var levels = LiveLevels()315 var clipUntil = Date.distantPast, lastFrame = Date()316 var peakHold: Float = Decibels.floor317 while true {318 let n = chunk.withUnsafeMutableBufferPointer { analysisRing.read(into: $0.baseAddress!, maxCount: $0.count) }319 if n == 0 {320 if phase.load(ordering: .relaxed) == Phase.stopping.rawValue { break }321 // Meters fall back while paused or interrupted.322 if phase.load(ordering: .relaxed) != Phase.recording.rawValue, levels.rmsDB > Decibels.floor {323 levels = LiveLevels(); visuals.write { $0.levels = levels }324 }325 Thread.sleep(forTimeInterval: 0.015)326 continue327 }328 let samples = Array(chunk[0..<n])329 recent.removeFirst(n); recent.append(contentsOf: samples)330331 var newBuckets: [WaveformBucket] = [], newColumns: [Float] = []332 samples.withUnsafeBufferPointer { p in333 waveform.push(p, into: &newBuckets)334 spectrogram.push(p, into: &newColumns)335 }336 loudness.push(mono: samples)337338 var peak: Float = 0, meanSquare: Float = 0339 vDSP_maxmgv(samples, 1, &peak, vDSP_Length(n))340 vDSP_measqv(samples, 1, &meanSquare, vDSP_Length(n))341 let now = Date(), dt = Float(now.timeIntervalSince(lastFrame))342 lastFrame = now343 let peakDB = Decibels.fromAmplitude(peak), rmsDB = Decibels.fromPower(meanSquare)344 if peak >= TimeDomainAccumulator.clipThreshold { clipUntil = now.addingTimeInterval(1.5) }345 peakHold = max(peakDB, peakHold - 9 * dt) // 9 dB/s fall-back346 levels.rmsDB = max(rmsDB, levels.rmsDB - 30 * dt) // fast attack, 30 dB/s release347 levels.peakDB = max(peakDB, levels.peakDB - 40 * dt)348 levels.peakHoldDB = peakHold349 levels.isClipping = now < clipUntil350 levels.momentaryLUFS = loudness.momentaryLUFS351352 let wanted = spectrumConfiguration.withLock { $0 }353 if wanted != analyzer.configuration { analyzer.update(wanted) }354 let size = analyzer.configuration.fftSize355 let frame = recent.withUnsafeBufferPointer { analyzer.process($0.baseAddress! + (recent.count - size), elapsed: Double(dt)) }356357 let snapshot = levels358 visuals.write { s in359 s.buckets.append(contentsOf: newBuckets)360 if s.buckets.count > LiveVisuals.bucketHistory { let drop = s.buckets.count - LiveVisuals.bucketHistory; s.buckets.removeFirst(drop); s.bucketBase += drop }361 s.columns.append(contentsOf: newColumns)362 let maxValues = LiveVisuals.columnHistory * s.binCount363 if s.columns.count > maxValues { let drop = (s.columns.count - maxValues) / s.binCount; s.columns.removeFirst(drop * s.binCount); s.columnBase += drop }364 s.spectrum = frame365 s.levels = snapshot366 s.recentSamples = Array(recent.suffix(4096))367 }368 onMonoChunk?(samples, fs)369 }370 analysisDone.signal()371 }372}373