AMD telephony model: v5b_full + benchmarked v4a, code, model card

README.md

@@ -0,0 +1,81 @@
+---
+license: cc-by-nc-4.0
+language:
+- en
+pipeline_tag: audio-classification
+tags:
+- audio
+- telephony
+- answering-machine-detection
+- voicemail-detection
+- yamnet
+- gru
+- 8khz
+- vicidial
+- asterisk
+---
+
+# AMD — Answering Machine Detection for telephony (YAMNet + GRU)
+
+Real-time answering-machine detection for 8 kHz US-English telephony
+(VICIdial / Asterisk outbound campaigns). A pure-PyTorch YAMNet backbone
+(fine-tuned, top-2 blocks) feeds a bidirectional GRU head; output is
+`p_machine ∈ [0,1]`. **~16 ms inference per 4 s of audio on a single CPU
+thread** — fast enough to decide inside the first ring seconds.
+
+Two checkpoints:
+
+| checkpoint | training pool | how it was measured |
+|---|---|---|
+| **`v5b_full` (root)** | 50,876 clips — the full max-data pool (incl. real carrier voicemail, IVR, network intercepts, robocalls, call-center + conversational telephone speech) | validation (4,949 held-out clips) |
+| `benchmarked_v4a/` | 31,947 clips (frozen-eval-disjoint) | two frozen external test sets |
+
+## Results
+
+`v5b_full` (validation, threshold 0.5): **97.7% accuracy**, machine recall
+**97.0%** under a ≤3% false-machine-on-humans cap, fmh 1.56%. On held-out
+clips of the hardest class — real carrier voicemail greetings — error is
+**13%**, versus 91% for a naive-composition baseline.
+
+`benchmarked_v4a` (frozen external sets, never trained on, one pass): 79.8%
+accuracy / balanced-acc .845 / AUC .935 on a 796-clip external set;
+92.5% / .928 / .979 on a 1,429-clip balanced set; machine recall at the
+FTC-style ≤3% abandonment cap: 0.56–0.91.
+
+## Usage
+
+```bash
+pip install torch numpy soundfile scipy
+python code/predict_example.py your_call.wav
+```
+
+```python
+import sys; sys.path.insert(0, "code")
+from predict_example import load, predict
+yamnet, head = load()
+p_machine = predict(yamnet, head, "call.wav")   # 0..1
+```
+
+Audio: any wav (resampled to 16 kHz mono internally; trained domain is 8 kHz
+G.711 telephony, first ≤10 s of the call).
+
+## Intended use & limitations
+
+- **Research / evaluation only (CC BY-NC 4.0).** Trained on a mixed-license
+  research pool; not cleared for commercial deployment.
+- US-English telephony. Non-English and non-telephone audio are out of domain.
+- Decision thresholds must be **calibrated on your own audio** — false-machine
+  rates measured on any fixed test set do not transfer exactly to live traffic.
+- `v5b_full` has no fully-external benchmark (its pool absorbed the project's
+  test sources — by design, for maximum coverage); `benchmarked_v4a` is the
+  checkpoint with honest external numbers. Known weak spots: robocall recall
+  (v5 val slice: 26% miss), heavily accented/studio-recorded humans.
+
+## Architecture
+
+- Backbone: YAMNet (AudioSet), pure-PyTorch port, custom `torch.stft` mel
+  frontend — no TensorFlow; top-2 blocks fine-tuned (BN frozen), bf16.
+- Head: bidirectional GRU over 1024-d patch embeddings (0.96 s window /
+  0.48 s hop), ~350k params, label smoothing 0.1.
+- Files: `*.yamnet.pth` (backbone, 15 MB) + `*.head.pt` (head + config, 1 MB)
+  + `*.json` (export manifest with round-trip verification).

benchmarked_v4a/v4a_ftw_mfnone_pw05.head.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fced3ef1ec2b9ad9c0717589341049751534040499aa2a9bcecc365b0107fd85
+size 1051377

benchmarked_v4a/v4a_ftw_mfnone_pw05.json

@@ -0,0 +1,16 @@
+{
+  "backbone_weights": "/root/amd/tracks/yamnet/experiments/backbone/v4a_ftw_mfnone_pw05.yamnet.pth",
+  "head_weights": "/root/amd/tracks/yamnet/experiments/backbone/v4a_ftw_mfnone_pw05.head.pt",
+  "head_config": {
+    "proj_dim": 128,
+    "hidden": 96,
+    "num_layers": 1,
+    "bidirectional": true,
+    "pooling": "last",
+    "dropout": 0.0
+  },
+  "gate_dbfs": -300.0,
+  "decision_threshold": 0.5,
+  "unfreeze_blocks": 2,
+  "note": "load backbone via extract_embeddings.load_model(backbone_weights); build head via sweep_head.build_config_head(head_config)."
+}

benchmarked_v4a/v4a_ftw_mfnone_pw05.yamnet.pth

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3bdadf83b44b5318354aae774ae2d5ddec78aec21fe49205fb5135249b8814c8
+size 15103509

code/extract_embeddings.py

@@ -0,0 +1,449 @@
+#!/usr/bin/env python3
+"""YAMNet 1024-d embedding extractor for the AMD Track-3 (YAMNet + GRU) recipe.
+
+Provenance / port choice
+-------------------------
+Network + pretrained weights: w-hc/torch_audioset (pure-PyTorch YAMNet port,
+numerically validated against Google's TF YAMNet to atol=1e-6 on the CNN given
+identical mel patches).
+  - architecture ported verbatim from
+    https://github.com/w-hc/torch_audioset/blob/master/torch_audioset/yamnet/model.py
+  - weights: https://github.com/w-hc/torch_audioset/releases/download/v0.1/yamnet.pth
+    sha256 620b5feb079a97f7c884427f66cf9b281dca0725f46828eb019d01cacb7ae968
+    (3.76M params; local copy at tracks/yamnet/weights/yamnet.pth)
+
+Why we DON'T use the upstream frontend / torch-vggish-yamnet pip:
+  both pull in `torchaudio` for the log-mel, and there is no torchaudio build
+  matching this box's torch 2.13.0+cpu (ABI risk). So the log-mel frontend here
+  is reimplemented with CORE torch (`torch.stft` + a hand-built HTK mel
+  filterbank) reproducing w-hc's exact YAMNetParams. Zero pip installs.
+  Exact bit-parity with TF is not required: the GRU head is trained on and
+  evaluated with THESE embeddings, so only self-consistency matters — but the
+  frontend still matches YAMNet's documented params closely so the pretrained
+  conv weights stay meaningful.
+
+Output
+------
+Per clip, one .npz with:
+  embeddings : float32 [n_frames, 1024]  (0.96s window, 0.48s hop → ~1 vec/0.48s)
+  energy     : float32 [n_frames]        (dBFS of the raw 16k waveform slice
+                                          aligned to each patch; for the silence
+                                          gate, tuned LATER without re-extraction)
+  sr, n_frames scalars for provenance.
+
+Usage
+-----
+  python extract_embeddings.py --wav clip.wav --out-dir emb/
+  python extract_embeddings.py --manifest data/manifest.csv --out-dir emb/ --threads 8
+  python extract_embeddings.py --selftest        # synthetic verify + benchmark
+"""
+import argparse
+import csv
+import hashlib
+import math
+import os
+import sys
+import time
+
+import numpy as np
+import soundfile as sf
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from scipy.signal import resample_poly
+
+# ----------------------------------------------------------------------------
+# YAMNet params (from w-hc CommonParams/YAMNetParams == TF yamnet/params.py)
+# ----------------------------------------------------------------------------
+SR = 16000
+STFT_WIN_S = 0.025           # 400 samples
+STFT_HOP_S = 0.010           # 160 samples
+N_FFT = 512
+N_MELS = 64
+MEL_MIN_HZ = 125.0
+MEL_MAX_HZ = 7500.0
+LOG_OFFSET = 0.001
+PATCH_WINDOW_S = 0.96        # 96 mel frames
+PATCH_HOP_S = 0.48           # 48 mel frames -> one embedding every 0.48s
+EMB_DIM = 1024
+
+WIN_SAMPLES = int(round(SR * STFT_WIN_S))     # 400
+HOP_SAMPLES = int(round(SR * STFT_HOP_S))     # 160
+PATCH_FRAMES = int(round(PATCH_WINDOW_S / STFT_HOP_S))   # 96
+PATCH_HOP_FRAMES = int(round(PATCH_HOP_S / STFT_HOP_S))  # 48
+
+_WEIGHTS = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                        "weights", "yamnet.pth")
+
+
+# ----------------------------------------------------------------------------
+# Network (ported verbatim from w-hc/torch_audioset yamnet/model.py)
+# ----------------------------------------------------------------------------
+class Conv2d_tf(nn.Conv2d):
+    """Conv2d with TF-Slim 'SAME' padding."""
+    def __init__(self, *args, **kwargs):
+        padding = kwargs.pop("padding", "SAME")
+        super().__init__(*args, **kwargs)
+        self.padding = padding
+        assert self.padding == "SAME"
+
+    def _same_pad(self, input, dim):
+        input_size = input.size(dim + 2)
+        filter_size = self.kernel_size[dim]
+        dilate = self.dilation if isinstance(self.dilation, int) else self.dilation[dim]
+        stride = self.stride if isinstance(self.stride, int) else self.stride[dim]
+        eff = (filter_size - 1) * dilate + 1
+        out_size = (input_size + stride - 1) // stride
+        total = max(0, (out_size - 1) * stride + eff - input_size)
+        return int(total % 2 != 0), total
+
+    def forward(self, input):
+        odd_1, pad_1 = self._same_pad(input, dim=0)
+        odd_2, pad_2 = self._same_pad(input, dim=1)
+        if odd_1 or odd_2:
+            input = F.pad(input, [0, odd_2, 0, odd_1])
+        return F.conv2d(input, self.weight, self.bias, self.stride,
+                        padding=[pad_1 // 2, pad_2 // 2],
+                        dilation=self.dilation, groups=self.groups)
+
+
+class CONV_BN_RELU(nn.Module):
+    def __init__(self, conv):
+        super().__init__()
+        self.conv = conv
+        self.bn = nn.BatchNorm2d(conv.out_channels, eps=1e-4)
+        self.relu = nn.ReLU()
+
+    def forward(self, x):
+        return self.relu(self.bn(self.conv(x)))
+
+
+class Conv(nn.Module):
+    def __init__(self, kernel, stride, input_dim, output_dim):
+        super().__init__()
+        self.fused = CONV_BN_RELU(Conv2d_tf(
+            in_channels=input_dim, out_channels=output_dim, kernel_size=kernel,
+            stride=stride, padding="SAME", bias=False))
+
+    def forward(self, x):
+        return self.fused(x)
+
+
+class SeparableConv(nn.Module):
+    def __init__(self, kernel, stride, input_dim, output_dim):
+        super().__init__()
+        self.depthwise_conv = CONV_BN_RELU(Conv2d_tf(
+            in_channels=input_dim, out_channels=input_dim, groups=input_dim,
+            kernel_size=kernel, stride=stride, padding="SAME", bias=False))
+        self.pointwise_conv = CONV_BN_RELU(Conv2d_tf(
+            in_channels=input_dim, out_channels=output_dim, kernel_size=1,
+            stride=1, padding="SAME", bias=False))
+
+    def forward(self, x):
+        return self.pointwise_conv(self.depthwise_conv(x))
+
+
+class YAMNet(nn.Module):
+    _CFG = [
+        (Conv, [3, 3], 2, 32), (SeparableConv, [3, 3], 1, 64),
+        (SeparableConv, [3, 3], 2, 128), (SeparableConv, [3, 3], 1, 128),
+        (SeparableConv, [3, 3], 2, 256), (SeparableConv, [3, 3], 1, 256),
+        (SeparableConv, [3, 3], 2, 512), (SeparableConv, [3, 3], 1, 512),
+        (SeparableConv, [3, 3], 1, 512), (SeparableConv, [3, 3], 1, 512),
+        (SeparableConv, [3, 3], 1, 512), (SeparableConv, [3, 3], 1, 512),
+        (SeparableConv, [3, 3], 2, 1024), (SeparableConv, [3, 3], 1, 1024),
+    ]
+
+    def __init__(self):
+        super().__init__()
+        input_dim = 1
+        self.layer_names = []
+        for i, (mod, kernel, stride, out_dim) in enumerate(self._CFG):
+            name = f"layer{i + 1}"
+            self.add_module(name, mod(kernel, stride, input_dim, out_dim))
+            input_dim = out_dim
+            self.layer_names.append(name)
+        self.classifier = nn.Linear(input_dim, 521, bias=True)  # unused for emb
+
+    def embeddings(self, x):
+        """x: [N, 1, 96, 64] mel patches -> [N, 1024] pooled embeddings."""
+        for name in self.layer_names:
+            x = getattr(self, name)(x)
+        x = F.adaptive_avg_pool2d(x, 1).reshape(x.shape[0], -1)
+        return x
+
+
+# ----------------------------------------------------------------------------
+# Log-mel frontend (core torch; reproduces w-hc VGGishLogMelSpectrogram config)
+# ----------------------------------------------------------------------------
+def _htk_mel_fb():
+    """HTK triangular mel filterbank [n_freqs, n_mels], torchaudio norm=None."""
+    n_freqs = N_FFT // 2 + 1                        # 257
+    all_freqs = torch.linspace(0, SR // 2, n_freqs)
+    m_min = 2595.0 * math.log10(1.0 + MEL_MIN_HZ / 700.0)
+    m_max = 2595.0 * math.log10(1.0 + MEL_MAX_HZ / 700.0)
+    m_pts = torch.linspace(m_min, m_max, N_MELS + 2)
+    f_pts = 700.0 * (10.0 ** (m_pts / 2595.0) - 1.0)
+    f_diff = f_pts[1:] - f_pts[:-1]                 # [n_mels+1]
+    slopes = f_pts.unsqueeze(0) - all_freqs.unsqueeze(1)   # [n_freqs, n_mels+2]
+    down = -slopes[:, :-2] / f_diff[:-1]
+    up = slopes[:, 2:] / f_diff[1:]
+    return torch.clamp(torch.minimum(down, up), min=0.0)   # [n_freqs, n_mels]
+
+
+_MEL_FB = _htk_mel_fb()
+_WINDOW = torch.hann_window(WIN_SAMPLES, periodic=True)
+
+
+_MIN_SAMPLES = PATCH_FRAMES * HOP_SAMPLES        # 15360 = 0.96s -> guarantees >=1 patch
+
+
+def waveform_to_patches(wav16k):
+    """wav16k: 1-D torch float32 @16k -> mel patches [n_patches, 1, 96, 64].
+
+    Clips shorter than one 0.96s window are zero-padded up to it (paper-consistent
+    zero-padding) so every clip yields at least one frame instead of being dropped.
+    """
+    if wav16k.shape[0] < _MIN_SAMPLES:
+        wav16k = torch.nn.functional.pad(wav16k, (0, _MIN_SAMPLES - wav16k.shape[0]))
+    stft = torch.stft(wav16k, n_fft=N_FFT, hop_length=HOP_SAMPLES,
+                      win_length=WIN_SAMPLES, window=_WINDOW, center=True,
+                      pad_mode="reflect", return_complex=True, normalized=False)
+    mag = stft.abs()                                # [n_freqs, T]  (power 2 -> sqrt = magnitude)
+    mel = torch.matmul(mag.transpose(0, 1), _MEL_FB)   # [T, n_mels]
+    logmel = torch.log(mel + LOG_OFFSET)            # [T, 64]
+    T = logmel.shape[0]
+    n_patches = (T - PATCH_FRAMES) // PATCH_HOP_FRAMES + 1
+    if n_patches < 1:
+        return torch.empty(0, 1, PATCH_FRAMES, N_MELS)
+    idx = torch.arange(PATCH_FRAMES).unsqueeze(0) + \
+        (torch.arange(n_patches) * PATCH_HOP_FRAMES).unsqueeze(1)   # [n_patches, 96]
+    patches = logmel[idx]                           # [n_patches, 96, 64]
+    return patches.unsqueeze(1)                     # [n_patches, 1, 96, 64]
+
+
+def patch_energy_dbfs(wav16k, n_patches):
+    """Per-patch dBFS of the raw 16k waveform slice aligned to each mel patch."""
+    win = int(round(PATCH_WINDOW_S * SR))           # 15360
+    hop = int(round(PATCH_HOP_S * SR))              # 7680
+    x = wav16k.detach().cpu().numpy()
+    out = np.empty(n_patches, dtype=np.float32)
+    for i in range(n_patches):
+        seg = x[i * hop: i * hop + win]
+        rms = float(np.sqrt(np.mean(seg.astype(np.float64) ** 2))) if seg.size else 0.0
+        out[i] = 20.0 * math.log10(rms + 1e-10)     # dBFS, full-scale ref = 1.0
+    return out
+
+
+# ----------------------------------------------------------------------------
+# Model load + audio load
+# ----------------------------------------------------------------------------
+def load_model(weights=_WEIGHTS):
+    model = YAMNet()
+    sd = torch.load(weights, map_location="cpu", weights_only=True)
+    model.load_state_dict(sd)
+    model.eval()
+    return model
+
+
+def load_audio_16k(path):
+    """Load any wav -> mono float32 @16k (scipy resample_poly for telephony 8k)."""
+    audio, sr = sf.read(path, dtype="float32", always_2d=False)
+    if audio.ndim > 1:
+        audio = audio.mean(axis=1)
+    if sr != SR:
+        g = math.gcd(int(sr), SR)
+        audio = resample_poly(audio, SR // g, int(sr) // g).astype(np.float32)
+    return torch.from_numpy(np.ascontiguousarray(audio, dtype=np.float32))
+
+
+@torch.no_grad()
+def extract_one(model, path):
+    wav = load_audio_16k(path)
+    patches = waveform_to_patches(wav)
+    n = patches.shape[0]
+    if n == 0:
+        return np.zeros((0, EMB_DIM), np.float32), np.zeros((0,), np.float32)
+    emb = model.embeddings(patches).numpy().astype(np.float32)   # [n,1024]
+    energy = patch_energy_dbfs(wav, n)
+    return emb, energy
+
+
+# ----------------------------------------------------------------------------
+# CLI
+# ----------------------------------------------------------------------------
+def _safe_stem(path, idx):
+    stem = os.path.splitext(os.path.basename(path))[0]
+    return f"{idx:06d}_{stem}.npz"
+
+
+def _cache_name(path):
+    """Stable per-clip cache filename = sha1(abspath). Lets the cache survive
+    manifest changes (row reorder / add / drop) so a later index rebuild can
+    reuse .npz by path, and --skip-existing can no-op unchanged clips."""
+    return hashlib.sha1(os.path.abspath(path).encode()).hexdigest()[:16] + ".npz"
+
+
+def run_manifest(model, manifest, out_dir, name_by_hash=False, skip_existing=False):
+    os.makedirs(out_dir, exist_ok=True)
+    rows = []
+    with open(manifest, newline="") as f:
+        reader = csv.DictReader(f)
+        if "path" not in reader.fieldnames:
+            sys.exit(f"manifest {manifest} has no 'path' column: {reader.fieldnames}")
+        entries = list(reader)
+    t0 = time.perf_counter()
+    n_reused = n_new = 0
+    for i, row in enumerate(entries):
+        path = row["path"]
+        out_name = _cache_name(path) if name_by_hash else _safe_stem(path, i)
+        out_path = os.path.join(out_dir, out_name)
+        # reuse cache only if it exists AND the source file is not newer than it
+        # (a trimmed/replaced clip at the same path has a newer mtime -> re-extract)
+        reuse = (skip_existing and os.path.exists(out_path) and os.path.exists(path)
+                 and os.path.getmtime(path) <= os.path.getmtime(out_path))
+        if reuse:
+            try:
+                n_frames = int(np.load(out_path)["n_frames"])
+            except Exception:
+                os.remove(out_path)
+            else:
+                n_reused += 1
+                rows.append({"npz": out_name, "path": path,
+                             "label": row.get("label", ""),
+                             "label_binary": row.get("label_binary", ""),
+                             "source": row.get("source", ""), "n_frames": n_frames})
+                if (i + 1) % 500 == 0:
+                    print(f"  {i + 1}/{len(entries)} (reused {n_reused}, new {n_new})...")
+                continue
+        try:
+            emb, energy = extract_one(model, path)
+        except Exception as e:
+            print(f"  [WARN] row {i} {path}: {type(e).__name__}: {e}")
+            continue
+        np.savez(out_path, embeddings=emb, energy=energy, sr=SR,
+                 n_frames=emb.shape[0])
+        n_new += 1
+        rows.append({"npz": out_name, "path": path,
+                     "label": row.get("label", ""),
+                     "label_binary": row.get("label_binary", ""),
+                     "source": row.get("source", ""),
+                     "n_frames": emb.shape[0]})
+        if (i + 1) % 500 == 0:
+            print(f"  {i + 1}/{len(entries)} (reused {n_reused}, new {n_new})...")
+    print(f"  extracted new={n_new} reused={n_reused}")
+    idx_csv = os.path.join(out_dir, "embeddings_index.csv")
+    with open(idx_csv, "w", newline="") as f:
+        w = csv.DictWriter(
+            f, fieldnames=["npz", "path", "label", "label_binary", "source", "n_frames"])
+        w.writeheader()
+        w.writerows(rows)
+    dt = time.perf_counter() - t0
+    print(f"Done: {len(rows)}/{len(entries)} clips in {dt:.1f}s -> {out_dir}")
+    print(f"Index: {idx_csv}")
+
+
+def run_single(model, wav, out_dir):
+    os.makedirs(out_dir, exist_ok=True)
+    emb, energy = extract_one(model, wav)
+    out_path = os.path.join(out_dir, _safe_stem(wav, 0))
+    np.savez(out_path, embeddings=emb, energy=energy, sr=SR, n_frames=emb.shape[0])
+    print(f"{wav}: embeddings {emb.shape}, energy {energy.shape} -> {out_path}")
+    print(f"  energy dBFS: {np.array2string(energy, precision=1, max_line_width=200)}")
+
+
+def selftest():
+    print("=== YAMNet extractor self-test ===")
+    model = load_model()
+    # (a) synthetic 8kHz input: 4s 440Hz tone, then 4s silence
+    sr_in = 8000
+    t = np.arange(4 * sr_in) / sr_in
+    tone = (0.5 * np.sin(2 * np.pi * 440 * t)).astype(np.float32)
+    silence = np.zeros(4 * sr_in, dtype=np.float32)
+    for name, sig in [("tone_4s@8k", tone), ("silence_4s@8k", silence)]:
+        wav = load_audio_16k_from_array(sig, sr_in)
+        patches = waveform_to_patches(wav)
+        with torch.no_grad():
+            emb = model.embeddings(patches).numpy()
+        energy = patch_energy_dbfs(wav, patches.shape[0])
+        finite = np.isfinite(emb).all()
+        const = bool(np.allclose(emb.std(axis=0), 0, atol=1e-4)) if emb.shape[0] > 1 else None
+        print(f"[{name}] patches={patches.shape[0]} emb={emb.shape} "
+              f"finite={finite} nan={np.isnan(emb).any()} "
+              f"emb_mean={emb.mean():.4f} emb_std={emb.std():.4f} "
+              f"all_frames_constant={const}")
+        print(f"    energy dBFS = {np.array2string(energy, precision=1)}")
+    # combined tone-vs-silence separation check
+    tone_wav = load_audio_16k_from_array(tone, sr_in)
+    sil_wav = load_audio_16k_from_array(silence, sr_in)
+    with torch.no_grad():
+        e_tone = model.embeddings(waveform_to_patches(tone_wav)).numpy()
+        e_sil = model.embeddings(waveform_to_patches(sil_wav)).numpy()
+    diff = np.linalg.norm(e_tone.mean(0) - e_sil.mean(0))
+    en_tone = patch_energy_dbfs(tone_wav, waveform_to_patches(tone_wav).shape[0])
+    en_sil = patch_energy_dbfs(sil_wav, waveform_to_patches(sil_wav).shape[0])
+    print(f"[separation] ||emb_tone - emb_silence|| = {diff:.3f}  (expect >> 0)")
+    print(f"[energy-gate] tone median dBFS={np.median(en_tone):.1f} vs "
+          f"silence median dBFS={np.median(en_sil):.1f}  "
+          f"(gap={np.median(en_tone) - np.median(en_sil):.1f} dB)")
+    # (c) benchmark: 4s clip @8k input
+    bench_sig = tone
+    for th in [1, 8]:
+        torch.set_num_threads(th)
+        w = load_audio_16k_from_array(bench_sig, sr_in)
+        with torch.no_grad():
+            model.embeddings(waveform_to_patches(w))  # warmup
+            ts = []
+            for _ in range(10):
+                t0 = time.perf_counter()
+                p = waveform_to_patches(w)
+                model.embeddings(p)
+                patch_energy_dbfs(w, p.shape[0])
+                ts.append((time.perf_counter() - t0) * 1000)
+        ts.sort()
+        p50 = ts[len(ts) // 2]
+        rtf = 4000.0 / p50
+        print(f"[bench] threads={th}: {p50:.1f} ms / 4s clip  "
+              f"(audio-sec per wall-sec = {rtf:.1f}x)")
+
+
+def load_audio_16k_from_array(sig, sr_in):
+    if sr_in != SR:
+        g = math.gcd(int(sr_in), SR)
+        sig = resample_poly(sig, SR // g, int(sr_in) // g).astype(np.float32)
+    return torch.from_numpy(np.ascontiguousarray(sig, dtype=np.float32))
+
+
+def main():
+    ap = argparse.ArgumentParser(description="YAMNet 1024-d embedding extractor")
+    ap.add_argument("--wav", help="single audio file")
+    ap.add_argument("--manifest", help="CSV with a 'path' column (+ optional label)")
+    ap.add_argument("--out-dir", default="embeddings", help="output dir for .npz")
+    ap.add_argument("--weights", default=_WEIGHTS)
+    ap.add_argument("--threads", type=int, default=0,
+                    help="torch CPU threads (0 = leave default)")
+    ap.add_argument("--name-by-hash", action="store_true",
+                    help="name .npz by sha1(abspath) (stable cache across manifest edits)")
+    ap.add_argument("--skip-existing", action="store_true",
+                    help="reuse an existing .npz instead of re-extracting")
+    ap.add_argument("--selftest", action="store_true")
+    args = ap.parse_args()
+
+    if args.threads > 0:
+        torch.set_num_threads(args.threads)
+
+    if args.selftest:
+        selftest()
+        return
+    model = load_model(args.weights)
+    if args.manifest:
+        run_manifest(model, args.manifest, args.out_dir,
+                     name_by_hash=args.name_by_hash, skip_existing=args.skip_existing)
+    elif args.wav:
+        run_single(model, args.wav, args.out_dir)
+    else:
+        sys.exit("provide --wav, --manifest, or --selftest")
+
+
+if __name__ == "__main__":
+    main()

code/predict_example.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Standalone inference for the Mission-3 AMD model (track3v4_a).
+
+Usage:
+  python3 predict_example.py <audio.wav> [threshold]
+
+Deps: pip install torch numpy soundfile scipy
+Any wav works (8k mu-law telephony audio is the trained domain; anything else
+is resampled to 16k mono internally). Default threshold 0.5; the FTC-compliance
+calibration starting point is 0.876 — see docs/REPORT_M3.md section 7 before
+trusting any fixed threshold.
+"""
+import os
+import sys
+
+import torch
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+import extract_embeddings as xe            # noqa: E402
+from sweep_head import build_config_head   # noqa: E402
+
+MODEL_DIR = os.path.join(HERE, "..")
+
+
+def load():
+    yamnet = xe.load_model(os.path.join(MODEL_DIR, "v5b_full.yamnet.pth"))
+    ck = torch.load(os.path.join(MODEL_DIR, "v5b_full.head.pt"),
+                    map_location="cpu", weights_only=False)
+    head = build_config_head(ck["config"])
+    head.load_state_dict(ck["state_dict"])
+    head.eval()
+    return yamnet, head
+
+
+def predict(yamnet, head, wav_path):
+    """Returns p_machine in [0,1]."""
+    wav = xe.load_audio_16k(wav_path)
+    patches = xe.waveform_to_patches(wav)
+    if patches.shape[0] == 0:
+        return 0.0  # no audio frames -> fail-open as human
+    with torch.no_grad():
+        emb = yamnet.embeddings(patches)                    # [n, 1024]
+        x = emb.unsqueeze(0)                                # [1, n, 1024]
+        lengths = torch.tensor([emb.shape[0]], dtype=torch.long)
+        return float(torch.sigmoid(head(x, lengths)).item())
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        sys.exit(__doc__)
+    torch.set_num_threads(1)
+    t = float(sys.argv[2]) if len(sys.argv) > 2 else 0.5
+    yamnet, head = load()
+    p = predict(yamnet, head, sys.argv[1])
+    print(f"p_machine={p:.4f}  ->  {'MACHINE' if p >= t else 'HUMAN'}  (threshold {t})")

code/sweep_head.py

@@ -0,0 +1,124 @@
+"""Configurable GRU classifier head for YAMNet embeddings (Mission-2 sweep).
+
+Superset of gru_head.GRUHead: keeps the exact same math when built with the
+canonical config (proj=32, hidden=48, layers=1, unidirectional, pooling='last',
+dropout=0) but exposes every knob the round-1 grid needs:
+
+    proj_dim, hidden, num_layers, bidirectional, pooling {last|mean|attn}, dropout
+
+`forward` returns a RAW LOGIT (no sigmoid), like gru_head, so training uses
+BCEWithLogitsLoss for numerical stability. This module is NEW; it does not touch
+gru_head.py / head_best.pt / the deployed adapter.
+
+Pooling semantics (over the GRU output sequence, honoring per-clip lengths):
+  last : final hidden state h_n. Bidirectional -> concat last-layer fwd+bwd.
+  mean : mean of GRU outputs over valid timesteps.
+  attn : additive-attention weighted sum of GRU outputs over valid timesteps.
+"""
+import torch
+import torch.nn as nn
+from torch.nn.utils.rnn import pack_padded_sequence, pad_packed_sequence
+
+EMB_DIM = 1024
+
+
+class ConfigGRUHead(nn.Module):
+    def __init__(self, emb_dim=EMB_DIM, proj=32, hidden=48, num_layers=1,
+                 bidirectional=False, pooling="last", dropout=0.0):
+        super().__init__()
+        assert pooling in ("last", "mean", "attn"), pooling
+        self.pooling = pooling
+        self.bidirectional = bool(bidirectional)
+        self.num_layers = int(num_layers)
+        self.hidden = int(hidden)
+
+        self.proj = nn.Linear(emb_dim, proj)                    # Dense(1024->proj), tanh below
+        self.in_drop = nn.Dropout(dropout) if dropout > 0 else nn.Identity()
+        gru_drop = dropout if (num_layers > 1 and dropout > 0) else 0.0
+        self.gru = nn.GRU(proj, hidden, num_layers=num_layers, batch_first=True,
+                          bidirectional=self.bidirectional, dropout=gru_drop)
+
+        dirs = 2 if self.bidirectional else 1
+        self.feat_dim = hidden * dirs
+        if pooling == "attn":
+            self.attn_w = nn.Linear(self.feat_dim, self.feat_dim)
+            self.attn_v = nn.Linear(self.feat_dim, 1, bias=False)
+        self.out_drop = nn.Dropout(dropout) if dropout > 0 else nn.Identity()
+        self.out = nn.Linear(self.feat_dim, 1)                  # Dense(feat->1)
+
+    # -- pooling helpers -----------------------------------------------------
+    def _last(self, h_n):
+        """Final hidden state -> [B, feat_dim]. h_n: [layers*dirs, B, hidden]."""
+        if self.bidirectional:
+            fwd = h_n[-2]                                       # last layer forward
+            bwd = h_n[-1]                                       # last layer backward
+            return torch.cat([fwd, bwd], dim=-1)
+        return h_n[-1]
+
+    def _masked_seq(self, packed_out, lengths, batch_first_shape):
+        """Unpack -> (out [B,Tmax,feat], mask [B,Tmax] bool)."""
+        out, _ = pad_packed_sequence(packed_out, batch_first=True)  # [B,Tmax,feat]
+        B, Tmax = out.shape[0], out.shape[1]
+        idx = torch.arange(Tmax, device=out.device).unsqueeze(0)    # [1,Tmax]
+        mask = idx < lengths.to(out.device).unsqueeze(1)            # [B,Tmax]
+        return out, mask
+
+    def forward(self, x, lengths):
+        """x: [B, T, emb_dim] padded. lengths: [B] valid frame counts. -> logit [B]."""
+        h = torch.tanh(self.proj(x))
+        h = self.in_drop(h)
+        packed = pack_padded_sequence(h, lengths.cpu(), batch_first=True,
+                                      enforce_sorted=False)
+        packed_out, h_n = self.gru(packed)
+
+        if self.pooling == "last":
+            feat = self._last(h_n)                              # [B, feat]
+        else:
+            out, mask = self._masked_seq(packed_out, lengths, x.shape)
+            m = mask.unsqueeze(-1).float()                      # [B,Tmax,1]
+            if self.pooling == "mean":
+                feat = (out * m).sum(1) / m.sum(1).clamp(min=1.0)
+            else:  # attn
+                score = self.attn_v(torch.tanh(self.attn_w(out))).squeeze(-1)  # [B,Tmax]
+                score = score.masked_fill(~mask, float("-inf"))
+                w = torch.softmax(score, dim=1).unsqueeze(-1)   # [B,Tmax,1]
+                feat = (out * w).sum(1)
+
+        feat = self.out_drop(feat)
+        return self.out(feat).squeeze(-1)
+
+
+def build_config_head(config):
+    """Construct a ConfigGRUHead from a config dict (arch keys only)."""
+    return ConfigGRUHead(
+        emb_dim=EMB_DIM,
+        proj=int(config.get("proj_dim", 32)),
+        hidden=int(config.get("hidden", 48)),
+        num_layers=int(config.get("num_layers", 1)),
+        bidirectional=bool(config.get("bidirectional", False)),
+        pooling=config.get("pooling", "last"),
+        dropout=float(config.get("dropout", 0.0)),
+    )
+
+
+def param_count(model):
+    return sum(p.numel() for p in model.parameters())
+
+
+if __name__ == "__main__":
+    # sanity: canonical config must match the 44,657-param deployed head math
+    from gru_head import PARAM_COUNT
+    m = build_config_head({"proj_dim": 32, "hidden": 48, "num_layers": 1,
+                           "bidirectional": False, "pooling": "last", "dropout": 0.0})
+    n = param_count(m)
+    print(f"canonical ConfigGRUHead params = {n} (expected {PARAM_COUNT}): {n == PARAM_COUNT}")
+    x = torch.randn(3, 5, EMB_DIM)
+    lens = torch.tensor([5, 3, 1])
+    for pool in ("last", "mean", "attn"):
+        for bi in (False, True):
+            for nl in (1, 2):
+                mm = build_config_head({"proj_dim": 64, "hidden": 96, "num_layers": nl,
+                                        "bidirectional": bi, "pooling": pool, "dropout": 0.2})
+                y = mm(x, lens)
+                assert y.shape == (3,), (pool, bi, nl, y.shape)
+    print("forward shapes OK across pooling x bidir x layers")

v5b_full.head.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b1eb0b111fd1919f419e2eea134964a8f3fa9b311976441d312a83373a653368
+size 1051115

v5b_full.json

@@ -0,0 +1,16 @@
+{
+  "backbone_weights": "/root/amd/tracks/yamnet/experiments/backbone/v5b_full.yamnet.pth",
+  "head_weights": "/root/amd/tracks/yamnet/experiments/backbone/v5b_full.head.pt",
+  "head_config": {
+    "proj_dim": 128,
+    "hidden": 96,
+    "num_layers": 1,
+    "bidirectional": true,
+    "pooling": "last",
+    "dropout": 0.0
+  },
+  "gate_dbfs": -300.0,
+  "decision_threshold": 0.5,
+  "unfreeze_blocks": 2,
+  "note": "load backbone via extract_embeddings.load_model(backbone_weights); build head via sweep_head.build_config_head(head_config)."
+}

v5b_full.yamnet.pth

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:da4037dc39907021b8ac44e491a763defad1b4ff67532607fab9f86563a20cde
+size 15101511