File size: 13,132 Bytes
ab5ae4a | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 | """q_raw (8 physical dimensions), q_dmg (4 normalized damage dimensions), d.
SSOT §3.1.3. Two of the four damage detectors have no formula anywhere in the
SSOT (``T60_est`` and ``codec_artifact_score``); they are implemented here as
explicit PLACEHOLDER estimators and repeated verbatim in the milestone report.
``vowel_coverage`` likewise has only a ratio in the SSOT — the detector below
follows the De Jong & Wempe (2009) syllable-nucleus idea the older scheme
document cites, with every free parameter marked PLACEHOLDER.
``snr_est_db`` per SSOT is ``min(20 log10(signal_rms / E_noise), WADA_SNR(A))``.
The paper's lookup table is not in the repository, so WADA-SNR here is the
paper's statistic G = log E|x| - E log|x| inverted through a table rebuilt by
simulation from the paper's model (Gamma(0.4) speech amplitudes, Gaussian
noise, fixed seed). That is a deviation from "use the published table".
"""
from __future__ import annotations
from dataclasses import dataclass
import numpy as np
try:
from . import constants as C
except ImportError:
import constants as C
# --------------------------------------------------------------------------
# WADA-SNR (Kim & Stern, Interspeech 2008)
# --------------------------------------------------------------------------
_WADA_TABLE: tuple[np.ndarray, np.ndarray] | None = None
def _wada_statistic(signal: np.ndarray) -> float:
"""Kim & Stern G = log(E|x|) - E(log|x|) over the whole waveform."""
magnitude = np.maximum(np.abs(np.asarray(signal, dtype=np.float64)),
C.WADA_AMPLITUDE_FLOOR)
if magnitude.size < 2:
return float("nan")
return float(np.log(magnitude.mean()) - np.log(magnitude).mean())
def wada_lookup_table():
"""Rebuild the paper's G -> SNR table by simulation (deterministic seed).
DEVIATION from "use the published table": the Kim & Stern (2008) table is
not in the repository. It is regenerated with the paper's own model: clean
speech amplitudes ~ Gamma(shape 0.4) with random sign, unit power; additive
unit Gaussian noise scaled to each grid SNR. G rises monotonically with
SNR; ``np.maximum.accumulate`` removes Monte-Carlo wiggle at the noisy end.
"""
global _WADA_TABLE
if _WADA_TABLE is not None:
return _WADA_TABLE
rng = np.random.default_rng(C.WADA_SIM_SEED)
n = C.WADA_SIM_SAMPLES
speech = rng.gamma(C.WADA_GAMMA_SHAPE, 1.0, n) * rng.choice([-1.0, 1.0], n)
speech /= np.sqrt(np.mean(speech ** 2))
noise = rng.standard_normal(n)
grid = np.arange(C.WADA_GRID_DB[0], C.WADA_GRID_DB[1] + 0.5, 1.0)
stats = np.array([_wada_statistic(speech + noise * 10.0 ** (-snr / 20.0))
for snr in grid])
stats = np.maximum.accumulate(stats)
_WADA_TABLE = (stats, grid)
return _WADA_TABLE
def wada_snr_db(signal: np.ndarray, sample_rate: int = C.TARGET_SR) -> float:
"""Invert the G -> SNR table; values outside clamp to the grid ends."""
value = _wada_statistic(signal)
if not np.isfinite(value):
return float("nan")
stats, grid = wada_lookup_table()
estimate = float(np.interp(value, stats, grid))
return float(np.clip(estimate, C.SNR_REPORT_MIN_DB, C.SNR_REPORT_MAX_DB))
# --------------------------------------------------------------------------
# Damage detectors written as explicit placeholders
# --------------------------------------------------------------------------
def t60_estimate(x_trim: np.ndarray, sample_rate: int = C.TARGET_SR) -> float:
"""PLACEHOLDER T60 from a Schroeder backward integral on the quietest tail.
The SSOT never defines how T60_est is measured. This estimator takes the
last ``T60_WINDOW_S`` of the recording, integrates energy backwards, fits
a line to the -5..-25 dB part of the decay, and returns ``3 * 60 / slope``.
Poor fits (R^2 < T60_MIN_R2) return 0.0 so q_reverb stays silent rather
than inventing reverb. Replace with a calibrated detector before release.
"""
window = int(round(C.T60_WINDOW_S * sample_rate))
if len(x_trim) < window or window <= 0:
return 0.0
tail = np.asarray(x_trim[-window:], dtype=np.float64)
energy = np.cumsum((tail ** 2)[::-1])[::-1]
if energy[0] <= C.RMS_EPSILON:
return 0.0
edc_db = 10.0 * np.log10(np.maximum(energy / energy[0], 1e-20))
times = np.arange(len(edc_db)) / sample_rate
mask = (edc_db <= -5.0) & (edc_db >= -25.0)
if mask.sum() < 10:
return 0.0
slope, intercept = np.polyfit(times[mask], edc_db[mask], 1)
fitted = slope * times[mask] + intercept
residual = edc_db[mask] - fitted
ss_tot = float(np.sum((edc_db[mask] - edc_db[mask].mean()) ** 2))
r2 = 1.0 - float(np.sum(residual ** 2)) / ss_tot if ss_tot > 0 else 0.0
if slope >= 0 or r2 < C.T60_MIN_R2:
return 0.0
return float(np.clip(-60.0 / slope, 0.0, 2.0))
def codec_artifact_score(spectrum: np.ndarray, freqs: np.ndarray) -> float:
"""PLACEHOLDER codec score: high-band energy relative to the speech band.
Low-bitrate codecs and aggressive noise suppression cut the 6.5-7.8 kHz
shelf while leaving 300-3400 Hz mostly intact. The SSOT gives no formula,
so this is a placeholder ratio mapped by ``CODEC_RATIO_REF``; 0 = clean.
"""
total = float(spectrum.sum())
if total <= C.RMS_EPSILON:
return 0.0
high = float(spectrum[(freqs >= C.CODEC_HIGH_BAND_HZ[0]) &
(freqs <= C.CODEC_HIGH_BAND_HZ[1])].sum())
mid = float(spectrum[(freqs >= C.CODEC_MID_BAND_HZ[0]) &
(freqs <= C.CODEC_MID_BAND_HZ[1])].sum())
if mid <= C.RMS_EPSILON:
return 1.0
ratio = high / mid
return float(np.clip(1.0 - ratio / C.CODEC_RATIO_REF, 0.0, 1.0))
# --------------------------------------------------------------------------
# Clipping (original PCM, absolute full-scale, plus flat-top detection)
# --------------------------------------------------------------------------
def clipping_ratio(x_pcm: np.ndarray) -> float:
"""SSOT clipping definition on the original, un-resampled-scale PCM.
``|x| >= 0.99`` (hard limit) OR ``|x| >= 0.50`` with two consecutive
near-zero sample differences (flat rail). Never relative to max|x|.
"""
x = np.asarray(x_pcm, dtype=np.float64)
if x.size == 0:
return 0.0
hard = np.abs(x) >= C.CLIP_HARD_LIMIT
if x.size <= C.CLIP_FLAT_LOOKBACK:
return float(hard.mean())
diffs = [np.abs(x[C.CLIP_FLAT_LOOKBACK:] - x[C.CLIP_FLAT_LOOKBACK - k:x.size - k])
for k in range(1, C.CLIP_FLAT_LOOKBACK + 1)]
flat = np.maximum.reduce(diffs) < C.CLIP_FLAT_DELTA
loud = np.abs(x[C.CLIP_FLAT_LOOKBACK:]) >= C.CLIP_FLAT_LIMIT
flat_top = np.concatenate((np.zeros(C.CLIP_FLAT_LOOKBACK, dtype=bool), flat & loud))
return float(np.mean(hard | flat_top))
# --------------------------------------------------------------------------
# Vowel-like coverage
# --------------------------------------------------------------------------
def _intensity_envelope(signal: np.ndarray, sample_rate: int) -> np.ndarray:
frame = int(round(0.010 * sample_rate))
hop = frame // 2
n_frames = max(1, 1 + (len(signal) - frame) // hop) if len(signal) >= frame else 1
env = np.empty(n_frames)
for index in range(n_frames):
a = index * hop
env[index] = np.sqrt(np.mean(signal[a:a + frame] ** 2))
return env
def vowel_like_mask(segment_a: np.ndarray, voiced_mask: np.ndarray,
sample_rate: int = C.TARGET_SR) -> np.ndarray:
"""PLACEHOLDER vowel-like regions on A (De Jong & Wempe syllable nuclei).
Peaks in the 10 ms intensity envelope with >= 2 dB prominence and >= 150 ms
spacing are expanded to 250 ms regions clipped to A, required to overlap a
periodic frame, and merged. Every constant is a placeholder; the SSOT only
fixes the ratio ``vowel_coverage = vowel-like duration / T_voiced``.
"""
n = len(segment_a)
out = np.zeros(n, dtype=bool)
if n == 0:
return out
env = _intensity_envelope(segment_a, sample_rate)
if len(env) < 3:
return out
env_db = 20.0 * np.log10(np.maximum(env, C.RMS_EPSILON))
frame = int(round(0.010 * sample_rate))
hop = frame // 2
min_gap = int(round(C.VOWEL_PEAK_MIN_GAP_S / (hop / sample_rate)))
half = int(round(C.VOWEL_REGION_S / 2.0 * sample_rate))
last_peak = -min_gap
for index in range(1, len(env_db) - 1):
if not (env_db[index] > env_db[index - 1] and env_db[index] >= env_db[index + 1]):
continue
neighbourhood = env_db[max(0, index - 15):index + 16]
if env_db[index] - np.median(neighbourhood) < C.VOWEL_PEAK_PROMINENCE_DB:
continue
if index - last_peak < min_gap:
continue
center = index * hop
a = max(0, center - half)
b = min(n, center + half)
if b <= a:
continue
region = np.zeros(n, dtype=bool)
region[a:b] = True
if (region & voiced_mask).sum() < (b - a) // 2:
continue
out |= region
last_peak = index
return out
# --------------------------------------------------------------------------
# Quality vector assembly
# --------------------------------------------------------------------------
@dataclass(frozen=True)
class QualityVectors:
q_raw: np.ndarray # 8 physical dimensions, SSOT order
q_dmg: np.ndarray # [q_clip, q_reverb, q_snr, q_codec]
d: float
snr_est_db: float
diagnostics: dict
def quality_vectors(x_pcm: np.ndarray, x_trim: np.ndarray, segment_a: np.ndarray,
voiced_mask: np.ndarray, voiced_ratio: float,
e_noise: float, n_missing: int,
signal_rms: float | None = None,
sample_rate: int = C.TARGET_SR) -> QualityVectors:
"""Assemble q_raw / q_dmg / d exactly in SSOT §3.1.3 order.
``voiced_mask`` is the per-sample periodic mask on the same time base as
``x_trim``; ``signal_rms`` is the median RMS over periodic frames and is
passed in by the caller that already computed frame RMS.
"""
if signal_rms is None or not np.isfinite(signal_rms):
signal_rms = float(np.sqrt(np.mean(segment_a ** 2))) if segment_a.size else 0.0
from scipy.signal import welch
if segment_a.size >= C.SPECTRAL_WELCH_SEGMENT:
freqs, spectrum = welch(segment_a, fs=sample_rate,
nperseg=C.SPECTRAL_WELCH_SEGMENT)
elif segment_a.size:
freqs, spectrum = welch(segment_a, fs=sample_rate,
nperseg=max(2, segment_a.size))
else:
freqs, spectrum = np.zeros(1), np.zeros(1)
total_energy = float(spectrum.sum())
if total_energy > C.RMS_EPSILON:
flatness = float(np.exp(np.mean(np.log(np.maximum(spectrum, 1e-20)))) /
np.mean(spectrum))
lf_ratio = float(spectrum[freqs < C.LF_RUMBLE_HZ].sum() / total_energy)
tilt = 10.0 * np.log10(
max(float(spectrum[(freqs >= C.TILT_HIGH_HZ[0]) &
(freqs <= C.TILT_HIGH_HZ[1])].sum()), 1e-20) /
max(float(spectrum[(freqs >= C.TILT_LOW_HZ[0]) &
(freqs <= C.TILT_LOW_HZ[1])].sum()), 1e-20))
else:
flatness, lf_ratio, tilt = float("nan"), float("nan"), float("nan")
# snr_est_db = min(energy ratio, WADA-SNR) — the stricter of the two.
if e_noise > C.RMS_EPSILON and signal_rms > 0:
energy_snr = 20.0 * np.log10(signal_rms / e_noise)
else:
energy_snr = float("nan")
wada = wada_snr_db(segment_a, sample_rate) if segment_a.size else float("nan")
candidates = [v for v in (energy_snr, wada) if np.isfinite(v)]
snr_est = min(candidates) if candidates else float("nan")
clip_ratio = clipping_ratio(x_pcm)
recording_level = (20.0 * np.log10(np.sqrt(np.mean(x_trim ** 2)))
if x_trim.size else float("-inf"))
q_raw = np.array([
snr_est,
flatness,
lf_ratio,
clip_ratio,
recording_level,
tilt,
voiced_ratio,
float(n_missing),
], dtype=np.float64)
q_clip = float(np.clip(clip_ratio / C.Q_CLIP_SCALE, 0.0, 1.0))
t60 = t60_estimate(x_trim, sample_rate)
q_reverb = float(np.clip((t60 - C.Q_REVERB_T60_ONSET_S) / C.Q_REVERB_T60_SCALE_S,
0.0, 1.0))
q_snr = (float(np.clip((C.Q_SNR_CLEAN_DB - snr_est) / C.Q_SNR_SCALE_DB, 0.0, 1.0))
if np.isfinite(snr_est) else 1.0)
q_codec = codec_artifact_score(spectrum, freqs)
q_dmg = np.array([q_clip, q_reverb, q_snr, q_codec], dtype=np.float64)
d = float(1.0 - np.prod(1.0 - q_dmg))
return QualityVectors(
q_raw=q_raw,
q_dmg=q_dmg,
d=d,
snr_est_db=float(snr_est) if np.isfinite(snr_est) else float("nan"),
diagnostics={"energy_snr_db": energy_snr, "wada_snr_db": wada,
"t60_est_s": t60, "clipping_ratio": clip_ratio},
)
|