aria_linear_head
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},
    )