SPB Git

Repository Public License

SpectralMetrics.swift 6.9 KB 149 lines swift

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
Files main
Menu

Theme