Repository Public License
1//2// ORIX Audio3// File: Core/Sources/ORIXAudioCore/Analysis/SpectralMetrics.swift4// Description: Frame-averaged spectral descriptors: centroid, bandwidth, rolloff, flatness, flux, band energy, peaks.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8//9import Accelerate10import Foundation1112public struct BandEnergy: Codable, Sendable, Hashable {13 public var name: String14 public var lowerHz: Double15 public var upperHz: Double16 /// Mean-square power in the band, in dBFS (RMS reference).17 public var decibels: Float18 /// Share of the total 20 Hz–20 kHz power.19 public var fraction: Float20}2122public struct SpectralMetrics: Codable, Sendable, Equatable {23 public var frameCount = 024 public var fftSize = 025 /// Power-weighted mean frequency (Hz), averaged over non-silent frames.26 public var centroidHz: Double = 027 /// Power-weighted standard deviation around the centroid (Hz).28 public var bandwidthHz: Double = 029 /// Frequency below which 85 % of the power lies (Hz).30 public var rolloffHz: Double = 031 /// Geometric / arithmetic mean of the power spectrum: 0 = pure tone, 1 = white noise.32 public var flatness: Double = 033 /// Mean positive change of the normalised magnitude spectrum between consecutive frames (unitless).34 public var flux: Double = 035 /// Strongest component of the long-term average spectrum.36 public var dominantFrequencyHz: Double?37 public var bands: [BandEnergy] = []38 public var peaks: [SpectralPeak] = []39 /// Long-term average spectrum (amplitude dBFS) resampled to 256 log-spaced points, 20 Hz → min(20 kHz, Nyquist).40 public var averageSpectrum: [Float] = []41 public init() {}42}4344/// Streams mono audio through a 50 %-overlap Hann STFT and accumulates descriptors.45public final class SpectralAccumulator {46 public static let rolloffFraction = 0.8547 public let sampleRate: Double48 public let fftSize: Int49 private let fft: RealFFT50 private let layout: FrequencyBandLayout51 private let ranges: [Range<Int>]52 private var pending: [Float] = []53 private var power: [Float]54 private var previousNorm: [Float]55 private var sumPower: [Double]56 private var frames = 0, activeFrames = 0, fluxFrames = 057 private var centroidSum = 0.0, bandwidthSum = 0.0, rolloffSum = 0.0, flatnessSum = 0.0, fluxSum = 0.05859 public init(sampleRate: Double, fftSize: Int = 2048, bands: FrequencyBandLayout = .orix) {60 self.sampleRate = sampleRate; self.fftSize = fftSize; self.layout = bands61 fft = RealFFT(size: fftSize, window: .hann)62 ranges = bands.binRanges(fftSize: fftSize, sampleRate: sampleRate)63 power = [Float](repeating: 0, count: fftSize / 2 + 1)64 previousNorm = []65 sumPower = [Double](repeating: 0, count: fftSize / 2 + 1)66 }6768 public func push(_ s: UnsafeBufferPointer<Float>) {69 pending.append(contentsOf: s)70 var offset = 071 let hop = fftSize / 272 while offset + fftSize <= pending.count {73 pending.withUnsafeBufferPointer { analyse($0.baseAddress! + offset) }74 offset += hop75 }76 if offset > 0 { pending.removeFirst(offset) }77 }7879 public func push(_ s: [Float]) { s.withUnsafeBufferPointer { push($0) } }8081 private func analyse(_ frame: UnsafePointer<Float>) {82 let n = power.count83 power.withUnsafeMutableBufferPointer { p in84 fft.squaredMagnitudes(frame, into: p.baseAddress!)85 fft.scale(p.baseAddress!, to: .power, sampleRate: sampleRate)86 }87 frames += 188 var total = 0.089 for k in 1..<n { total += Double(power[k]); sumPower[k] += Double(power[k]) }90 // Frames below −80 dBFS total power are treated as silence and excluded from shape descriptors.91 guard total > 1e-8 else { previousNorm = []; return }92 activeFrames += 193 let binHz = sampleRate / Double(fftSize)94 var weighted = 0.0, logSum = 0.095 for k in 1..<n { let p = Double(power[k]); weighted += p * Double(k) * binHz; logSum += log(max(p, 1e-20)) }96 let centroid = weighted / total97 var spread = 0.0, cumulative = 0.0, rolloff = 0.0, found = false98 for k in 1..<n {99 let p = Double(power[k]), f = Double(k) * binHz100 spread += p * (f - centroid) * (f - centroid)101 cumulative += p102 if !found && cumulative >= Self.rolloffFraction * total { rolloff = f; found = true }103 }104 centroidSum += centroid105 bandwidthSum += (spread / total).squareRoot()106 rolloffSum += rolloff107 flatnessSum += exp(logSum / Double(n - 1)) / (total / Double(n - 1))108 // Flux on the L2-normalised magnitude spectrum, positive differences only (onset-style).109 var norm = [Float](repeating: 0, count: n)110 var count = Int32(n)111 vvsqrtf(&norm, power, &count)112 var energy: Float = 0113 vDSP_svesq(norm, 1, &energy, vDSP_Length(n))114 if energy > 0 { var g = 1 / energy.squareRoot(); vDSP_vsmul(norm, 1, &g, &norm, 1, vDSP_Length(n)) }115 if previousNorm.count == n {116 var f = 0.0117 for k in 0..<n { let d = norm[k] - previousNorm[k]; if d > 0 { f += Double(d * d) } }118 fluxSum += f.squareRoot(); fluxFrames += 1119 }120 previousNorm = norm121 }122123 public func finish() -> SpectralMetrics {124 var m = SpectralMetrics()125 m.frameCount = frames; m.fftSize = fftSize126 guard frames > 0 else { return m }127 if activeFrames > 0 {128 let a = Double(activeFrames)129 m.centroidHz = centroidSum / a; m.bandwidthHz = bandwidthSum / a; m.rolloffHz = rolloffSum / a; m.flatness = flatnessSum / a130 }131 if fluxFrames > 0 { m.flux = fluxSum / Double(fluxFrames) }132 let mean = sumPower.map { Float($0 / Double(frames)) }133 let enbw = Float(WindowFunction.hann.equivalentNoiseBandwidthBins)134 var bandPower = [Float](repeating: 0, count: ranges.count)135 for (i, r) in ranges.enumerated() { for k in r { bandPower[i] += mean[k] }; bandPower[i] /= enbw }136 let total = bandPower.reduce(0, +)137 m.bands = zip(layout.bands, bandPower).map {138 BandEnergy(name: $0.name, lowerHz: $0.lowerHz, upperHz: $0.upperHz, decibels: Decibels.fromPower($1), fraction: total > 0 ? $1 / total : 0)139 }140 m.dominantFrequencyHz = SpectrumAnalyzer.dominant(inPowerDB: mean, fftSize: fftSize, sampleRate: sampleRate)?.frequency141 // Amplitude dBFS of the average spectrum = power dB + 3.01.142 let amplitudeDB = mean.map { Decibels.fromPower($0) + 3.0103 }143 m.peaks = SpectrumAnalyzer.peaks(in: amplitudeDB, fftSize: fftSize, sampleRate: sampleRate, count: 8, thresholdDB: -90)144 m.averageSpectrum = FrequencyAxis.logarithmic.resample(amplitudeDB, fftSize: fftSize, sampleRate: sampleRate, columns: 256,145 min: 20, max: min(20000, sampleRate / 2))146 return m147 }148}149