README.md

---
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}
}
```