Rewrite the model card for the v0.1.1 release

README.md

@@ -15,31 +15,42 @@ pipeline_tag: text-to-audio
 
 # StaleyNET checkpoints
 
-Weights for **StaleyNET**, a text-prompted music generator trained from random
-initialization in Rust on NVIDIA edge GPUs. No pretrained network, codec,
-vocoder, or text encoder is used: the Transformer, the residual vector
-quantizer, the Griffin-Lim vocoder, and every GPU kernel are implemented in the
-project.
+Weights for **StaleyNET**, a text-prompted music generator trained from random initialization in Rust on NVIDIA edge GPUs. The Transformer, residual vector quantizer, Griffin-Lim vocoder, and GPU kernels are implemented in the project.
 
-The code, paper, and book live in the companion GitHub repository:
+The code, paper, and book live in the companion repository:
 <https://github.com/arpanpathak/staleynet>.
 
+## Release v0.1.1
+
+- GitHub release: <https://github.com/arpanpathak/staleynet/releases/tag/v0.1.1>
+- `staleynet-audio` 0.1.1 on crates.io: <https://crates.io/crates/staleynet-audio>
+- Test status: 171 tests pass, including 18 GPU integration tests on a Jetson Orin.
+- CI: rustfmt, clippy with warnings denied, cargo-deny, and the audio coverage gate.
+
+## At a glance
+
+| Item | Value |
+|---|---|
+| Checkpointed runs | 6 |
+| Parameters | 7,099,904 for text-only runs; 7,165,440 for the lyrics run |
+| Transformer | width 256, 8 heads, 6 layers, context 768 |
+| Audio tokens | 4 residual codebooks, 1024 entries each |
+| Audio features | 128 mel bands at 24 kHz, FFT 1024, hop 256 |
+| Training data | Song Describer Dataset and JamendoLyrics MultiLang |
+| License | CC BY-SA 4.0, subject to the upstream dataset terms |
+
 ## Checkpoints
 
 | Run | Purpose | Parameters | `best` step | `latest` step | Training tracks |
 |---|---|---:|---:|---:|---:|
-| `thor-base` | base text-to-music model | 7,099,904 | 0 | — | 667 |
+| `thor-base` | base text-to-music model | 7,099,904 | 0 | None | 667 |
 | `smoke` | pipeline smoke test | 7,099,904 | 0 | 1,500 | 667 |
 | `overfit-one-take` | single-take memorisation check | 7,099,904 | 200 | 200 | 1 |
 | `vocal-scratch` | vocal-filtered model from scratch | 7,099,904 | 5,500 | 6,000 | 281 |
-| `vocal-finetune` | vocal fine-tune | 7,099,904 | 250 | — | 281 |
+| `vocal-finetune` | vocal fine-tune | 7,099,904 | 250 | None | 281 |
 | `lyrics-orin` | lyrics-conditioned model | 7,165,440 | 3,750 | 4,000 | 543 (73 with lyrics) |
 
-The step numbers are exactly what each `model.json` records. `best/` is the
-weight-only checkpoint selected by validation; `latest/` is the resumable
-checkpoint with AdamW moments. Some early runs stored only `best/`, and
-`thor-base` / `smoke` record step 0 in their `best/model.json`; where a
-`latest/` exists, prefer it for the late training state.
+The step values are exactly what each `model.json` records. `best/` is the weight-only checkpoint selected by validation. `latest/` is the resumable checkpoint with AdamW moments. Some early runs stored only `best/`, and `thor-base` and `smoke` record step 0 in their `best/model.json`. Where a `latest/` exists, prefer it for the late training state.
 
 ## Layout
 
@@ -52,10 +63,7 @@ metrics/                     full metrics.jsonl for every run
 logs/                        captured training logs
 ```
 
-`tensors.bin` is little-endian `f32` in parameter-visitor order. `latest/`
-appends the AdamW first moments and then the second moments; `model.json`
-records the tensor manifest, the step, whether optimizer state is present, and
-the training configuration.
+`tensors.bin` is little-endian `f32` in parameter-visitor order. `latest/` appends the AdamW first moments and then the second moments. `model.json` records the tensor manifest, the step, whether optimizer state is present, and the training configuration.
 
 ## Download and use
 
@@ -82,29 +90,23 @@ staleynet sing \
   --out song.wav
 ```
 
-Architecture: width 256, 8 heads, 6 layers, feed-forward multiplier 4, context
-length 768, 4 residual codebooks of 1024 entries, 128 mel bands at 24 kHz.
-`lyrics-orin` adds a 256-byte lyrics field.
+Architecture: width 256, 8 heads, 6 layers, feed-forward multiplier 4, context length 768, 4 residual codebooks of 1024 entries, 128 mel bands at 24 kHz. `lyrics-orin` adds a 256-byte lyrics field.
 
 ## Training data and licensing
 
-- **Song Describer Dataset** (SDD), Zenodo record
-  [10072001](https://zenodo.org/records/10072001): 706 Jamendo recordings
-  with human captions. Captions are CC BY-SA 4.0; the recordings carry the
-  per-track Creative Commons licences in `audio_licenses.txt`, including
-  CC BY-NC-ND and CC BY-NC-SA.
-- **JamendoLyrics MultiLang**, <https://github.com/f90/jamendolyrics>: code and
-  metadata are MIT; songs and lyrics carry the per-song CC licences in
-  `JamendoLyrics.csv`.
+- **Song Describer Dataset** (SDD), Zenodo record [10072001](https://zenodo.org/records/10072001): 706 Jamendo recordings with human captions. Captions are CC BY-SA 4.0. The recordings carry the per-track Creative Commons licenses in `audio_licenses.txt`, including CC BY-NC-ND and CC BY-NC-SA.
+- **JamendoLyrics MultiLang**, <https://github.com/f90/jamendolyrics>: code and metadata are MIT. Songs and lyrics carry the per-song CC licenses in `JamendoLyrics.csv`.
 
-Because the training audio includes NonCommercial and NoDerivatives tracks,
-these checkpoints are **research artifacts, not a commercial product**. Do not
-use them commercially where the upstream recording licences forbid it, and do
-not use them to impersonate a singer without consent.
+Because the training audio includes NonCommercial and NoDerivatives tracks, these checkpoints are research artifacts, not a commercial product. Do not use them commercially where the upstream recording licenses forbid it, and do not use them to impersonate a singer without consent.
 
-The checkpoint files are offered under CC BY-SA 4.0
-(`LICENSE-CC-BY-SA-4.0.txt`) to the extent the upstream dataset licences allow.
-See `NOTICE` for the full provenance statement and `SHA256SUMS` for integrity.
+The checkpoint files are offered under CC BY-SA 4.0 (`LICENSE-CC-BY-SA-4.0.txt`) to the extent the upstream dataset licenses allow. See `NOTICE` for the full provenance statement and `SHA256SUMS` for integrity.
+
+## Known limitations
+
+- Griffin-Lim produces phasey audio compared with a learned vocoder.
+- The models are small edge models, not production music systems.
+- The lyric models were trained on a small lyrics subset, so lyric intelligibility is limited.
+- The checkpoints are research artifacts and have no warranty.
 
 ## Citation
 
@@ -117,5 +119,3 @@ See `NOTICE` for the full provenance statement and `SHA256SUMS` for integrity.
   url    = {https://github.com/arpanpathak/staleynet}
 }
 ```
-
-No warranty. This is a research checkpoint, not a production model.