README: user-facing model card (files, run with codec.cpp tts-cli, license as upstream)

README.md

@@ -1,117 +1,100 @@
 ---
-license: other
+license: apache-2.0
+base_model: neuphonic/neutts-air
+pipeline_tag: text-to-speech
 language:
 - en
 tags:
+- codec.cpp
 - gguf
+- text-to-speech
 - tts
 - neutts
-- text-to-speech
-base_model: neuphonic/neutts-nano
+- voice-cloning
 ---
 
-# NeuTTS Nano GGUF
+# NeuTTS Air — GGUF
 
-GGUF conversions of [Neuphonic's NeuTTS Nano](https://huggingface.co/neuphonic/neutts-nano) — a compact (~228 M params, ~117 M active) on-device TTS LM with instant voice cloning.
+[Neuphonic's NeuTTS Air](https://huggingface.co/neuphonic/neutts-air): compact English TTS with builtin voices and voice cloning.
 
-The stack is split so each runtime owns the part it's good at:
-
-- **LLM-part** — text-and-reference-codes to speech token IDs, stock `llama` arch, runs in **llama.cpp**.
-- **Codec-part** — speech token IDs to/from 24 kHz PCM via [NeuCodec](https://huggingface.co/neuphonic/neucodec), runs in [codec.cpp](https://github.com/mybigday/codec.cpp).
+Runs offline with [codec.cpp](https://github.com/mybigday/codec.cpp) on CPU or GPU (CUDA, Vulkan, Metal).
 
 ## Files
 
-### LLM-part (llama arch, vocab 194256, RoPE θ=500000 + linear scaling x32)
-
-`neutts-nano-<quant>.gguf`
-
-| File              | Size    |
-| ----------------- | ------- |
-| `neutts-nano-f32.gguf`    | 925 MB  |
-| `neutts-nano-f16.gguf`    | 467 MB  |
-| `neutts-nano-bf16.gguf`   | 467 MB  |
-| `neutts-nano-q8_0.gguf`   | 253 MB  |
-| `neutts-nano-q6_k.gguf`   | 245 MB  |
-| `neutts-nano-q5_k_m.gguf` | 217 MB  |
-| `neutts-nano-q5_k_s.gguf` | 214 MB  |
-| `neutts-nano-q5_1.gguf`   | 216 MB  |
-| `neutts-nano-q5_0.gguf`   | 209 MB  |
-| `neutts-nano-q4_k_m.gguf` | 210 MB  |
-| `neutts-nano-q4_k_s.gguf` | 205 MB  |
-| `neutts-nano-q4_1.gguf`   | 202 MB  |
-| `neutts-nano-q4_0.gguf`   | 194 MB  |
-| `neutts-nano-q3_k_l.gguf` | 200 MB  |
-| `neutts-nano-q3_k_m.gguf` | 196 MB  |
-| `neutts-nano-q3_k_s.gguf` | 190 MB  |
-| `neutts-nano-q2_k.gguf`   | 190 MB  |
-
-### Codec-part (distill NeuCodec, `distill_neucodec` arch, 65536 codebook, 24 kHz, 50 Hz token rate)
-
-`codec-<quant>.gguf`
-
-| File                | Size    |
-| ------------------- | ------- |
-| `codec-f32.gguf` | 1050 MB |
-| `codec-f16.gguf` | 526 MB |
-| `codec-q8_0.gguf` | 381 MB |
-| `codec-q5_k_m.gguf` | 323 MB |
-| `codec-q4_k_m.gguf` | 303 MB |
+Every run needs **one model file + one codec file** from this repo.
 
-[neuphonic/distill-neucodec](https://huggingface.co/neuphonic/distill-neucodec): the decoder is
-bit-identical to NeuCodec's; the distill encoder (SQCodec + DistilHuBERT) gives codec.cpp an encode
-path, so reference voices can be cloned from audio (`codec_speaker_from_audio`, any sample rate).
-Every precision was checked end to end (Whisper CER 0 on a test sentence).
+| | `--backbone` | `--model` (codec) | Total |
+|---|---|---|---|
+| Recommended | `neutts-air-q8_0.gguf` | `codec-q8_0.gguf` | 1.2 GB |
+| Smallest | `neutts-air-q4_k_m.gguf` | `codec-q4_k_m.gguf` | 900 MB |
+| Best quality | `neutts-air-f16.gguf` | `codec-f16.gguf` | 2.0 GB |
 
-## Voices
+<details>
+<summary>Other files</summary>
+
+| File | Size |
+|---|---|
+| `codec-f32.gguf` | 1.0 GB |
+| `codec-q5_k_m.gguf` | 323 MB |
+| `neutts-air-bf16.gguf` | 1.5 GB |
+| `neutts-air-f32.gguf` | 3.0 GB |
+| `neutts-air-q2_k.gguf` | 513 MB |
+| `neutts-air-q3_k_l.gguf` | 543 MB |
+| `neutts-air-q3_k_m.gguf` | 530 MB |
+| `neutts-air-q3_k_s.gguf` | 512 MB |
+| `neutts-air-q4_0.gguf` | 526 MB |
+| `neutts-air-q4_1.gguf` | 561 MB |
+| `neutts-air-q4_k_s.gguf` | 584 MB |
+| `neutts-air-q5_0.gguf` | 595 MB |
+| `neutts-air-q5_1.gguf` | 630 MB |
+| `neutts-air-q5_k_m.gguf` | 631 MB |
+| `neutts-air-q5_k_s.gguf` | 623 MB |
+| `neutts-air-q6_k.gguf` | 777 MB |
 
-The codec GGUF carries upstream's `samples/` voices as builtin codec speakers:
+</details>
 
-- `ref_codes` (I32 tensor `spk.<name>.ref_codes`): NeuCodec tokens of the reference clip
-  (upstream's `.pt`);
-- `ref_text` (metadata `distill_neucodec.spk.<name>.ref_text`): its transcript phonemized as
-  neutts does (espeak-ng, stress + punctuation, the voice's language).
 
-Read them with `codec_get_speaker` / `codec_speaker_get_slot` / `codec_speaker_ref_text`. Use a voice
-in the backbone's language.
+## Run
 
-| Voice | Language | ref codes |
-|---|---|---|
-| `jo` (default) | en-us | 653 |
-| `dave` | en-us | 372 |
-| `emily` | en-us | 402 |
-| `paul` | en-us | 286 |
-| `sophie` | en-us | 175 |
-| `steven` | en-us | 258 |
-| `mateo` | es | 318 |
-| `greta` | de | 199 |
-| `juliette` | fr-fr | 405 |
+With [codec.cpp](https://github.com/mybigday/codec.cpp)'s `tts-cli` ([build it](https://github.com/mybigday/codec.cpp#text-to-speech), then):
 
 ```bash
-tts-cli synthesize --backbone <llm>.gguf --model codec-f16.gguf --voice dave \
+hf download BricksDisplay/NeuTTS-Air-GGUF neutts-air-q8_0.gguf codec-q8_0.gguf --local-dir NeuTTS-Air
+
+./build/tts-cli synthesize --backbone NeuTTS-Air/neutts-air-q8_0.gguf --model NeuTTS-Air/codec-q8_0.gguf \
+    --voice dave \
     --text "ðə bˈɜːtʃ kənˈuː slˈɪd ɔnðə smˈuːð plˈæŋks." --output out.wav
-tts-cli synthesize ... --ref-audio ref.wav --ref-text "<phonemes>" --save-speaker my_voice.gguf
 ```
 
-See [docs/models/neutts.md](https://github.com/mybigday/codec.cpp/blob/main/docs/models/neutts.md).
+Clone a voice (the transcript is given in phonemes too):
 
-## Prompt format
+```bash
+./build/tts-cli synthesize ... --ref-audio my_voice.wav --ref-text "<phonemes of the clip>" \
+    --save-speaker my_voice.gguf --text "<phonemes>" --output out.wav
+```
 
-The reference flow (from `neuphonic/neutts`):
+All `tts-cli` options (voices, voice cloning, sampling, GPU) are described in the [codec.cpp README](https://github.com/mybigday/codec.cpp#text-to-speech).
 
-```
-user: Convert the text to speech:<|TEXT_PROMPT_START|>{ref_phones} {input_phones}<|TEXT_PROMPT_END|>
-assistant:<|SPEECH_GENERATION_START|>{ref_codes_as_speech_tokens}
+
+## Input text
+
+The model reads **IPA phonemes**, not plain text. Convert your text with
+espeak-ng (stress marks and punctuation kept), e.g. with Python's `phonemizer`:
+
+```python
+from phonemizer.backend import EspeakBackend
+g2p = EspeakBackend("en-us", preserve_punctuation=True, with_stress=True)
+print(g2p.phonemize(["The birch canoe slid on the smooth planks."])[0])
 ```
 
-- `{ref_phones}` / `{input_phones}` — IPA-phonemized text (espeak-ng / phonemizer).
-- `{ref_codes_as_speech_tokens}` — concatenation of `<|speech_N|>` strings for each NeuCodec token of a reference clip.
-- Generation continues with more `<|speech_N|>` tokens until `<|SPEECH_GENERATION_END|>`.
+Or build codec.cpp with `-DCODEC_TTS_ESPEAK=ON` and pass English text directly.
+
+## Voices
 
-Speech-token vocab range: `<|speech_0|>` = id 128262 … `<|speech_65535|>` = id 193797.
-Stop token: `<|SPEECH_GENERATION_END|>` = id 128261.
+Builtin: `jo` (default), `dave`, `emily`, `paul`, `sophie`, `steven` (English),
+plus `mateo` (Spanish), `greta` (German), `juliette` (French) for Neuphonic's
+other-language models. Voice cloning: `--ref-audio` with `--ref-text`.
 
-## Notes
+## License
 
-- Reference encoding (audio → speech tokens): `codec_speaker_from_audio` / `tts-cli --ref-audio` with this codec.
-- Phonemization isn't part of the GGUF — apply espeak-ng (or equivalent) on the host before tokenizing prompts; raw English text will be off-distribution.
-- Source weights: `neuphonic/neutts-nano` (LLM) and `neuphonic/distill-neucodec` (codec), voices from `neuphonic/neutts` `samples/`.
+`apache-2.0`, the same as the [original model](https://huggingface.co/neuphonic/neutts-air).