Model card: add the breath head nll-hubert-ls960-v1 and M4Singer attribution

README.md

@@ -7,6 +7,7 @@ tags:
   - forced-alignment
   - singing-voice
   - phoneme-alignment
+  - breath-detection
   - hubert
 library_name: singalign
 pipeline_tag: audio-to-audio
@@ -26,6 +27,7 @@ name and verifies the pinned SHA256 before it puts anything on disk.
 |---|---|---:|---|
 | `hfa-mandarin-fullweak-v1.ckpt` | HubertFA | 54.2 MB | `d38f7d5839e2cd93e8dec5b77b6bd3ed28aa1318d5ed069c2cd81c899dd3c057` |
 | `hfa-english-fullweak-v1.ckpt` | HubertFA | 54.1 MB | `c1b2baa939a87b3ed832c97e18eba9fcb27214b39f50ff346c062601bd11c513` |
+| `nll-hubert-ls960-v1.pt` | breath head (NLL) for the English aligner | 9.9 MB | `03587e7a476aea7f137904e6034420d0a4b255d12949e85ec16b20077ae29ce8` |
 
 ## `hfa-mandarin-fullweak-v1`
 
@@ -157,16 +159,70 @@ aligner = HubertFATorchAligner(ckpt="hfa-english-fullweak-v1", g2p="G2pEn")
 results = aligner.align([{"id": "x", "audio_path": "a.wav", "text": "english lyrics"}])
 ```
 
+## `nll-hubert-ls960-v1`
+
+A **breath (non-lexical) head**, not an aligner: a 2.45 M-parameter CVNT that
+labels each 10 ms frame `None` / `AP` from the HuBERT units the aligner has
+already computed, and whose breaths are spliced into the finished alignment as
+`AP` without touching any other boundary. It rides on
+`hfa-english-fullweak-v1` as `ap_detector="nll"` and is selected automatically
+for any HubertFA aligner whose front-end is `hubert-base-ls960`.
+
+- **Why it exists**: a breath head is bound to the SSL front-end it was
+  trained on. The head shipped inside upstream HubertFA's ONNX bundle was
+  trained on `chinese-hubert-base` units; run over `hubert-base-ls960` units
+  (same 768 width, unrelated latent space) it recalls **0.001** of the breaths
+  in held-out English singing -- nothing. The toolkit now refuses that pairing.
+- **Recipe**: `configs/nll/train_v2.yaml`, data `configs/nll/binarize_v2.yaml`;
+  class-weighted CE + focal + dice, 15000 steps, **step 7500** selected on
+  frame-F1 over the annotation-consistent held-out groups.
+- **Training data (59.3 h)**: GTSinger singers whose breath annotation agrees
+  with the upstream head's convention (ZH ×2, EN-Alto-2, EN-Tenor-1, IT ×3,
+  ES-Soprano-1; 32.7 h) + M4Singer (26.7 h). Five GTSinger languages label the
+  whole inter-phrase gap as breath; a head trained on all of GTSinger learns
+  "gap ⇒ breath" and its precision collapses on any other corpus.
+- **Binary**: `None` / `AP`. No tail-breath (`EP`) class.
+
+### Results
+
+Frame-F1 at threshold 0.5, scored only inside the gold non-content regions
+(where a breath could be), on songs held out by title:
+
+| Held-out set | This head | Upstream head on its own front-end |
+|---|---:|---:|
+| GTSinger Chinese (2 singers, 1.7 h) | 0.885 / 0.872 | 0.844 / 0.790 |
+| GTSinger English, consistent singers (1.3 h) | 0.782 / 0.750 | 0.746 / 0.712 |
+| M4Singer held-out songs (3.0 h) | **0.893** | 0.826 |
+| Opencpop, all 3756 clips (5.2 h, never trained on) | 0.815 | **0.931** |
+
+The Opencpop gap is a known limitation: this head still over-fires on
+Opencpop's silent gaps (precision 0.69 at recall 0.99). Full account, including
+the per-singer annotation probe:
+`docs/experiments/nll_hubert_ls960_v1.md` in the toolkit.
+
+### Usage
+
+```python
+from modules.api import HubertFATorchAligner
+
+aligner = HubertFATorchAligner(ckpt="hfa-english-fullweak-v1", g2p="G2pEn",
+                               ap_detector="nll")   # resolves to this head
+```
+
+Pairing it with a `chinese-hubert-base` aligner raises; the Mandarin line keeps
+the upstream head.
+
 ## Training data, attribution and terms
 
-Both checkpoints are derived from corpora with their own terms. Attribution is
+All 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 |
+| [GTSinger](https://github.com/GTSinger/GTSinger) | all three | CC BY-NC-SA 4.0 — attribution, non-commercial, **ShareAlike** |
+| [M4Singer](https://github.com/M4Singer/M4Singer) | Mandarin, breath head | CC BY-NC-SA 4.0; cite Zhang et al., *M4Singer*, NeurIPS 2022 |
+| Opencpop | Mandarin | research corpus; cite its paper |
 | [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 |
@@ -181,7 +237,8 @@ weights.
   ~[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.
 - **One language per checkpoint.** Each model's inventory and frozen encoder
-  are language-specific; there is no multilingual checkpoint.
+  are language-specific; there is no multilingual checkpoint. The breath head
+  is language-independent but **front-end-specific**.
 - 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** for that reason, under