| --- |
| license: mit |
| base_model: ResembleAI/chatterbox-turbo |
| pipeline_tag: text-to-speech |
| language: |
| - en |
| tags: |
| - codec.cpp |
| - gguf |
| - text-to-speech |
| - tts |
| - chatterbox |
| - chatterbox-turbo |
| - voice-cloning |
| --- |
| |
| # Chatterbox Turbo — GGUF |
|
|
| [ResembleAI's Chatterbox Turbo](https://huggingface.co/ResembleAI/chatterbox-turbo): fast English TTS with voice cloning and paralinguistic tags such as `[laugh]`. |
|
|
| Two files make one model, as with llama.cpp's multimodal projectors: the **model** file is the text-to-speech LM backbone, run by [llama.cpp](https://github.com/ggml-org/llama.cpp); the **codec** file holds the audio side (decoder / vocoder, speaker encoders and the adaptor between the two), run by [codec.cpp](https://github.com/mybigday/codec.cpp). The runtimes below wire the two graphs together, on CPU or GPU (CUDA, Vulkan, Metal), fully offline. |
|
|
| ## Files |
|
|
| Every run needs **one model file + one codec file** from this repo. |
|
|
| | | `--backbone` | `--model` (codec) | Total | |
| |---|---|---|---| |
| | Recommended | `chatterbox-turbo-t3-q8_0.gguf` | `chatterbox-turbo-codec-q8_0.gguf` | 768 MB | |
| | Smallest | `chatterbox-turbo-t3-q4_k_m.gguf` | `chatterbox-turbo-codec-q4_k_m.gguf` | 499 MB | |
| | Best quality | `chatterbox-turbo-t3-f16.gguf` | `chatterbox-turbo-codec-f16.gguf` | 1.4 GB | |
|
|
| <details> |
| <summary>Other files</summary> |
|
|
| | File | Size | |
| |---|---| |
| | `chatterbox-turbo-codec-f32.gguf` | 1.3 GB | |
| | `chatterbox-turbo-codec-q5_k_m.gguf` | 260 MB | |
|
|
| </details> |
|
|
|
|
| ## Command line (codec.cpp) |
|
|
| With [codec.cpp](https://github.com/mybigday/codec.cpp)'s `tts-cli` ([build it](https://github.com/mybigday/codec.cpp#text-to-speech); it bundles llama.cpp), then: |
|
|
| ```bash |
| hf download BricksDisplay/Chatterbox-Turbo-GGUF chatterbox-turbo-t3-q8_0.gguf chatterbox-turbo-codec-q8_0.gguf --local-dir Chatterbox-Turbo |
| |
| ./build/tts-cli synthesize --backbone Chatterbox-Turbo/chatterbox-turbo-t3-q8_0.gguf --model Chatterbox-Turbo/chatterbox-turbo-codec-q8_0.gguf \ |
| --text "Hello, this is Chatterbox Turbo. [laugh]" --output out.wav |
| ``` |
|
|
| Clone a voice from a few seconds of clean speech: |
|
|
| ```bash |
| ./build/tts-cli synthesize ... --ref-audio my_voice.wav --text "Hello there." --output out.wav |
| ``` |
|
|
| 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). |
|
|
|
|
| ## Python |
|
|
| The `codec_cpp` package runs the same pipeline (it builds codec.cpp with its |
| bundled llama.cpp, so it needs CMake and a C++ compiler): |
|
|
| ```bash |
| pip install "codec-cpp @ git+https://github.com/mybigday/codec.cpp" huggingface_hub soundfile |
| ``` |
|
|
| ```python |
| import codec_cpp, soundfile |
| from huggingface_hub import hf_hub_download |
| |
| tts = codec_cpp.TTS(hf_hub_download("BricksDisplay/Chatterbox-Turbo-GGUF", "chatterbox-turbo-t3-q8_0.gguf"), |
| hf_hub_download("BricksDisplay/Chatterbox-Turbo-GGUF", "chatterbox-turbo-codec-q8_0.gguf")) |
| audio, sr = tts.synthesize("Hello, this is Chatterbox Turbo. [laugh]") |
| soundfile.write("out.wav", audio, sr) |
| ``` |
|
|
| `tts.voices()` lists the builtin voices; `ref_audio=` clones a voice where the |
| model supports it; `tts.stream(text)` yields audio as it is generated. More in |
| the [Python docs](https://github.com/mybigday/codec.cpp/tree/main/python). |
|
|
|
|
| ## React Native (llama.rn) |
|
|
| [llama.rn](https://github.com/mybigday/llama.rn) loads the same two files on iOS and Android: |
|
|
| ```ts |
| const ctx = await initLlama({ model: 'chatterbox-turbo-t3-q8_0.gguf', embedding: true }) |
| await ctx.initVocoder({ path: 'chatterbox-turbo-codec-q8_0.gguf' }) |
| const { prompt, grammar, embedding, flow } = await ctx.getFormattedAudioCompletion({ |
| prompt: 'Hello world', |
| }) |
| const result = await ctx.completion({ prompt, grammar, embedding }) |
| const pcm = flow === 'continuous_embd' |
| ? await ctx.decodeAudioEmbeddings(result.embeddings, result.embedding_dim) |
| : await ctx.decodeAudioTokens(result.audio_tokens) |
| ``` |
|
|
| Voice cloning, saved voices and per-model notes: [llama.rn TTS docs](https://github.com/mybigday/llama.rn#text-to-speech-tts). |
|
|
|
|
| ## Sampling |
|
|
| The model files carry the recommended sampling as llama.cpp's |
| `general.sampling.*` metadata, the settings of the original `ChatterboxTurboTTS.generate()`; |
| `tts-cli`, `tts-server`, llama.rn and any llama.cpp host apply them unless |
| you set your own. |
|
|
| | Setting | Value | `tts-cli` flag | |
| |---|---|---| |
| | temperature | 0.8 | `--temp 0.8` | |
| | top-k | 1000 | `--top-k 1000` | |
| | top-p | 0.95 | `--top-p 0.95` | |
| | min-p | 0 (off) | `--min-p 0.0` | |
| | repetition penalty | 1.2 | `--repeat-penalty 1.2` | |
| | repetition window | 1024 (every generated token) | `--repeat-last-n 1024` | |
| | sampler order | temperature → top-k → top-p → penalties | `--samplers "temperature;top_k;top_p;penalties"` | |
|
|
| The order is the original's (Hugging Face warpers: temperature, top-k, top-p, |
| then the repetition penalty). |
|
|
| ## Voices |
|
|
| - Builtin voice: `default`. |
| - Voice cloning: `--ref-audio` with any short, clean clip. Save it with |
| `--save-speaker` to reuse it without the clip. |
|
|
| ## License |
|
|
| `mit`, the same as the [original model](https://huggingface.co/ResembleAI/chatterbox-turbo). |
|
|
