Document the English checkpoint, its corpora terms and its limits

README.md

@@ -1,7 +1,8 @@
 ---
-license: cc-by-nc-4.0
+license: cc-by-nc-sa-4.0
 language:
   - zh
+  - en
 tags:
   - forced-alignment
   - singing-voice
@@ -24,6 +25,7 @@ name and verifies the pinned SHA256 before it puts anything on disk.
 | File | Family | Size | SHA256 |
 |---|---|---:|---|
 | `hfa-mandarin-fullweak-v1.ckpt` | HubertFA | 54.2 MB | `d38f7d5839e2cd93e8dec5b77b6bd3ed28aa1318d5ed069c2cd81c899dd3c057` |
+| `hfa-english-fullweak-v1.ckpt` | HubertFA | 54.1 MB | `c1b2baa939a87b3ed832c97e18eba9fcb27214b39f50ff346c062601bd11c513` |
 
 ## `hfa-mandarin-fullweak-v1`
 
@@ -89,17 +91,102 @@ aligner = HubertFATorchAligner()             # resolves to this checkpoint
 results = aligner.align([{"id": "x", "audio_path": "a.wav", "text": "中文歌词"}])
 ```
 
+## `hfa-english-fullweak-v1`
+
+The same alignment head over a **frozen `facebook/hubert-base-ls960`
+front-end** — same HuBERT-base recipe as the Mandarin model, so only the
+encoder path and the phoneme inventory differ.
+
+- **Recipe**: `configs/hfa/train_en_fullweak.yaml`, data
+  `configs/hfa/binarize_en_fullweak.yaml`.
+- **Training data**: 21.4 h full-label across **13 singers** (GTSinger-en,
+  ACV-001, Project-AIdol, 8 of NUS-48E's 12 singers) + 1845 h weak-label
+  English singing (lyrics only, no phoneme durations).
+- **Step 54000**, selected by CBER on held-out singers — *not* the final
+  step-60000 weights.
+- **Phoneme inventory**: the 39 CMUdict ARPAbet phones (stress stripped) plus
+  `SP`, `english-arpabet-v1` profile.
+- **G2P**: G2pEn (CMUdict + a seq2seq for OOV) — no dictionary to configure.
+
+### Results
+
+Scored on **four held-out NUS-48E singers** (201 clips, 0.53 h) — two from each
+mode of the corpus's F0 distribution, none of whom appears in training. The
+same suite selected the checkpoint, so read these as in-suite numbers.
+
+| System | CBER ↓ | VER20 ↓ | VER50 ↓ | mIoU ↑ |
+|---|---:|---:|---:|---:|
+| `hfa-english-fullweak-v1` | 0.1975 | 0.1318 | **0.0616** | 0.7821 |
+| Same recipe, full label only (21.4 h) | **0.1940** | **0.1300** | 0.0617 | **0.7833** |
+
+**The weak label bought nothing measurable here.** The two models tie, and the
+gap is smaller than this run's own validation-point scatter. It is released as
+the default English model on the grounds that the Mandarin line measured weak
+label buying robustness on *rough* recordings — but English has no rough-domain
+held-out set to check that on, because the validation set is studio singing
+while the weak label is crawled audio. If your material is clean, expect
+nothing from the extra 1845 h. The full account is in
+`docs/experiments/hfa_en_full_weak_v1.md` in the toolkit.
+
+### Batched inference is not bit-reproducible
+
+This checkpoint **does not pass** the toolkit's batch-invariance gate:
+`bench/tools/validate_hfa_batch.py` measures a **10.5 ms** maximum boundary
+shift between batch-1 and batch-8 against a 1.0 ms tolerance. Scale: one
+boundary of one clip in 48, between content phones (`SH | IY`) rather than on
+an `SP` edge, so an adapter does not drop it.
+
+Batching changes the floating-point reduction order in the linear layers, and
+weak-label training leaves the logits flat enough at an acoustically ambiguous
+boundary that the last-bit difference moves the Viterbi path. A deterministic
+tie-break cannot fix it — the inputs genuinely differ. Set `max_batch_size=1`
+if you need reproducibility. For comparison, the full-label-only model measures
+0.003 ms on the same items.
+
+### Runtime dependency
+
+[`facebook/hubert-base-ls960`](https://huggingface.co/facebook/hubert-base-ls960),
+**not** the Mandarin encoder — the two are not interchangeable.
+
+### Usage
+
+```python
+from modules.api import HubertFATorchAligner
+
+aligner = HubertFATorchAligner(ckpt="hfa-english-fullweak-v1", g2p="G2pEn")
+results = aligner.align([{"id": "x", "audio_path": "a.wav", "text": "english lyrics"}])
+```
+
+## Training data, attribution and terms
+
+Both checkpoints are derived from corpora with their own terms. Attribution is
+required by several of them; the ShareAlike terms are why this repository is
+CC-BY-NC-SA-4.0 rather than CC-BY-NC-4.0.
+
+| Corpus | Used by | Terms |
+|---|---|---|
+| [GTSinger](https://github.com/GTSinger/GTSinger) | both | CC BY-NC-SA 4.0 — attribution, non-commercial, **ShareAlike** |
+| M4Singer, Opencpop | Mandarin | research corpora; cite their papers |
+| [Project-AIdol](https://github.com/lottev1991) | English | CC BY-SA 4.0. Created by **Lotte V (@lottev1991)**. The dataset asks that it not be used with voice changers (RVC and similar), and that models featuring the voice not be publicly released without prior permission — this is an aligner, which predicts phone boundaries and cannot reproduce a voice. |
+| ACV-001 | English | supplied as supplementary data; check the source for its current terms |
+| NUS-48E | English | shared for **research purposes only**; cite Duan, Fang, Li, Sim and Wang, *The NUS Sung and Spoken Lyrics Corpus*, APSIPA ASC 2013 |
+| CrawlSinger (zh / en) | both | scraped singing; the underlying recordings are third-party copyrighted works |
+
+No audio from any of these corpora is redistributed here — only trained
+weights.
+
 ## Caveats
 
 - **`confidence` does not transfer across models.** SOFA scores land in
   ~[0.79, 1] and HubertFA in ~[0.67, 0.95], and the score is a top-2 pairwise
   margin. Any threshold inherited from another model has to be re-calibrated.
-- **Mandarin only.** The inventory and the frozen encoder are both Chinese;
-  there is no released multilingual checkpoint.
-- The weak-label half of the training data is scraped Mandarin singing whose
+- **One language per checkpoint.** Each model's inventory and frozen encoder
+  are language-specific; there is no multilingual checkpoint.
+- The weak-label half of both models' training data is scraped singing whose
   underlying recordings are third-party copyrighted works. The weights are
-  released for **non-commercial research** (CC-BY-NC-4.0) for that reason; the
-  toolkit's source code is MIT and licensed separately.
+  released for **non-commercial research** for that reason, under
+  **CC-BY-NC-SA-4.0** — ShareAlike because GTSinger, in both models' full-label
+  data, carries it. The toolkit's source code is MIT and licensed separately.
 
 ## Citation