Repository Public
1// ORIX DJ2// File: Packages/ORIXDJCore/Tests/ORIXAnalysisTests/AnalyzerTests.swift3// Description: Functional tests of the analysis engine: loudness, waveform, robustness, cancellation, models, timing.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai7import Foundation8import Testing9import ORIXAnalysis1011final class Counter: @unchecked Sendable {12 var values: [Double] = []13 var polls = 014}1516@Suite struct LoudnessTests {17 @Test func stereoSineAtMinus20dBFSIsMinus20LUFS() throws {18 for rate in [44100.0, 48000.0] {19 let x = SignalSynth.sine(frequency: 1000, seconds: 10, sampleRate: rate, amplitude: 0.1)20 let r = try analyze(x, x.map { $0 }, sampleRate: rate)21 #expect(abs(r.integratedLUFS - (-20)) < 0.15, "LUFS \(r.integratedLUFS) at \(rate)")22 #expect(abs(r.peakDBFS - (-20)) < 0.05)23 #expect(abs(r.suggestedGainDB - 6) < 0.2)24 }25 }2627 @Test func referenceLevelsOfTheStandard() throws {28 // BS.1770: a 0 dBFS 997 Hz sine in ONE channel reads -3.01 LKFS; in both channels 0.0.29 let x = SignalSynth.sine(frequency: 997, seconds: 10, sampleRate: 48000, amplitude: 1)30 let silent = [Float](repeating: 0, count: x.count)31 let one = try analyze(x, silent, sampleRate: 48000)32 let both = try analyze(x, x.map { $0 }, sampleRate: 48000)33 let dualMono = try analyze(x, sampleRate: 48000)34 #expect(abs(one.integratedLUFS - (-3.01)) < 0.1, "one channel: \(one.integratedLUFS)")35 #expect(abs(both.integratedLUFS - 0) < 0.1, "both channels: \(both.integratedLUFS)")36 #expect(abs(dualMono.integratedLUFS - both.integratedLUFS) < 0.01)37 // Full-scale input must be turned down: -14 LUFS target and the -1 dBFS peak ceiling both apply.38 #expect(both.suggestedGainDB < -13.5)39 }4041 @Test func gatingIgnoresSilenceAndMuchQuieterPassages() throws {42 let rate = 44100.043 let loud = SignalSynth.sine(frequency: 1000, seconds: 10, sampleRate: rate, amplitude: 0.1)44 let reference = try analyze(loud).integratedLUFS45 let withSilence = try analyze(loud + [Float](repeating: 0, count: Int(20 * rate))).integratedLUFS46 #expect(abs(withSilence - reference) < 0.1, "absolute gate: \(withSilence) vs \(reference)")47 // 20 dB quieter half: below the relative gate (-10 LU), so it must not pull the result down (ungated would be -23).48 let quiet = SignalSynth.sine(frequency: 1000, seconds: 10, sampleRate: rate, amplitude: 0.01)49 let mixed = try analyze(loud + quiet).integratedLUFS50 #expect(abs(mixed - reference) < 0.2, "relative gate: \(mixed) vs \(reference)")51 // 6 dB quieter half: above the relative gate, so it does count.52 let softer = SignalSynth.sine(frequency: 1000, seconds: 10, sampleRate: rate, amplitude: 0.05)53 let averaged = try analyze(loud + softer).integratedLUFS54 #expect(averaged < reference - 1.5 && averaged > reference - 3)55 }5657 @Test func peakCeilingLimitsTheSuggestedGain() throws {58 // Quiet on average but with a full-scale click: gain is limited by the -1 dBFS ceiling.59 var x = SignalSynth.pinkNoise(seconds: 8, sampleRate: testSampleRate, amplitude: 0.02)60 x[1000] = 0.9961 let r = try analyze(x)62 #expect(r.integratedLUFS < -30)63 #expect(abs(r.suggestedGainDB - (-1 - r.peakDBFS)) < 1e-9)64 #expect(r.peakDBFS + r.suggestedGainDB <= -1 + 1e-9)65 }66}6768@Suite struct WaveformTests {69 func means(_ w: WaveformSummary) -> (low: Double, mid: Double, high: Double, peak: Double) {70 // skip the first and last 100 ms (filter transients)71 let range = 15..<(w.count - 15)72 func mean(_ a: [UInt8]) -> Double { range.reduce(0.0) { $0 + Double(a[$1]) } / Double(range.count) }73 return (mean(w.low), mean(w.mid), mean(w.high), mean(w.peak))74 }7576 @Test func bandSeparation() throws {77 let low = means(try analyze(SignalSynth.sine(frequency: 60, seconds: 3, sampleRate: testSampleRate)).waveform)78 #expect(low.low > 170 && low.mid < 0.1 * low.low && low.high < 0.02 * low.low, "60 Hz: \(low)")79 let mid = means(try analyze(SignalSynth.sine(frequency: 1000, seconds: 3, sampleRate: testSampleRate)).waveform)80 #expect(mid.mid > 170 && mid.low < 0.1 * mid.mid && mid.high < 0.1 * mid.mid, "1 kHz: \(mid)")81 let high = means(try analyze(SignalSynth.sine(frequency: 6000, seconds: 3, sampleRate: testSampleRate)).waveform)82 #expect(high.high > 170 && high.low < 0.02 * high.high && high.mid < 0.1 * high.high, "6 kHz: \(high)")83 // amplitude 0.5: band value 255 * sqrt(0.5) = 180, linear peak 255 * 0.5 = 12884 #expect(abs(low.low - 180) < 4 && abs(low.peak - 127.5) < 2)85 }8687 @Test func columnCountAndOverview() throws {88 let x = SignalSynth.clickTrack(bpm: 120, seconds: 10, sampleRate: testSampleRate)89 let w = try analyze(x).waveform90 #expect(w.columnsPerSecond == 150)91 #expect(w.count == 1500)92 #expect(w.low.count == w.count && w.mid.count == w.count && w.high.count == w.count)93 let o = w.overview(columns: 100)94 #expect(o.count == 100 && o.low.count == 100)95 #expect(abs(o.columnsPerSecond - 10) < 1e-9)96 #expect(o.peak.max() == w.peak.max())97 #expect(o.peak[0] == w.peak[0..<15].max())98 #expect(w.overview(columns: 5000).count == w.count)99 #expect(w.overview(columns: 0).count == 0)100 // clicks every 0.5 s = every 75 columns: quiet between them101 #expect(w.peak[0] > 150 && w.peak[40] == 0 && w.peak[75] > 150)102 }103}104105@Suite struct RobustnessTests {106 @Test func silenceGivesNoGrid() throws {107 let r = try analyze([Float](repeating: 0, count: Int(20 * testSampleRate)))108 #expect(r.grid == nil)109 #expect(r.key == nil)110 #expect(r.integratedLUFS == AnalysisResult.silenceLUFS)111 #expect(r.suggestedGainDB == 0)112 #expect(r.transients.isEmpty)113 #expect(r.waveform.count == 3000 && r.waveform.peak.allSatisfy { $0 == 0 })114 _ = try JSONEncoder().encode(r) // no infinities115 }116117 @Test func veryShortInputsDoNotCrash() throws {118 for count in [0, 1, 2, 100, 441, 4410, 22050, 40000] {119 let noise = SignalSynth.whiteNoise(seconds: 1, sampleRate: testSampleRate)120 let x = Array(noise.prefix(count))121 let r = try analyze(x)122 #expect(r.grid == nil, "count \(count)")123 #expect(abs(r.duration - Double(count) / testSampleRate) < 1e-9)124 _ = try JSONEncoder().encode(r)125 }126 let t = SignalSynth.track(.init(seconds: 0.8), sampleRate: testSampleRate)127 #expect(try analyze(t.left, t.right).grid == nil)128 // mismatched channel lengths: the shorter one wins129 let r = try TrackAnalyzer.analyze(left: [0.1, 0.2, 0.3], right: [0.1], sampleRate: testSampleRate)130 #expect(r.waveform.count == 1)131 // absurd sample rate132 #expect(try TrackAnalyzer.analyze(left: [0.1, 0.2], right: [0.1, 0.2], sampleRate: 0).duration == 0)133 }134135 @Test func steadySineAndNoiseHaveNoConfidentTempo() throws {136 let sine = try analyze(SignalSynth.sine(frequency: 440, seconds: 20, sampleRate: testSampleRate))137 #expect(sine.grid == nil)138 for seed in [1, 2, 3] as [UInt64] {139 let noise = try analyze(SignalSynth.whiteNoise(seconds: 20, sampleRate: testSampleRate, seed: seed))140 #expect(noise.grid == nil || noise.bpmConfidence < 0.4, "white noise confidence \(noise.bpmConfidence)")141 let pink = try analyze(SignalSynth.pinkNoise(seconds: 20, sampleRate: testSampleRate, seed: seed))142 #expect(pink.grid == nil || pink.bpmConfidence < 0.4, "pink noise confidence \(pink.bpmConfidence)")143 }144 }145146 @Test func cancellationThrows() throws {147 let t = SignalSynth.track(.init(seconds: 20), sampleRate: testSampleRate)148 #expect(throws: CancellationError.self) {149 _ = try TrackAnalyzer.analyze(left: t.left, right: t.right, sampleRate: testSampleRate, isCancelled: { true })150 }151 // cancel in the middle of the work152 let counter = Counter()153 #expect(throws: CancellationError.self) {154 _ = try TrackAnalyzer.analyze(left: t.left, right: t.right, sampleRate: testSampleRate,155 progress: { counter.values.append($0) },156 isCancelled: { counter.polls += 1; return (counter.values.last ?? 0) >= 0.4 })157 }158 #expect(counter.polls > 3)159 #expect((counter.values.last ?? 0) < 1)160 }161162 @Test func progressIsMonotonicAndEndsAtOne() throws {163 let t = SignalSynth.track(.init(seconds: 12), sampleRate: testSampleRate)164 let counter = Counter()165 _ = try TrackAnalyzer.analyze(left: t.left, right: t.right, sampleRate: testSampleRate, progress: { counter.values.append($0) })166 #expect(counter.values.first == 0 && counter.values.last == 1)167 #expect(zip(counter.values, counter.values.dropFirst()).allSatisfy { $0 <= $1 })168 #expect(counter.values.count >= 5)169 }170}171172@Suite struct TempoBehaviourTests {173 @Test func driftingTempoHasLowStability() throws {174 // Clicks accelerating from 90 to 150 BPM over 40 s, and a steady reference.175 let seconds = 40.0176 let click = SignalSynth.clickSample(sampleRate: testSampleRate)177 var x = [Float](repeating: 0, count: Int(seconds * testSampleRate))178 var t = 0.05179 while t < seconds - 0.1 {180 let start = Int(t * testSampleRate)181 for (i, v) in click.enumerated() where start + i < x.count { x[start + i] += v }182 t += 60 / (90 + 60 * t / seconds)183 }184 let drifting = try analyze(x)185 let steady = try analyze(SignalSynth.clickTrack(bpm: 120, seconds: seconds, sampleRate: testSampleRate, offsetSeconds: 0.05))186 print("tempoStability: steady \(steady.tempoStability), accelerating 90->150 \(drifting.tempoStability) (grid \(String(describing: drifting.grid?.bpm)))")187 #expect(steady.tempoStability > 0.9)188 #expect(drifting.tempoStability < 0.4)189190 // Jittered human-like timing: each beat displaced by up to ±12 % of a beat, random walk tempo.191 var y = [Float](repeating: 0, count: x.count)192 var state: UInt64 = 42193 func random() -> Double { state = state &* 6364136223846793005 &+ 1442695040888963407; return Double(state >> 33) / Double(1 << 31) }194 t = 0.05195 var bpm = 110.0196 while t < seconds - 0.1 {197 let start = Int(t * testSampleRate)198 for (i, v) in click.enumerated() where start + i < y.count { y[start + i] += v }199 bpm = min(135, max(90, bpm + (random() - 0.5) * 14))200 t += 60 / bpm201 }202 let rubato = try analyze(y)203 print("tempoStability: random-walk 90...135 \(rubato.tempoStability)")204 #expect(rubato.tempoStability < 0.6)205 }206207 @Test func bpmRangeFoldsTheTempo() throws {208 let x = SignalSynth.clickTrack(bpm: 140, seconds: 30, sampleRate: testSampleRate)209 var options = AnalysisOptions()210 options.bpmRange = 60...100211 #expect(abs((try analyze(x, options: options).grid?.bpm ?? 0) - 70) < 0.05)212 options.bpmRange = 100...200213 #expect(abs((try analyze(x, options: options).grid?.bpm ?? 0) - 140) < 0.05)214 let slow = SignalSynth.clickTrack(bpm: 60, seconds: 30, sampleRate: testSampleRate)215 #expect(abs((try analyze(slow).grid?.bpm ?? 0) - 120) < 0.05) // default range 70...180216 }217218 @Test func otherSampleRatesSwingAndMono() throws {219 let spec = SignalSynth.TrackSpec(bpm: 126, tonic: 5, mode: .minor, seconds: 40, style: .house, seed: 7, offsetSeconds: 0.2, swing: 0.25)220 for rate in [48000.0, 22050.0] {221 let t = SignalSynth.track(spec, sampleRate: rate)222 let r = try analyze(t.left, t.right, sampleRate: rate)223 #expect(abs((r.grid?.bpm ?? 0) - 126) < 0.05, "bpm at \(rate): \(String(describing: r.grid?.bpm))")224 if let grid = r.grid {225 #expect(abs(circularDifference(grid.firstBeatSeconds, 0.2, period: 60 / grid.bpm)) < 0.006, "phase at \(rate)")226 }227 #expect(r.key?.tonic == 5 && r.key?.mode == .minor, "key at \(rate): \(r.key?.name ?? "nil")")228 let mono = zip(t.left, t.right).map { ($0 + $1) / 2 }229 let m = try analyze(mono, sampleRate: rate)230 #expect(abs((m.grid?.bpm ?? 0) - 126) < 0.05)231 }232 }233234 @Test func transientsMatchTheClicks() throws {235 let x = SignalSynth.clickTrack(bpm: 120, seconds: 10, sampleRate: testSampleRate, offsetSeconds: 0.1)236 let r = try analyze(x)237 #expect(r.transients.count == 20, "\(r.transients.count) transients")238 #expect(r.transients == r.transients.sorted())239 for (k, t) in r.transients.enumerated() where r.transients.count == 20 {240 #expect(abs(Double(t) - (0.1 + 0.5 * Double(k))) < 0.003, "transient \(k) at \(t)")241 }242 let dense = try analyze(SignalSynth.whiteNoise(seconds: 5, sampleRate: testSampleRate))243 #expect(dense.transients.count <= TrackAnalyzer.maximumTransients)244 }245}246247@Suite struct ModelTests {248 @Test func keyNamesAndCamelot() {249 let am = KeyEstimate(tonic: 9, mode: .minor, confidence: 1)250 #expect(am.name == "A minor" && am.shortName == "Am" && am.camelot == "8A")251 let c = KeyEstimate(tonic: 0, mode: .major, confidence: 1)252 #expect(c.name == "C major" && c.shortName == "C" && c.camelot == "8B")253 let fs = KeyEstimate(tonic: 6, mode: .major, confidence: 1)254 #expect(fs.name == "F♯ major" && fs.shortName == "F♯" && fs.camelot == "2B")255 let expectedMajor = ["8B", "3B", "10B", "5B", "12B", "7B", "2B", "9B", "4B", "11B", "6B", "1B"]256 let expectedMinor = ["5A", "12A", "7A", "2A", "9A", "4A", "11A", "6A", "1A", "8A", "3A", "10A"]257 for t in 0..<12 {258 #expect(KeyEstimate(tonic: t, mode: .major, confidence: 1).camelot == expectedMajor[t])259 #expect(KeyEstimate(tonic: t, mode: .minor, confidence: 1).camelot == expectedMinor[t])260 }261 }262263 @Test func keyCompatibilityAndTransposition() {264 let am = KeyEstimate(tonic: 9, mode: .minor, confidence: 0.5)265 #expect(am.isCompatible(with: am))266 #expect(am.isCompatible(with: KeyEstimate(tonic: 0, mode: .major, confidence: 1))) // relative, 8B267 #expect(am.isCompatible(with: KeyEstimate(tonic: 4, mode: .minor, confidence: 1))) // Em, 9A268 #expect(am.isCompatible(with: KeyEstimate(tonic: 2, mode: .minor, confidence: 1))) // Dm, 7A269 #expect(!am.isCompatible(with: KeyEstimate(tonic: 11, mode: .minor, confidence: 1))) // Bm, 10A270 #expect(!am.isCompatible(with: KeyEstimate(tonic: 7, mode: .major, confidence: 1))) // G, 9B271 #expect(!am.isCompatible(with: KeyEstimate(tonic: 9, mode: .major, confidence: 1))) // A, 11B272 // wrap-around 12 <-> 1273 #expect(KeyEstimate(tonic: 4, mode: .major, confidence: 1).isCompatible(with: KeyEstimate(tonic: 11, mode: .major, confidence: 1)))274 #expect(am.transposed(semitones: 3) == KeyEstimate(tonic: 0, mode: .minor, confidence: 0.5))275 #expect(am.transposed(semitones: -10).tonic == 11)276 #expect(am.transposed(semitones: 12) == am)277 }278279 @Test func beatGridConversions() {280 let grid = BeatGrid(bpm: 120, firstBeatSeconds: 0.25, downbeatIndex: 2)281 #expect(grid.beat(at: 0.25) == 0)282 #expect(abs(grid.beat(at: 1.5) - 2.5) < 1e-12)283 #expect(abs(grid.seconds(atBeat: 8) - 4.25) < 1e-12)284 #expect(abs(grid.nearestBeatSeconds(to: 1.4) - 1.25) < 1e-12)285 #expect(abs(grid.nearestBeatSeconds(to: 0.05) - 0.25) < 1e-12)286 #expect(abs(grid.nearestBeatSeconds(to: -0.1) - (-0.25)) < 1e-12)287 #expect(abs(grid.barStartSeconds(atOrBefore: 4.0) - 3.25) < 1e-12)288 for s in stride(from: -3.0, through: 30, by: 0.37) { #expect(abs(grid.seconds(atBeat: grid.beat(at: s)) - s) < 1e-9) }289 }290291 @Test func resultRoundTripsThroughJSON() throws {292 let t = SignalSynth.track(.init(bpm: 128, tonic: 2, mode: .major, seconds: 20, style: .techno), sampleRate: testSampleRate)293 let r = try analyze(t.left, t.right)294 let decoded = try JSONDecoder().decode(AnalysisResult.self, from: JSONEncoder().encode(r))295 #expect(decoded.version == AnalysisResult.currentVersion)296 #expect(decoded.grid == r.grid && decoded.key == r.key)297 #expect(decoded.transients == r.transients && decoded.waveform.low == r.waveform.low && decoded.waveform.peak == r.waveform.peak)298 #expect(decoded.integratedLUFS == r.integratedLUFS && decoded.suggestedGainDB == r.suggestedGainDB)299 #expect(r.grid != nil && r.grid!.firstBeatSeconds >= 0 && r.grid!.firstBeatSeconds < 60 / r.grid!.bpm)300 #expect((0...3).contains(r.grid!.downbeatIndex))301 for v in [r.bpmConfidence, r.tempoStability, r.downbeatConfidence, r.key?.confidence ?? 0] { #expect(v >= 0 && v <= 1) }302 #expect(r.peakDBFS + r.suggestedGainDB <= -1 + 1e-9)303 }304}305306@Suite struct SynthTests {307 @Test func deterministicAndBounded() {308 let spec = SignalSynth.TrackSpec(bpm: 124, seconds: 16, style: .house, seed: 5)309 let a = SignalSynth.track(spec, sampleRate: testSampleRate)310 let b = SignalSynth.track(spec, sampleRate: testSampleRate)311 #expect(a.left == b.left && a.right == b.right)312 #expect(a.left.count == Int(16 * testSampleRate) && a.right.count == a.left.count)313 #expect(a.left != a.right) // real stereo314 var other = spec315 other.seed = 6316 #expect(SignalSynth.track(other, sampleRate: testSampleRate).left != a.left)317 for style in SignalSynth.TrackSpec.Style.allCases {318 var s = spec319 s.style = style320 let t = SignalSynth.track(s, sampleRate: testSampleRate)321 let peak = max(t.left.map { abs($0) }.max()!, t.right.map { abs($0) }.max()!)322 #expect(abs(peak - 0.891) < 1e-3, "\(style) peak \(peak)")323 #expect(t.left.allSatisfy { $0.isFinite })324 }325 #expect(SignalSynth.track(.init(seconds: 0), sampleRate: testSampleRate).left.isEmpty)326 }327328 @Test func elementarySignals() {329 let sine = SignalSynth.sine(frequency: 100, seconds: 1, sampleRate: 8000, amplitude: 0.25)330 #expect(sine.count == 8000 && abs(sine.map { abs($0) }.max()! - 0.25) < 1e-4)331 let white = SignalSynth.whiteNoise(seconds: 1, sampleRate: 8000, amplitude: 0.5, seed: 9)332 #expect(white == SignalSynth.whiteNoise(seconds: 1, sampleRate: 8000, amplitude: 0.5, seed: 9))333 #expect(white != SignalSynth.whiteNoise(seconds: 1, sampleRate: 8000, amplitude: 0.5, seed: 10))334 #expect(white.allSatisfy { abs($0) <= 0.5 } && abs(white.reduce(0, +) / 8000) < 0.02)335 let pink = SignalSynth.pinkNoise(seconds: 2, sampleRate: 8000, amplitude: 0.5, seed: 3)336 #expect(abs(pink.map { abs($0) }.max()! - 0.5) < 1e-4)337 let sweep = SignalSynth.sweep(from: 50, to: 2000, seconds: 2, sampleRate: 8000)338 // zero crossings are much denser at the end than at the start339 func crossings(_ r: Range<Int>) -> Int { r.dropLast().filter { (sweep[$0] < 0) != (sweep[$0 + 1] < 0) }.count }340 #expect(crossings(14000..<16000) > 8 * crossings(0..<2000))341 let clicks = SignalSynth.clickTrack(bpm: 60, seconds: 3, sampleRate: 8000, offsetSeconds: 0.5)342 #expect(clicks[3999] == 0 && abs(clicks[4000]) > 0.5 && abs(clicks[12000]) > 0.5 && clicks[11999] == 0)343 }344}345346@Suite struct TimingTests {347 @Test func fiveMinuteTrackTiming() throws {348 let rate = 44100.0349 let t = SignalSynth.track(.init(bpm: 126, tonic: 7, mode: .minor, seconds: 300, style: .house, seed: 11, offsetSeconds: 0.08), sampleRate: rate)350 var best = Double.infinity351 var result: AnalysisResult?352 for _ in 0..<3 {353 let start = DispatchTime.now().uptimeNanoseconds354 result = try analyze(t.left, t.right, sampleRate: rate)355 best = min(best, Double(DispatchTime.now().uptimeNanoseconds - start) / 1e9)356 }357 let r = try #require(result)358 #if DEBUG359 let configuration = "debug"360 #else361 let configuration = "release"362 #endif363 print("=== ORIX-ANALYSIS-TIMING ===")364 print("5 min 44.1 kHz stereo, single thread, \(configuration) build: \(String(format: "%.3f", best)) s (best of 3)")365 print("bpm \(String(format: "%.4f", r.grid?.bpm ?? 0)) (truth 126), first beat \(String(format: "%.4f", r.grid?.firstBeatSeconds ?? -1)) s (truth 0.0800), "366 + "downbeat \(r.grid?.downbeatIndex ?? -1), key \(r.key?.name ?? "nil") (truth G minor), LUFS \(String(format: "%.2f", r.integratedLUFS)), "367 + "stability \(String(format: "%.2f", r.tempoStability)), transients \(r.transients.count)")368 print("=== END ===")369 #expect(abs((r.grid?.bpm ?? 0) - 126) < 0.01)370 #if !DEBUG371 #expect(best < 3.0)372 #endif373 }374}375