Repository Public License
1//2// ORIX Audio3// File: Core/Sources/ORIXAudioCore/Analysis/Diagnostics.swift4// Description: Plain-language findings derived from measured metrics. Indicators only — never forensic or medical claims.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8//9import Foundation1011public struct DiagnosticFinding: Codable, Sendable, Hashable, Identifiable {12 public enum Severity: String, Codable, Sendable { case info, notice, warning }13 public enum Kind: String, Codable, Sendable {14 case clipping, lowLevel, elevatedNoise, longSilence, possibleDistortion, narrowSpectrum, dcOffset, limitedBandwidth, healthy15 }16 public var kind: Kind17 public var severity: Severity18 /// The measured values that triggered the finding, for display: e.g. ["events": 4, "samples": 212].19 public var values: [String: Double]20 public var id: String { kind.rawValue }21}2223public enum AudioDiagnostics {24 public static func findings(time t: TimeDomainMetrics, spectral s: SpectralMetrics, loudness l: LoudnessMetrics, speech: SpeechActivityMetrics = .init(), sampleRate: Double) -> [DiagnosticFinding] {25 var out: [DiagnosticFinding] = []26 guard t.sampleCount > 0 else { return out }27 if t.clippingEvents > 0 {28 out.append(.init(kind: .clipping, severity: t.clippedSamples > Int(sampleRate * 0.01) ? .warning : .notice,29 values: ["events": Double(t.clippingEvents), "samples": Double(t.clippedSamples)]))30 }31 if t.peakDBFS < -20 && t.peak > 0 {32 out.append(.init(kind: .lowLevel, severity: t.peakDBFS < -30 ? .warning : .notice, values: ["peakDBFS": Double(t.peakDBFS), "rmsDBFS": Double(t.rmsDBFS)]))33 }34 // Only meaningful when the programme has gaps: with continuous material (music, a steady tone) the quietest35 // moments are still signal, not background.36 if t.noiseFloorDBFS > -45 && t.dynamicSpreadDB < 15 && t.duration > 3 && speech.pauses.count >= 3 {37 out.append(.init(kind: .elevatedNoise, severity: .notice, values: ["floorDBFS": Double(t.noiseFloorDBFS), "spreadDB": Double(t.dynamicSpreadDB)]))38 }39 if let longest = t.silences.map(\.duration).max(), longest >= 10 {40 out.append(.init(kind: .longSilence, severity: .info, values: ["seconds": longest, "total": t.silentDuration]))41 }42 // Clipping with a very low crest factor suggests sustained overload rather than isolated peaks.43 if t.clippingEvents > 0 && t.crestFactorDB < 6 {44 out.append(.init(kind: .possibleDistortion, severity: .warning, values: ["crestDB": Double(t.crestFactorDB)]))45 }46 if let top = s.bands.max(by: { $0.fraction < $1.fraction }), top.fraction > 0.9, s.flatness < 0.02 {47 out.append(.init(kind: .narrowSpectrum, severity: .info, values: ["fraction": Double(top.fraction), "lowerHz": top.lowerHz, "upperHz": top.upperHz]))48 }49 if abs(t.dcOffset) > 0.01 {50 out.append(.init(kind: .dcOffset, severity: .notice, values: ["offset": Double(t.dcOffset)]))51 }52 // Band-limited source inside a wide-band file: less than −40 dB of the energy lies above 4 kHz.53 let high = s.bands.filter { $0.lowerHz >= 4000 }.reduce(Float(0)) { $0 + $1.fraction }54 if sampleRate >= 32000, !s.bands.isEmpty, high < 1e-4, s.bandwidthHz > 200, t.rms > 0.001 {55 out.append(.init(kind: .limitedBandwidth, severity: .info, values: ["rolloffHz": s.rolloffHz, "highShare": Double(high)]))56 }57 if out.isEmpty { out.append(.init(kind: .healthy, severity: .info, values: [:])) }58 return out59 }60}6162/// The full analysis of one recording. Every number carries its unit in the property name.63public struct AnalysisReport: Codable, Sendable, Equatable {64 public var version = 165 public var sampleRate: Double66 public var channels: Int67 public var time: TimeDomainMetrics68 public var spectral: SpectralMetrics69 public var loudness: LoudnessMetrics70 public var speech: SpeechActivityMetrics71 public var findings: [DiagnosticFinding]72}73