Repository Public License
1//2// ORIX Audio3// File: Core/Sources/ORIXAudioCore/DSP/Effects.swift4// Description: Streaming enhancement processors: filters, 3-band EQ, compressor, spectral noise reduction, voice preset.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8//9import Accelerate10import Foundation1112/// A serialisable description of one enhancement step. Parameters are in physical units.13public enum AudioEffect: Codable, Sendable, Hashable {14 /// 24 dB/octave Butterworth high-pass.15 case highPass(frequencyHz: Double)16 /// 24 dB/octave Butterworth low-pass.17 case lowPass(frequencyHz: Double)18 /// Low shelf at 150 Hz, peaking at 1.5 kHz (Q 0.9), high shelf at 6 kHz; gains in dB.19 case equalizer(lowDB: Double, midDB: Double, highDB: Double)20 /// Feed-forward RMS compressor with a 6 dB soft knee.21 case compressor(thresholdDB: Double, ratio: Double, attackMs: Double, releaseMs: Double, makeupDB: Double)22 /// Spectral subtraction against a noise profile measured from the quietest frames of the recording. `strength` in 0…1.23 case noiseReduction(strength: Double)24 /// High-pass 80 Hz, small low cut, presence lift, gentle compression — a fixed chain, not a learned model.25 case voiceEnhance2627 public var displayName: String {28 switch self {29 case .highPass: "High-pass filter"30 case .lowPass: "Low-pass filter"31 case .equalizer: "Equalizer"32 case .compressor: "Compressor"33 case .noiseReduction: "Noise reduction"34 case .voiceEnhance: "Voice enhance"35 }36 }3738 public var isNoiseReduction: Bool { if case .noiseReduction = self { true } else { false } }3940 /// Expands presets into primitive effects.41 var primitives: [AudioEffect] {42 switch self {43 case .voiceEnhance:44 [.highPass(frequencyHz: 80), .equalizer(lowDB: -1.5, midDB: 2.5, highDB: 1.5),45 .compressor(thresholdDB: -22, ratio: 3, attackMs: 8, releaseMs: 120, makeupDB: 4)]46 default: [self]47 }48 }49}5051/// Feed-forward compressor with state that survives chunk boundaries.52public struct Compressor: Sendable {53 public var thresholdDB, ratio, makeupDB: Double54 private let attack, release: Double55 private var envelope = 0.0, gainDB = 0.05657 public init(thresholdDB: Double, ratio: Double, attackMs: Double, releaseMs: Double, makeupDB: Double, sampleRate: Double) {58 self.thresholdDB = thresholdDB; self.ratio = max(1, ratio); self.makeupDB = makeupDB59 attack = exp(-1 / (max(0.1, attackMs) * 0.001 * sampleRate))60 release = exp(-1 / (max(1, releaseMs) * 0.001 * sampleRate))61 }6263 /// Static curve in dB (input level → gain change), 6 dB soft knee (Giannoulis, Massberg & Reiss 2012).64 public static func gainDB(levelDB x: Double, thresholdDB t: Double, ratio r: Double, kneeDB w: Double = 6) -> Double {65 let over = x - t66 if 2 * over < -w { return 0 }67 if 2 * abs(over) <= w { return (1 / r - 1) * (over + w / 2) * (over + w / 2) / (2 * w) }68 return (1 / r - 1) * over69 }7071 public mutating func process(_ s: UnsafeMutableBufferPointer<Float>) {72 for i in s.indices {73 let x = Double(s[i])74 envelope = 0.999 * envelope + 0.001 * x * x75 let target = Self.gainDB(levelDB: 10 * log10(max(envelope, 1e-12)), thresholdDB: thresholdDB, ratio: ratio)76 let c = target < gainDB ? attack : release77 gainDB = c * gainDB + (1 - c) * target78 s[i] = Float(x * pow(10, (gainDB + makeupDB) / 20))79 }80 }81}8283/// Shared STFT plumbing for the noise estimator and the denoiser: 1024-point Hann, 75 % overlap.84final class DenoiseSTFT {85 static let size = 1024, hop = 256, half = 51286 let setup: FFTSetup87 let log2n = vDSP_Length(10)88 let window = WindowFunction.hann.coefficients(count: DenoiseSTFT.size)89 var real = [Float](repeating: 0, count: DenoiseSTFT.half), imag = [Float](repeating: 0, count: DenoiseSTFT.half)90 var frame = [Float](repeating: 0, count: DenoiseSTFT.size)9192 init() { setup = vDSP_create_fftsetup(10, FFTRadix(kFFTRadix2))! }93 deinit { vDSP_destroy_fftsetup(setup) }9495 func forward(_ input: UnsafePointer<Float>) {96 vDSP_vmul(input, 1, window, 1, &frame, 1, vDSP_Length(Self.size))97 real.withUnsafeMutableBufferPointer { rp in imag.withUnsafeMutableBufferPointer { ip in98 var split = DSPSplitComplex(realp: rp.baseAddress!, imagp: ip.baseAddress!)99 frame.withUnsafeBufferPointer { $0.baseAddress!.withMemoryRebound(to: DSPComplex.self, capacity: Self.half) { vDSP_ctoz($0, 2, &split, 1, vDSP_Length(Self.half)) } }100 vDSP_fft_zrip(setup, &split, 1, log2n, FFTDirection(FFT_FORWARD))101 } }102 }103104 /// Inverse transform of the current real/imag into `frame`, windowed and normalised for overlap-add.105 func inverse() {106 real.withUnsafeMutableBufferPointer { rp in imag.withUnsafeMutableBufferPointer { ip in107 var split = DSPSplitComplex(realp: rp.baseAddress!, imagp: ip.baseAddress!)108 vDSP_fft_zrip(setup, &split, 1, log2n, FFTDirection(FFT_INVERSE))109 frame.withUnsafeMutableBufferPointer { $0.baseAddress!.withMemoryRebound(to: DSPComplex.self, capacity: Self.half) { vDSP_ztoc(&split, 1, $0, 2, vDSP_Length(Self.half)) } }110 } }111 // forward (×2) then inverse (×N/… ) of vDSP's packed real FFT yields 2N·x; Hann² at 75 % overlap sums to 1.5.112 var g = 1 / (Float(Self.size) * 2 * 1.5)113 vDSP_vmul(frame, 1, window, 1, &frame, 1, vDSP_Length(Self.size))114 vDSP_vsmul(frame, 1, &g, &frame, 1, vDSP_Length(Self.size))115 }116}117118/// One pass over the audio: keeps the magnitude spectra of the quietest non-silent frames and averages them.119public final class NoiseProfileEstimator {120 public static let keptFrames = 200121 private let stft = DenoiseSTFT()122 private var pending: [Float] = []123 private var kept: [(energy: Float, magnitudes: [Float])] = []124 private var worstKept: Float = .greatestFiniteMagnitude125126 public init() {}127128 public func push(_ s: UnsafeBufferPointer<Float>) {129 pending.append(contentsOf: s)130 var offset = 0131 while offset + DenoiseSTFT.size <= pending.count {132 pending.withUnsafeBufferPointer { stft.forward($0.baseAddress! + offset) }133 var mags = [Float](repeating: 0, count: DenoiseSTFT.half)134 var energy: Float = 0135 for k in 1..<DenoiseSTFT.half { let m = stft.real[k] * stft.real[k] + stft.imag[k] * stft.imag[k]; mags[k] = m.squareRoot(); energy += m }136 // Exactly-silent frames (digital silence, inserted gaps) carry no information about the noise.137 if energy > 1e-9, kept.count < Self.keptFrames || energy < worstKept {138 kept.append((energy, mags))139 if kept.count > Self.keptFrames * 2 { trim() }140 }141 offset += DenoiseSTFT.size / 2142 }143 if offset > 0 { pending.removeFirst(offset) }144 }145146 private func trim() {147 kept.sort { $0.energy < $1.energy }148 kept.removeLast(kept.count - Self.keptFrames)149 worstKept = kept.last?.energy ?? .greatestFiniteMagnitude150 }151152 /// Mean magnitude per bin of the quietest frames, or nil when the audio is too short to estimate anything.153 public func profile() -> [Float]? {154 trim0()155 guard kept.count >= 8 else { return nil }156 var out = [Float](repeating: 0, count: DenoiseSTFT.half)157 for f in kept { vDSP_vadd(out, 1, f.magnitudes, 1, &out, 1, vDSP_Length(DenoiseSTFT.half)) }158 var g = 1 / Float(kept.count)159 vDSP_vsmul(out, 1, &g, &out, 1, vDSP_Length(DenoiseSTFT.half))160 return out161 }162163 private func trim0() { if kept.count > Self.keptFrames { trim() } else { kept.sort { $0.energy < $1.energy } } }164}165166/// Streaming spectral subtraction. Output is delayed by `latency` samples; call `flush` at the end.167public final class SpectralDenoiser {168 public static let latency = DenoiseSTFT.size - DenoiseSTFT.hop169 private let stft = DenoiseSTFT()170 private let noise: [Float]171 private let over: Float, gainFloor: Float172 private var input: [Float]173 private var overlap = [Float](repeating: 0, count: DenoiseSTFT.size)174 private var smoothedGain = [Float](repeating: 1, count: DenoiseSTFT.half)175176 public init(noiseProfile: [Float], strength: Double) {177 noise = noiseProfile178 let s = max(0, min(1, strength))179 over = Float(1 + 2 * s) // over-subtraction 1…3180 gainFloor = Float(pow(10, -(6 + 18 * s) / 20)) // residual floor −6…−24 dB limits musical noise181 input = [Float](repeating: 0, count: Self.latency) // prime so the first hop is fully overlapped182 }183184 /// Consumes `chunk`, appends processed samples to `output`.185 public func process(_ chunk: UnsafeBufferPointer<Float>, into output: inout [Float]) {186 input.append(contentsOf: chunk)187 var offset = 0188 while offset + DenoiseSTFT.size <= input.count {189 input.withUnsafeBufferPointer { stft.forward($0.baseAddress! + offset) }190 for k in 1..<DenoiseSTFT.half {191 let m = (stft.real[k] * stft.real[k] + stft.imag[k] * stft.imag[k]).squareRoot()192 let g = m > 0 ? max(gainFloor, 1 - over * noise[k] / m) : gainFloor193 smoothedGain[k] = 0.6 * smoothedGain[k] + 0.4 * g // temporal smoothing across frames194 stft.real[k] *= smoothedGain[k]; stft.imag[k] *= smoothedGain[k]195 }196 stft.inverse()197 vDSP_vadd(overlap, 1, stft.frame, 1, &overlap, 1, vDSP_Length(DenoiseSTFT.size))198 output.append(contentsOf: overlap[0..<DenoiseSTFT.hop])199 overlap.removeFirst(DenoiseSTFT.hop)200 overlap.append(contentsOf: repeatElement(0, count: DenoiseSTFT.hop))201 offset += DenoiseSTFT.hop202 }203 if offset > 0 { input.removeFirst(offset) }204 }205206 /// Pushes enough zeros to drain the delay line. The caller trims the result to the true length.207 public func flush(into output: inout [Float]) {208 let zeros = [Float](repeating: 0, count: DenoiseSTFT.size * 2)209 zeros.withUnsafeBufferPointer { process($0, into: &output) }210 }211}212213/// A stateful effect chain for one channel. Noise reduction (when present) runs first and delays the signal by214/// `SpectralDenoiser.latency` samples; the renderer compensates for that delay.215public final class EffectChain {216 private enum Stage { case biquad(BiquadCascade), compressor(Compressor) }217 private var denoiser: SpectralDenoiser?218 private var stages: [Stage] = []219 public var latency: Int { denoiser == nil ? 0 : SpectralDenoiser.latency }220221 public init(effects: [AudioEffect], sampleRate fs: Double, noiseProfile: [Float]?) {222 for e in effects.flatMap(\.primitives) {223 switch e {224 case .highPass(let f):225 stages.append(.biquad(BiquadCascade([.highPass(frequency: f, q: 0.5412, sampleRate: fs), .highPass(frequency: f, q: 1.3066, sampleRate: fs)])))226 case .lowPass(let f):227 stages.append(.biquad(BiquadCascade([.lowPass(frequency: f, q: 0.5412, sampleRate: fs), .lowPass(frequency: f, q: 1.3066, sampleRate: fs)])))228 case .equalizer(let lo, let mid, let hi):229 stages.append(.biquad(BiquadCascade([.lowShelf(frequency: 150, gainDB: lo, sampleRate: fs),230 .peaking(frequency: 1500, gainDB: mid, q: 0.9, sampleRate: fs),231 .highShelf(frequency: 6000, gainDB: hi, sampleRate: fs)])))232 case .compressor(let t, let r, let a, let rel, let m):233 stages.append(.compressor(Compressor(thresholdDB: t, ratio: r, attackMs: a, releaseMs: rel, makeupDB: m, sampleRate: fs)))234 case .noiseReduction(let strength):235 if denoiser == nil, let noiseProfile { denoiser = SpectralDenoiser(noiseProfile: noiseProfile, strength: strength) }236 case .voiceEnhance: break237 }238 }239 }240241 /// Processes a chunk and returns the samples that are ready (fewer than the input while the denoiser fills).242 public func process(_ chunk: [Float]) -> [Float] {243 var out: [Float]244 if let denoiser {245 out = []; out.reserveCapacity(chunk.count + DenoiseSTFT.size)246 chunk.withUnsafeBufferPointer { denoiser.process($0, into: &out) }247 } else { out = chunk }248 runStages(&out)249 return out250 }251252 public func flush() -> [Float] {253 guard let denoiser else { return [] }254 var out: [Float] = []255 denoiser.flush(into: &out)256 runStages(&out)257 return out258 }259260 private func runStages(_ out: inout [Float]) {261 guard !out.isEmpty else { return }262 for i in stages.indices {263 switch stages[i] {264 case .biquad(var c): c.process(&out); stages[i] = .biquad(c)265 case .compressor(var c): out.withUnsafeMutableBufferPointer { c.process($0) }; stages[i] = .compressor(c)266 }267 }268 }269}270