Upload README.md with huggingface_hub

README.md

@@ -1,5 +1,7 @@
 ---
 license: mit
+library_name: pytorch
+pipeline_tag: audio-classification
 tags:
   - audio
   - audio-classification
@@ -8,6 +10,10 @@ tags:
   - open-set-recognition
   - wavlm
   - encodec
+datasets:
+  - mueller91/MLAAD
+metrics:
+  - accuracy
 ---
 
 # sourcetrace — fitted heads for open-set audio deepfake source tracing
@@ -21,16 +27,65 @@ generator is not one it has seen.
 They hold the small trained head plus the fitted scoring stack (class anchors,
 relative-Mahalanobis density, z-norm constants, conformal calibration, per-block
 whitening). The front-ends — `microsoft/wavlm-large` and `facebook/encodec_24khz` — are
-frozen, are **not** included here, and are fetched separately by
-`scripts/download_models.py`.
+frozen, are **not** included here, and are fetched separately by `./setup.sh`.
+
+## Model
+
+| | |
+|---|---|
+| Input | 2133-d feature vector, **not** audio |
+| SSL front end | `microsoft/wavlm-large`, **frozen**, layers 4–7, mean\|std pooled → 2048-d |
+| Signature channel | 24 group-delay bands + 16 modulation bins + 12 codec-grid dims → 52-d |
+| Codec channel | `facebook/encodec_24khz` reconstruction residual at 1.5 / 6 / 12 kbps → 33-d |
+| Head | factorized gated, AM 192 + vocoder 64 + codec 32 = 288-d, tanh FiLM gates |
+| Embedding | 800-d = 288 score branch ‖ 512 whitened transfer branch |
+| Trainable parameters | 1,089,888 (548,576 head + 541,312 transfer) |
+| Training | Adam, lr 3e-4, no weight decay, 300 epochs, batch 512 |
+
+The file is far larger than the parameter count because most of it is the fitted
+scoring stack — 65 per-class Mahalanobis precisions at 288×288 float64, plus the
+whitening matrices — not weights.
+
+The codec channel is the contribution: re-encode each clip through EnCodec-24 kHz
+and keep what it got *wrong*. Those 33 numbers come off the waveform the speech
+model never sees. Deleting the channel moves FPR95 from 1.14 % to 2.70 % while
+closed-set accuracy barely changes — it buys *rejection*, not attribution.
+
+The head in the public code is a reconstruction from the published method
+description, not a recovered original; its construction order is load-bearing for
+RNG reproducibility.
 
 ## Input
 
 Not audio. A **2133-d** feature vector per clip, laid out as
 `[ SSL 0:2048 | signature 2048:2100 | codec residual 2100:2133 ]`, produced by
-`scripts/extract_features.py`. There is no way to run these weights without the
+`python -m sourcetrace.extract`. There is no way to run these weights without the
 repository and an extracted feature cache.
 
+## Files
+
+| file | size | what it is |
+|---|---|---|
+| `mlaad_v5.pt` | 79 MB | MLAAD v5, 65 known generator families |
+| `stopa.pt` | 18 MB | STOPA, 13 attack classes |
+
+Both are sha256-verified on download against digests compiled into
+`scripts/download_weights.py`, not served from here. A digest served from the same
+place as the file it describes attests to nothing.
+
+## Use
+
+```bash
+git clone https://github.com/pujariaditya/sourcetrace && cd sourcetrace
+pip install -e . && ./setup.sh
+python scripts/download_weights.py      # both heads, sha256-pinned
+python -m sourcetrace.evaluate --task mlaad_v5 --checkpoint checkpoints/mlaad_v5.pt
+```
+
+Downloading saves the ~35–40 min fit and nothing else: evaluation still reads the
+feature cache, so MLAAD v5 must be downloaded and extracted first. See the
+repository README for that step.
+
 ## `mlaad_v5.pt`
 
 MLAAD v5, family-level open-set protocol: 65 known generator families, 9,620 evaluation
@@ -38,24 +93,16 @@ trials, split seed 42, fit seed 0.
 
 | Metric | Value | Published SOTA |
 |---|---|---|
-| FPR95 (lower better) | **1.14 %** | 3.36 % |
-| OOD-EER (lower better) | 3.66 % | — |
-| Closed-set accuracy | 99.34 % | — |
+| FPR95 ↓ | **1.14 %** | 3.36 % |
+| OOD-EER ↓ | 3.66 % | — |
+| Closed-set accuracy ↑ | 99.34 % | — |
 
 Conformal abstention: measured coverage 96.11 % against a 95 % nominal level.
 
 **Reproducible, not just reported.** Refitting from the public code at these seeds
 reproduces `results/ablation/full.json` bit-for-bit — FPR95 1.1428571428571428, OOD-EER
 3.6571428571428575, closed-set 99.33714285714285, under exact equality rather than a
-tolerance. This file is that fit. Downloading it saves the ~35-40 min fit and nothing
-else: evaluation still reads the feature cache, so MLAAD v5 must be downloaded and
-extracted first.
-
-```bash
-huggingface-cli download RootAccess4Life/ood-source-tracing mlaad_v5.pt \
-    --local-dir checkpoints
-python scripts/evaluate.py --task mlaad_v5 --checkpoint checkpoints/mlaad_v5.pt
-```
+tolerance. This file is that fit.
 
 **Single-seed.** One split seed, one fit seed. These are point estimates with no
 variance attached; do not read the margin over 3.36 % as a measured effect size.
@@ -63,39 +110,37 @@ variance attached; do not read the margin over 3.36 % as a measured effect size.
 ## `stopa.pt`
 
 STOPA cross-corpus open-set protocol: 3 EET attacks fitted, 5 known enrolled, 5 unknown
-held out; 33,200 enrolment and 629,800 trial clips, conditions pooled, split seed 42 /
-fit seed 0.
+held out; 33,200 enrolment and 629,800 probe utterances, conditions pooled, split seed
+42 / fit seed 0.
 
-| Metric | Value | Published SOTA |
+| Metric | Value | Published |
 |---|---|---|
-| Unknown-attack EER (lower better) | **9.33 %** | 16.43 % |
-| Known-attack EER | 10.79 % | — |
+| Unknown-attack EER ↓ | **9.33 %** | 16.43 % |
+| Known-attack EER ↓ | 10.79 % | — |
 
-Measured by the released code on 2026-08-18; raw numbers in `results/stopa_measured.json`.
+Measured by the released code on 2026-08-18; raw numbers in
+`results/stopa_measured.json`.
 
-A lost earlier implementation had recorded 9.38 % and the paper declines to print it,
-because no identified run stood behind it. The figure above is **not** a recovery of that
-run — different implementation, and the reference head's seeded initialisation is
-unrecoverable. It is an independent measurement that happens to land 0.05 points away,
-with a protocol, seeds and a results file behind it. Cite this one, not 9.38.
+9.33 % sits below every baseline STOPA itself reports — mid-30s for AASIST-family
+countermeasures, near 50 % for ResNet-34 — and those are the like-for-like anchors:
+trained systems, scored the same way, over the same partition. **No margin is claimed
+over the lower published 16.43 %.** That is a *zero-shot* system, fitted on no STOPA
+split, where this head is fitted on EET; the two share a metric but not a setting.
 
 **Single-seed**, like the MLAAD numbers above.
 
-```bash
-huggingface-cli download RootAccess4Life/ood-source-tracing stopa.pt --local-dir checkpoints
-python scripts/evaluate.py --task stopa --checkpoint checkpoints/stopa.pt
-```
-
 ## Limitations
 
 - Trained on MLAAD v5 only. Attribution across other corpora, languages, codecs or
   recording conditions is untested.
-- The head in the public code is a reconstruction from `docs/METHOD.md`. It does not
-  reproduce an earlier reference implementation's FPR95 = 0.7543 % / OOD-EER = 2.81 %;
-  that head's seeded initialisation is unrecoverable and those figures are retired.
-- For research on open-set attribution. Not validated for forensic, legal or moderation
-  use; the abstention rule is calibrated on this protocol and its coverage guarantee
-  does not transfer off it.
+- Both numbers are single-seed point estimates.
+- For research on open-set attribution. **Not validated for forensic, legal or
+  moderation use**, and the abstention rule is calibrated on this protocol — its
+  coverage guarantee does not transfer off it.
+- The harm from an attribution model is a confident wrong name, not a refusal. On an
+  unseen generator the calibrated answer is *unknown*, and that answer is the point
+  of the system; do not deploy it anywhere the abstention is discarded, and do not
+  present an attribution as evidence about a person.
 
 ## Licence
 
@@ -104,12 +149,8 @@ redistributed here.
 
 ## Citation
 
-```bibtex
-@inproceedings{pujari2027frontend,
-  title     = {Front-End Evidence and Calibrated Abstention for
-               Open-Set Audio Deepfake Attribution},
-  author    = {Pujari, Aditya},
-  booktitle = {Proc. IEEE ICASSP},
-  year      = {2027}
-}
-```
+See [`CITATION.cff`](https://github.com/pujariaditya/sourcetrace/blob/main/CITATION.cff)
+in the code repository, which is the single source for how to cite this.
+
+Please also cite the benchmarks (MLAAD, STOPA) and the baselines this is compared
+against (Neamtu et al., EUSIPCO 2026; Chhibber et al., Odyssey 2026).