SPB Git

Repository Public License

WaveformSummary.swift 10.8 KB 222 lines swift

1//2//  ORIX Audio3//  File: Core/Sources/ORIXAudioCore/DSP/WaveformSummary.swift4//  Description: Multi-resolution waveform summary (min / max / RMS + per-band energy from a real FFT) for drawing and caching.5//6//  Author: Simon-Pierre Boucher7//  Contact: contact@spboucher.ai8//9import Accelerate10import Foundation1112/// One time bucket of a waveform. The band energies come from an FFT of the bucket's samples, so the colour of a13/// bucket is a measurement of its spectral content — never a decoration.14public struct WaveformBucket: Sendable, Equatable {15    public var min: Float16    public var max: Float17    public var rms: Float18    /// Mean-square power in each of the seven ORIX bands (linear).19    public var bands: SIMD8<Float>2021    public init(min: Float = 0, max: Float = 0, rms: Float = 0, bands: SIMD8<Float> = .zero) {22        self.min = min; self.max = max; self.rms = rms; self.bands = bands23    }2425    public var peak: Float { Swift.max(abs(min), abs(max)) }2627    /// Fraction of the bucket's band-limited power in each band (sums to 1, or all zero for silence).28    public var bandFractions: [Float] {29        var total: Float = 030        for i in 0..<FrequencyBandLayout.bandCount { total += bands[i] }31        guard total > 1e-12 else { return [Float](repeating: 0, count: FrequencyBandLayout.bandCount) }32        return (0..<FrequencyBandLayout.bandCount).map { bands[$0] / total }33    }3435    /// Share of each band by RMS amplitude (square root of band power), summing to 1. Used for colour mixing: amplitude36    /// weighting keeps quieter high bands visible next to strong bass, where power weighting would hide them.37    public var bandAmplitudeFractions: [Float] {38        var total: Float = 039        var out = [Float](repeating: 0, count: FrequencyBandLayout.bandCount)40        for i in 0..<FrequencyBandLayout.bandCount { out[i] = bands[i].squareRoot(); total += out[i] }41        guard total > 1e-6 else { return [Float](repeating: 0, count: FrequencyBandLayout.bandCount) }42        return out.map { $0 / total }43    }4445    /// Index of the band holding the most power, or nil for silence.46    public var dominantBand: Int? {47        var best = -1; var value: Float = 1e-1248        for i in 0..<FrequencyBandLayout.bandCount where bands[i] > value { value = bands[i]; best = i }49        return best >= 0 ? best : nil50    }5152    /// Power-weighted mean band index in [0, 6]: a compact "spectral colour" coordinate.53    public var bandCentroid: Float? {54        var total: Float = 0, weighted: Float = 055        for i in 0..<FrequencyBandLayout.bandCount { total += bands[i]; weighted += bands[i] * Float(i) }56        return total > 1e-12 ? weighted / total : nil57    }5859    static func merged(_ a: WaveformBucket, _ b: WaveformBucket) -> WaveformBucket {60        WaveformBucket(min: Swift.min(a.min, b.min), max: Swift.max(a.max, b.max),61                       rms: ((a.rms * a.rms + b.rms * b.rms) / 2).squareRoot(), bands: (a.bands + b.bands) * 0.5)62    }63}6465/// Pyramid of bucket arrays: level 0 has `samplesPerBucket` samples per bucket, each higher level halves the resolution.66public struct WaveformSummary: Sendable {67    public static let defaultSamplesPerBucket = 51268    public var sampleRate: Double69    public var samplesPerBucket: Int70    public var totalSamples: Int71    public var levels: [[WaveformBucket]]7273    public var duration: Double { Double(totalSamples) / sampleRate }7475    /// The coarsest level that still gives at least `points` buckets across `timeRange` (seconds).76    public func buckets(for timeRange: ClosedRange<Double>, points: Int) -> (buckets: ArraySlice<WaveformBucket>, secondsPerBucket: Double) {77        guard let base = levels.first, !base.isEmpty else { return ([], 0) }78        let span = max(1e-6, timeRange.upperBound - timeRange.lowerBound)79        var level = 080        while level + 1 < levels.count {81            let next = Double(samplesPerBucket << (level + 1)) / sampleRate82            if span / next < Double(points) { break }83            level += 184        }85        let spb = Double(samplesPerBucket << level) / sampleRate86        let arr = levels[level]87        let lo = max(0, min(arr.count, Int(timeRange.lowerBound / spb)))88        let hi = max(lo, min(arr.count, Int((timeRange.upperBound / spb).rounded(.up))))89        return (arr[lo..<hi], spb)90    }9192    // MARK: Cache serialisation (little-endian, versioned)9394    private static let magic: UInt32 = 0x4F57_4631   // "OWF1"9596    public func serialized() -> Data {97        var d = Data()98        func put<T>(_ v: T) { withUnsafeBytes(of: v) { d.append(contentsOf: $0) } }99        put(Self.magic); put(sampleRate); put(Int64(samplesPerBucket)); put(Int64(totalSamples)); put(Int64(levels.first?.count ?? 0))100        for b in levels.first ?? [] {101            put(b.min); put(b.max); put(b.rms)102            for i in 0..<FrequencyBandLayout.bandCount { put(b.bands[i]) }103        }104        return d105    }106107    public init?(serialized d: Data) {108        var offset = 0109        func get<T>(_ type: T.Type) -> T? {110            let size = MemoryLayout<T>.size111            guard offset + size <= d.count else { return nil }112            defer { offset += size }113            return d.withUnsafeBytes { $0.loadUnaligned(fromByteOffset: offset, as: T.self) }114        }115        guard get(UInt32.self) == Self.magic, let sr = get(Double.self), let spb = get(Int64.self), let total = get(Int64.self),116              let count = get(Int64.self), count >= 0, d.count >= offset + Int(count) * 40 else { return nil }117        var base = [WaveformBucket](); base.reserveCapacity(Int(count))118        for _ in 0..<count {119            guard let mn = get(Float.self), let mx = get(Float.self), let r = get(Float.self) else { return nil }120            var bands = SIMD8<Float>.zero121            for i in 0..<FrequencyBandLayout.bandCount { guard let v = get(Float.self) else { return nil }; bands[i] = v }122            base.append(WaveformBucket(min: mn, max: mx, rms: r, bands: bands))123        }124        self.init(sampleRate: sr, samplesPerBucket: Int(spb), totalSamples: Int(total), base: base)125    }126127    public init(sampleRate: Double, samplesPerBucket: Int, totalSamples: Int, base: [WaveformBucket]) {128        self.sampleRate = sampleRate; self.samplesPerBucket = samplesPerBucket; self.totalSamples = totalSamples129        var levels = [base]130        while let last = levels.last, last.count > 256 {131            var next = [WaveformBucket](); next.reserveCapacity(last.count / 2 + 1)132            var i = 0133            while i + 1 < last.count { next.append(.merged(last[i], last[i + 1])); i += 2 }134            if i < last.count { next.append(last[i]) }135            levels.append(next)136        }137        self.levels = levels138    }139}140141/// Streaming builder: push mono samples in any chunk size, read finished buckets. Used live (recording) and offline (files).142///143/// Each bucket's band energies come from a 4096-point Hann FFT of the samples *ending* at the bucket's last sample144/// (a causal window, so the live display needs no look-ahead). 4096 points give 11.7 Hz bins at 48 kHz, enough to145/// separate the sub-bass band from the bass band; the price is that colour reacts over ~85 ms while min/max/RMS are exact per bucket.146public final class WaveformProcessor {147    public static let fftSize = 4096148    public let sampleRate: Double149    public let samplesPerBucket: Int150    private let fft: RealFFT151    private let ranges: [Range<Int>]152    private var work: [Float]153    private var frame: [Float]154    private var spectrum: [Float]155    private let enbw: Float156    private let historyCount: Int157    public private(set) var totalSamples = 0158159    public init(sampleRate: Double, samplesPerBucket: Int = WaveformSummary.defaultSamplesPerBucket, bands: FrequencyBandLayout = .orix) {160        precondition(samplesPerBucket <= Self.fftSize)161        self.sampleRate = sampleRate162        self.samplesPerBucket = samplesPerBucket163        self.fft = RealFFT(size: Self.fftSize, window: .hann)164        self.ranges = bands.binRanges(fftSize: Self.fftSize, sampleRate: sampleRate)165        self.historyCount = Self.fftSize - samplesPerBucket166        self.work = [Float](repeating: 0, count: Self.fftSize - samplesPerBucket)167        self.frame = [Float](repeating: 0, count: Self.fftSize)168        self.spectrum = [Float](repeating: 0, count: Self.fftSize / 2 + 1)169        self.enbw = Float(WindowFunction.hann.equivalentNoiseBandwidthBins)170    }171172    /// Appends samples; completed buckets are appended to `output`.173    public func push(_ samples: UnsafeBufferPointer<Float>, into output: inout [WaveformBucket]) {174        work.append(contentsOf: samples)175        totalSamples += samples.count176        var offset = 0177        while offset + Self.fftSize <= work.count {178            output.append(bucket(frameStart: offset, bucketCount: samplesPerBucket))179            offset += samplesPerBucket180        }181        if offset > 0 { work.removeFirst(offset) }182    }183184    /// Flushes a trailing partial bucket (end of file / stop).185    public func finish(into output: inout [WaveformBucket]) {186        let remainder = work.count - historyCount187        guard remainder > 0 else { return }188        work.append(contentsOf: repeatElement(0, count: samplesPerBucket - remainder))189        output.append(bucket(frameStart: 0, bucketCount: remainder))190        work.removeFirst(samplesPerBucket)191    }192193    private func bucket(frameStart: Int, bucketCount: Int) -> WaveformBucket {194        var mn: Float = 0, mx: Float = 0, ms: Float = 0195        var bands = SIMD8<Float>.zero196        work.withUnsafeBufferPointer { p in197            let base = p.baseAddress! + frameStart + historyCount198            vDSP_minv(base, 1, &mn, vDSP_Length(bucketCount))199            vDSP_maxv(base, 1, &mx, vDSP_Length(bucketCount))200            vDSP_measqv(base, 1, &ms, vDSP_Length(bucketCount))201            spectrum.withUnsafeMutableBufferPointer { s in202                fft.squaredMagnitudes(p.baseAddress! + frameStart, into: s.baseAddress!)203                fft.scale(s.baseAddress!, to: .power, sampleRate: sampleRate)204                for (i, r) in ranges.enumerated() {205                    var sum: Float = 0206                    if !r.isEmpty { vDSP_sve(s.baseAddress! + r.lowerBound, 1, &sum, vDSP_Length(r.count)) }207                    bands[i] = sum / enbw208                }209            }210        }211        return WaveformBucket(min: mn, max: mx, rms: ms.squareRoot(), bands: bands)212    }213214    public static func summarize(_ samples: [Float], sampleRate: Double, samplesPerBucket: Int = WaveformSummary.defaultSamplesPerBucket) -> WaveformSummary {215        let p = WaveformProcessor(sampleRate: sampleRate, samplesPerBucket: samplesPerBucket)216        var buckets: [WaveformBucket] = []217        samples.withUnsafeBufferPointer { p.push($0, into: &buckets) }218        p.finish(into: &buckets)219        return WaveformSummary(sampleRate: sampleRate, samplesPerBucket: samplesPerBucket, totalSamples: samples.count, base: buckets)220    }221}222
Files main
Menu

Theme