Upload README.md with huggingface_hub

README.md

@@ -11,26 +11,48 @@ tags:
 
 # Soprano 1.1 (RLX GGUF)
 
-Packed RLX Soprano 1.1 runnable GGUF (`soprano.gguf`, format `rlx-soprano-gguf-v1`). Not community LM-only Q4 GGUF.
+Single runnable `soprano.gguf` (`rlx-soprano-gguf-v1`): tokenizer + backbone + Vocos decoder.
 
-**Kind:** RLX-native weight bundle (not a plain upstream mirror).
+| Field | Value |
+|---|---|
+| **Hub id** | [`eugenehp/soprano`](https://huggingface.co/eugenehp/soprano) |
+| **Kind** | RLX-native weight bundle (graphs + sidecars ready for `rlx-*` crates). |
+| **RLX crate** | [`rlx-soprano`](https://github.com/MIT-RLX/rlx-models/tree/main/crates/rlx-soprano) |
+| **Upstream** | https://huggingface.co/KevinAHM/soprano-1.1-onnx |
 
-**Suggested Hub repo:** `eugenehp/soprano`
+## Quick start
 
-**Upstream:** https://huggingface.co/KevinAHM/soprano-1.1-onnx
+```bash
+hf download eugenehp/soprano soprano.gguf --local-dir weights/tts/soprano
+just fetch-soprano && just soprano-demo
+```
+
+## Primary files (use these)
 
-**RLX crate:** [`rlx-soprano`](https://github.com/MIT-RLX/rlx-models/tree/main/crates/rlx-soprano)
+- `soprano.gguf` — 422.4 MiB
 
 ## Contents
 
-`soprano.gguf` — pack with `just export-soprano-gguf`.
+`soprano.gguf` only. Pack locally with `just export-soprano-gguf`.
+
+## Do not use as the main runtime pack
+
+These files may be present for historical / staging reasons but are **not** the supported RLX load path:
+
+- `Soprano-1.1-80M.Q4_K_M.gguf`
+
+Community `*.f16.gguf` / LM-only Q4 packs are format wraps — they are not drop-in replacements for the RLX primary file above.
+
+## Note
+
+`Soprano-1.1-80M.Q4_K_M.gguf` is a community LM-only pack and is **not** loadable by `rlx-soprano`.
 
 ## Run with RLX
 
-From [rlx-models](https://github.com/MIT-RLX/rlx-models) with this directory as the model path:
+Clone [rlx-models](https://github.com/MIT-RLX/rlx-models), place this repo under `weights/tts/soprano` (or pass the path explicitly), then:
 
 ```bash
-cargo run -p rlx-soprano --release -- --model-dir . --text "Hi." --output /tmp/soprano.wav
+just fetch-soprano && just soprano-demo
 ```
 
 ## License
@@ -39,6 +61,6 @@ Apache License 2.0 — see `LICENSE`. Inherit upstream terms when redistributing
 
 Original weights and authorship: https://huggingface.co/KevinAHM/soprano-1.1-onnx
 
-## Staging note
+## Maintenance
 
-Prepared from the local `weights/` tree in [rlx-models](https://github.com/MIT-RLX/rlx-models) for a future standalone Hub upload. Prefer fetching upstream when this is only a redistrib.
+Cards and LFS attrs are regenerated from the local `weights/` tree in [rlx-models](https://github.com/MIT-RLX/rlx-models) via `python3 scripts/prepare_weights_hf.py`.