Repository Public License
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