Add model card

README.md

@@ -0,0 +1,100 @@
+---
+license: apache-2.0
+language:
+  - en
+tags:
+  - audio
+  - speech
+  - text-to-speech
+  - voice-cloning
+  - neucodec
+library_name: safetensors
+base_model: neuphonic/neucodec
+inference: false
+---
+
+# NeuCodec Decoder (safetensors weights)
+
+These are the [NeuCodec](https://huggingface.co/neuphonic/neucodec) decoder weights, extracted to `safetensors` for use with a pure-Rust CPU decoder (ndarray + rustfft) — no native ONNX runtime, no PyTorch at inference.
+
+The decoder converts the discrete speech codes produced by the NeuTTS backbone back into a 24 kHz audio waveform, completing the zero-shot voice cloning pipeline.
+
+This artifact exists to enable voice cloning in [Ragtag](https://ragtag-ai.app), a local-first desktop AI application, under strict architectural constraints: no native ONNX runtime (no `onnxruntime` / `ort`), no GPL dependencies. The companion encoder is [ragtag-ai/neucodec-encoder-rten](https://huggingface.co/ragtag-ai/neucodec-encoder-rten).
+
+## Model details
+
+- **Source model:** [neuphonic/neucodec](https://huggingface.co/neuphonic/neucodec) (decoder portion only)
+- **Format:** `safetensors` (extracted from the original `pytorch_model.bin`)
+- **Runtime:** a pure-Rust CPU decoder (ndarray + rustfft) — the implementation in [neutts-rs](https://github.com/eugenehp/neutts-rs), vendored into Ragtag
+- **Precision:** fp32
+- **File size:** approximately 880 MB
+- **Input:** NeuCodec speech codes (50 per second of audio)
+- **Output:** 24 kHz mono audio waveform
+
+## Provenance and extraction process
+
+Upstream distributes the decoder only as ONNX ([neuphonic/neucodec-onnx-decoder](https://huggingface.co/neuphonic/neucodec-onnx-decoder)); the pure-Rust decoder loads `safetensors`. These weights were extracted from the original PyTorch model:
+
+1. **PyTorch source:** `pytorch_model.bin` from [neuphonic/neucodec](https://huggingface.co/neuphonic/neucodec)
+2. **Extraction:** the decoder sub-graph (VocosBackbone: FSQ projection, conv embed, ResNet + RoPE transformer blocks, ISTFT head) is filtered out and written to `safetensors` (script: `convert_weights.py`, or the dependency-free `convert_weights_nopytorch.py`, in the Ragtag repo).
+
+No weights are modified — this is a format conversion only.
+
+## Quality verification
+
+The pure-Rust decoder was verified against the reference implementations:
+
+- **Decoder parity:** 0.99 correlation with the upstream Rust decoder on identical codes
+- **End-to-end:** codes encoded from real audio, decoded through this path, produce an intelligible reconstruction of the speaker (ASR-confirmed)
+
+NeuCodec is a generative (vocoder) decoder, so two valid implementations produce intelligible but not phase-identical waveforms; intelligibility, not waveform correlation, is the meaningful check.
+
+## Usage
+
+This is not a standalone TTS system. It is the decoder stage of Ragtag's clone pipeline, used together with:
+
+- The encoder [ragtag-ai/neucodec-encoder-rten](https://huggingface.co/ragtag-ai/neucodec-encoder-rten)
+- A NeuTTS backbone (e.g. [neuphonic/neutts-nano-q4-gguf](https://huggingface.co/neuphonic/neutts-nano-q4-gguf))
+- A G2P frontend producing IPA phonemes (Ragtag uses piper-plus-g2p)
+
+The decoder runs on CPU.
+
+## Licence and attribution
+
+Licensed under **Apache License 2.0**, derived from the original NeuCodec which is also Apache 2.0 licensed. Please retain attribution to the original authors:
+
+```
+NeuCodec by Neuphonic
+https://huggingface.co/neuphonic/neucodec
+Licensed under Apache 2.0
+```
+
+The safetensors extraction is contributed by Ragtag / Captivated Ltd, also under Apache 2.0.
+
+## Related resources
+
+- Original NeuCodec: [neuphonic/neucodec](https://huggingface.co/neuphonic/neucodec)
+- Companion encoder: [ragtag-ai/neucodec-encoder-rten](https://huggingface.co/ragtag-ai/neucodec-encoder-rten)
+- NeuTTS backbone: [neuphonic/neutts-air](https://huggingface.co/neuphonic/neutts-air)
+- neutts-rs (Rust port reference): [github.com/eugenehp/neutts-rs](https://github.com/eugenehp/neutts-rs)
+- Ragtag: [ragtag-ai.app](https://ragtag-ai.app)
+
+## Citation
+
+```bibtex
+@misc{neucodec2024,
+  author = {Neuphonic},
+  title = {NeuCodec},
+  year = {2024},
+  publisher = {Hugging Face},
+  url = {https://huggingface.co/neuphonic/neucodec}
+}
+
+@misc{neucodec-decoder-safetensors,
+  author = {Mallett, Leon},
+  title = {NeuCodec Decoder (safetensors weights)},
+  year = {2026},
+  publisher = {Hugging Face},
+  url = {https://huggingface.co/ragtag-ai/neucodec-decoder}
+}
+```