### Install Chatterbox TTS

Source: https://github.com/resemble-ai/chatterbox/blob/master/README.md

Install the Chatterbox TTS library using pip. For development, install from source after cloning the repository.

```shell
pip install chatterbox-tts
```

```shell
# conda create -yn chatterbox python=3.11
# conda activate chatterbox

git clone https://github.com/resemble-ai/chatterbox.git
cd chatterbox
pip install -e .
```

--------------------------------

### T3Cond Usage Example

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/types.md

Demonstrates how to instantiate and use the T3Cond dataclass, including moving it to a CUDA device and saving/loading its state.

```python
import torch
from chatterbox.models.t3.modules.cond_enc import T3Cond

speaker_emb = torch.randn(1, 256)
emotion = torch.tensor([[[0.6]]])
speech_tokens = torch.randint(0, 6561, (1, 150))

t3_cond = T3Cond(
    speaker_emb=speaker_emb,
    emotion_adv=emotion,
    cond_prompt_speech_tokens=speech_tokens
)

# Move to device
t3_cond = t3_cond.to(device="cuda")

# Save/load
t3_cond.save("cond.pt")
loaded = T3Cond.load("cond.pt", map_location="cuda")
```

--------------------------------

### Classifier-Free Guidance Explanation

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/core-models-api.md

Explains the setup for classifier-free guidance, requiring duplicated text tokens and a specific calculation for final logits.

```text
Classifier-Free Guidance:
- Requires text_tokens to be duplicated (batch_size=2) if cfg_weight > 0
- Second batch element is zeroed for unconditioned guidance
- Final logits: `cond + cfg_weight * (cond - uncond)`
```

--------------------------------

### AttrDict Usage Example

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/types.md

Shows how to instantiate and use AttrDict for attribute-style access to dictionary elements. This is commonly used for model outputs.

```python
from chatterbox.models.utils import AttrDict

result = AttrDict(text_logits=torch.randn(1, 10, 704), speech_logits=torch.randn(1, 20, 8194))
print(result.text_logits.shape)  # (1, 10, 704)
print(result['speech_logits'].shape)  # (1, 20, 8194)
```

--------------------------------

### EnTokenizer Constructor

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/core-models-api.md

Initializes the EnTokenizer by loading a vocabulary from a specified .json file path. It validates the presence of [START] and [STOP] tokens.

```python
def __init__(self, vocab_file_path):
```

--------------------------------

### Chatterbox TTS Workflow Example

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/README.md

Demonstrates a typical workflow for generating audio using ChatterboxTTS. This includes loading the model, preparing speaker conditionals, and generating multiple text utterances into WAV files.

```python
# Main classes
from chatterbox import ChatterboxTTS, ChatterboxVC, ChatterboxMultilingualTTS
from chatterbox.tts_turbo import ChatterboxTurboTTS

# Models
from chatterbox.models.t3 import T3
from chatterbox.models.s3gen import S3Gen
from chatterbox.models.voice_encoder import VoiceEncoder
from chatterbox.models.tokenizers import EnTokenizer, MTLTokenizer

# Types
from chatterbox.models.t3.modules.t3_config import T3Config
from chatterbox.models.t3.modules.cond_enc import T3Cond
from chatterbox.mtl_tts import SUPPORTED_LANGUAGES
```

--------------------------------

### Chatterbox Voice Conversion Workflow

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-vc-api.md

Demonstrates initializing the ChatterboxVC model and performing voice conversion for single and multiple target voices. Ensure you have the necessary audio files and PyTorch/torchaudio installed.

```python
from chatterbox.vc import ChatterboxVC
import torchaudio as ta

# Initialize voice conversion
vc = ChatterboxVC.from_pretrained(device="cuda")

# Scenario 1: Single conversion with target voice
vc.set_target_voice("target_speaker.wav")
output1 = vc.generate("source1.wav")
output2 = vc.generate("source2.wav")
output3 = vc.generate("source3.wav")

ta.save("output1.wav", output1, vc.sr)
ta.save("output2.wav", output2, vc.sr)
ta.save("output3.wav", output3, vc.sr)

# Scenario 2: Multiple target voices
sources = ["audio1.wav", "audio2.wav", "audio3.wav"]
targets = ["speaker_a.wav", "speaker_b.wav", "speaker_c.wav"]

for i, source in enumerate(sources):
    for j, target in enumerate(targets):
        output = vc.generate(source, target_voice_path=target)
        ta.save(f"converted_audio{i+1}_speaker{j+1}.wav", output, vc.sr)
```

--------------------------------

### ChatterboxTTS.from_pretrained

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-tts-api.md

Loads pre-trained model weights from Hugging Face Hub. This is the recommended way to get started with ChatterboxTTS.

```APIDOC
## ChatterboxTTS.from_pretrained

### Description
Loads pre-trained model weights from Hugging Face Hub.

### Method
`classmethod`

### Parameters
#### Path Parameters
- **device** (str) - Required - PyTorch device ("cuda", "cpu", or "mps")

### Returns
- ChatterboxTTS instance with pre-trained weights loaded

### Raises
- Falls back to "cpu" if device="mps" is unavailable on macOS

### Example
```python
import torchaudio as ta
from chatterbox.tts import ChatterboxTTS

model = ChatterboxTTS.from_pretrained(device="cuda")
```
```

--------------------------------

### Voice cloning with paralinguistic tags using Chatterbox Turbo

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-turbo-api.md

Example of generating speech with voice cloning and paralinguistic tags using the `generate` method. Ensure `torchaudio` is installed for audio saving. The `audio_prompt_path` parameter is used for voice cloning, and tags like `[chuckle]` are embedded in the text for prosody.

```python
import torchaudio as ta

# Voice cloning with paralinguistic tags
text = "Hi there, Sarah here from MochaFone calling you back [chuckle], have you got one minute to chat about the billing issue?"
wav = model.generate(
    text,
    audio_prompt_path="speaker_10s.wav",
    temperature=0.8,
    top_p=0.95,
    repetition_penalty=1.2
)
ta.save("turbo_output.wav", wav, model.sr)
```

--------------------------------

### Configure HuggingFace Environment Variables

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/configuration.md

Set HuggingFace environment variables to manage model cache and authentication. This example shows how to set the cache directory and an API token.

```bash
export HF_HOME=/data/hf_cache
export HF_TOKEN=hf_xxxxx
python script.py
```

--------------------------------

### Generate Audio with Voice Cloning

Source: https://github.com/resemble-ai/chatterbox/blob/master/README.md

Generate audio using a specified text and an audio prompt for voice cloning. This example can be used with the standard ChatterboxTTS model.

```python
import torchaudio as ta
from chatterbox.tts import ChatterboxTTS
from chatterbox.mtl_tts import ChatterboxMultilingualTTS

device = "cuda"  # or "cpu" / "mps"

# English example
model = ChatterboxTTS.from_pretrained(device=device)

text = "Ezreal and Jinx teamed up with Ahri, Yasuo, and Teemo to take down the enemy's Nexus in an epic late-game pentakill."

# If you want to synthesize with a different voice, specify the audio prompt
AUDIO_PROMPT_PATH = "YOUR_FILE.wav"
wav = model.generate(text, audio_prompt_path=AUDIO_PROMPT_PATH)
ta.save("test-2.wav", wav, model.sr)
```

--------------------------------

### Configure PyTorch Environment Variables

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/configuration.md

Configure PyTorch environment variables to control GPU usage and CPU threading. This example restricts CUDA to specific devices and sets the number of CPU threads.

```bash
# Use GPU 0 and 1 only
export CUDA_VISIBLE_DEVICES=0,1
# Use 4 CPU threads
export TORCH_NUM_THREADS=4
python script.py
```

--------------------------------

### Core Dependencies for Chatterbox AI

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/module-index.md

These are the essential libraries required for Chatterbox AI to function. Ensure these versions are installed for compatibility.

```shell
torch==2.6.0  # PyTorch (2.9.0 for Python 3.14+)
torchaudio==2.6.0  # Audio processing
transformers==5.2.0  # Hugging Face models
diffusers==0.29.0  # Diffusion utils
librosa==0.11.0  # Audio loading/processing
safetensors==0.5.3  # Fast model loading
```

--------------------------------

### Extract PerTh Watermark from Audio

Source: https://github.com/resemble-ai/chatterbox/blob/master/README.md

This script demonstrates how to load an audio file and extract the PerTh watermark using the 'perth' library. Ensure the 'perth' and 'librosa' libraries are installed.

```python
import perth
import librosa

AUDIO_PATH = "YOUR_FILE.wav"

# Load the watermarked audio
watermarked_audio, sr = librosa.load(AUDIO_PATH, sr=None)

# Initialize watermarker (same as used for embedding)
watermarker = perth.PerthImplicitWatermarker()

# Extract watermark
watermark = watermarker.get_watermark(watermarked_audio, sample_rate=sr)
print(f"Extracted watermark: {watermark}")
# Output: 0.0 (no watermark) or 1.0 (watermarked)
```

--------------------------------

### Load Pre-trained Multilingual TTS Model (v3)

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-multilingual-api.md

Loads a pre-trained multilingual TTS model from the Hugging Face Hub. Use this to quickly get started with the latest v3 model variant.

```python
from chatterbox.mtl_tts import ChatterboxMultilingualTTS

model = ChatterboxMultilingualTTS.from_pretrained(device="cuda", t3_model="v3")
```

--------------------------------

### Testing Audio File Loading with Librosa

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/errors.md

This code snippet demonstrates how to test audio file loading using librosa, which can help diagnose LibrosaError issues when preparing conditionals or generating audio with a prompt path. It includes basic error handling.

```python
import librosa

# Test audio loading
try:
    wav, sr = librosa.load("audio.wav", sr=None)
    print(f"Loaded: {len(wav)} samples at {sr} Hz")
except Exception as e:
    print(f"Audio loading failed: {e}")
    # Convert to WAV or check file integrity
```

--------------------------------

### ChatterboxVC.from_local

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-vc-api.md

Loads a voice conversion model from a local checkpoint directory.

```APIDOC
## ChatterboxVC.from_local

### Description
Loads voice conversion model from local checkpoint directory.

### Method
`classmethod`

### Parameters
#### Path Parameters
- **ckpt_dir** (str or Path) - Required - Path to checkpoint directory
- **device** (str) - Required - PyTorch device

### Returns
- ChatterboxVC instance

### Expected Files in ckpt_dir
- `s3gen.safetensors` - S3Gen decoder weights
- `conds.pt` (optional) - Built-in voice conditioning

### Example
```python
from pathlib import Path

vc = ChatterboxVC.from_local(Path("/path/to/vc_ckpt"), device="cuda")
```
```

--------------------------------

### Prepare Speaker Conditionals

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-turbo-api.md

Prepares speaker conditioning from a reference audio file. Requires audio to be at least 5 seconds long and supports optional loudness normalization and exaggeration.

```python
model.prepare_conditionals(
    "speaker_sample.wav",
    exaggeration=0.0,
    norm_loudness=True
)
```

--------------------------------

### EnTokenizer Class Definition

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/core-models-api.md

Defines the EnTokenizer class for English text tokenization using sentencepiece. It includes special token handling for [START] and [STOP] tokens.

```python
class EnTokenizer:
    """English text tokenizer with special token handling."""
```

--------------------------------

### Generate Audio with Chatterbox-Turbo

Source: https://github.com/resemble-ai/chatterbox/blob/master/README.md

Load the Chatterbox-Turbo model and generate audio from text, optionally using a reference clip for voice cloning. Requires torchaudio and torch.

```python
import torchaudio as ta
import torch
from chatterbox.tts_turbo import ChatterboxTurboTTS

# Load the Turbo model
model = ChatterboxTurboTTS.from_pretrained(device="cuda")

# Generate with Paralinguistic Tags
text = "Hi there, Sarah here from MochaFone calling you back [chuckle], have you got one minute to chat about the billing issue?"

# Generate audio (requires a reference clip for voice cloning)
wav = model.generate(text, audio_prompt_path="your_10s_ref_clip.wav")

ta.save("test-turbo.wav", wav, model.sr)
```

--------------------------------

### Get Supported Languages Dictionary

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-multilingual-api.md

Retrieves a dictionary of all language codes and their corresponding names supported by the multilingual TTS model. Useful for checking available languages before synthesis.

```python
languages = ChatterboxMultilingualTTS.get_supported_languages()
print(languages)  # {"ar": "Arabic", "da": "Danish", ...}
```

--------------------------------

### Configure S3Gen Model

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/configuration.md

Instantiate S3Gen for standard (CFM) or turbo (meanflow CFM) audio generation. The 'meanflow' parameter controls the generation approach.

```python
from chatterbox.models.s3gen import S3Gen

# Standard (10-step CFM)
s3gen = S3Gen(meanflow=False)

# Turbo (1-step meanflow CFM)
s3gen = S3Gen(meanflow=True)
```

--------------------------------

### Batch Synthesis with ChatterboxTTS

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/configuration.md

Synthesize multiple texts sequentially and concatenate the audio outputs. Ensure 'ref.wav' is available for audio prompts.

```python
import torchaudio as ta
from chatterbox.tts import ChatterboxTTS

model = ChatterboxTTS.from_pretrained(device="cuda")

texts = ["Hello world", "How are you?", "Goodbye"]
wavs = []

for text in texts:
    wav = model.generate(text, audio_prompt_path="ref.wav")
    wavs.append(wav)

# Concatenate outputs
full_audio = torch.cat(wavs, dim=1)
ta.save("output.wav", full_audio, model.sr)
```

--------------------------------

### Generate Converted Audio (One-Step)

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-vc-api.md

Perform voice conversion in a single step by providing both the source audio path and the target speaker's audio file path to the `generate` method. This method automatically sets the target voice and returns the converted audio as a PyTorch tensor at 24 kHz.

```python
import torchaudio as ta

output_wav = vc.generate(
    "source_audio.wav",
    target_voice_path="target_speaker.wav"
)
ta.save("converted.wav", output_wav, vc.sr)
```

--------------------------------

### Prepare Conditionals for ChatterboxTTS/MultilingualTTS

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/configuration.md

Use this method to prepare conditioning for ChatterboxTTS and ChatterboxMultilingualTTS. Specify the path to a reference audio file and optionally an exaggeration factor for emotion.

```python
model.prepare_conditionals(wav_fpath, exaggeration=0.5)
```

--------------------------------

### Handling ValueError for Unsupported Language ID

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/errors.md

This example shows how to fix a ValueError when an unsupported language_id is used with ChatterboxMultilingualTTS. It demonstrates checking for valid language codes and then using a correct one.

```python
from chatterbox.mtl_tts import SUPPORTED_LANGUAGES

# Check valid codes
valid_codes = list(SUPPORTED_LANGUAGES.keys())
print(valid_codes)  # ['ar', 'da', 'de', ...]

# Use valid code
model.generate("Bonjour", language_id="fr")
```

--------------------------------

### Voice Conversion Pipeline Flow

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-vc-api.md

Illustrates the step-by-step process of the voice conversion pipeline, from source audio input to the final output waveform.

```text
Source Audio (any sample rate)
    ↓
Resample to 16 kHz
    ↓
S3Tokenizer: Extract speech tokens
    ↓
S3Gen.inference(): Decode with target speaker embedding
    ↓
HiFiGAN: Convert mel-spectrogram to waveform
    ↓
Watermarking
    ↓
Output Waveform (24 kHz)
```

--------------------------------

### ChatterboxVC.from_pretrained

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-vc-api.md

Loads a pre-trained voice conversion model from Hugging Face Hub.

```APIDOC
## ChatterboxVC.from_pretrained

### Description
Loads pre-trained voice conversion model from Hugging Face Hub.

### Method
`classmethod`

### Parameters
#### Path Parameters
- **device** (str) - Required - PyTorch device ("cuda", "cpu", or "mps")

### Returns
- ChatterboxVC instance

### Example
```python
from chatterbox.vc import ChatterboxVC

vc = ChatterboxVC.from_pretrained(device="cuda")
```
```

--------------------------------

### Extract Watermark from Audio

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-turbo-api.md

Use this Python snippet to extract the Perth watermark from a WAV audio file. Ensure you have the 'perth' and 'librosa' libraries installed. The output will be 0.0 if no watermark is detected or 1.0 if it is watermarked.

```python
import perth
import librosa

watermarker = perth.PerthImplicitWatermarker()
wav, sr = librosa.load("output.wav", sr=None)
watermark = watermarker.get_watermark(wav, sample_rate=sr)
print(f"Watermark: {watermark}")  # 0.0 (none) or 1.0 (watermarked)
```

--------------------------------

### Generate Converted Audio (Two-Step)

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-vc-api.md

Convert source audio to the target speaker's voice. First, set the target voice using `set_target_voice`, then call `generate` with the source audio path. The output is a PyTorch tensor at 24 kHz.

```python
import torchaudio as ta

# Set target speaker
vc.set_target_voice("target_speaker.wav")

# Convert source audio
output_wav = vc.generate("source_audio.wav")
ta.save("converted.wav", output_wav, vc.sr)
```

--------------------------------

### Construct valid text token tensors

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/errors.md

When manually constructing token tensors, ensure they include START and STOP tokens and that token IDs are within the valid range defined by the model's configuration.

```python
import torch

# Text tokens must include START/STOP
from chatterbox.models.t3.modules.t3_config import T3Config
hp = T3Config.english_only()
print(f"START: {hp.start_text_token}, STOP: {hp.stop_text_token}")

# Valid range: 0 to text_vocab_size-1
text_tokens = torch.randint(0, hp.text_tokens_dict_size, (1, 100))
```

--------------------------------

### Import Core Models for TTS Synthesis

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/module-index.md

Import core models and configurations for TTS synthesis, including T3 models, their configurations, conditional encoders, and S3Gen models for token-to-mel conversion and waveform generation. Also includes constants for S3GEN sample rate and silence.

```python
from chatterbox.models.t3 import T3
from chatterbox.models.t3.modules.t3_config import T3Config
from chatterbox.models.t3.modules.cond_enc import T3Cond, T3CondEnc

from chatterbox.models.s3gen import S3Gen, S3Token2Mel, S3Token2Wav
from chatterbox.models.s3gen.const import S3GEN_SR, S3GEN_SIL
```

--------------------------------

### Load ChatterboxTTS from Hugging Face Hub

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-tts-api.md

Loads pre-trained model weights from Hugging Face Hub. Requires PyTorch and torchaudio. Ensure the specified device is available.

```python
import torchaudio as ta
from chatterbox.tts import ChatterboxTTS

model = ChatterboxTTS.from_pretrained(device="cuda")
```

--------------------------------

### Chatterbox TTS Initialization

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/module-index.md

This snippet shows how to load a pre-trained ChatterboxTTS model, including downloading model files and setting up the model for inference.

```python
ChatterboxTTS.from_pretrained(device="cuda")
  # hf_hub_download() → Download model files
  # load_safetensors() / torch.load()
  # Move to device, eval mode
```

--------------------------------

### Prepare Conditionals for ChatterboxTurboTTS

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/configuration.md

This method is for ChatterboxTurboTTS. It includes the reference audio path and exaggeration, with an additional option to normalize loudness.

```python
model.prepare_conditionals(
    wav_fpath,
    exaggeration=0.5,
    norm_loudness=True
)
```

--------------------------------

### Load ChatterboxVC from Local Checkpoint

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-vc-api.md

Load a voice conversion model from a local checkpoint directory. Ensure the directory contains 's3gen.safetensors' and optionally 'conds.pt'. Specify the checkpoint directory path and the PyTorch device.

```python
from pathlib import Path

vc = ChatterboxVC.from_local(Path("/path/to/vc_ckpt"), device="cuda")
```

--------------------------------

### ChatterboxTTS.from_local

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-tts-api.md

Loads model from a local checkpoint directory. Use this if you have downloaded model weights manually.

```APIDOC
## ChatterboxTTS.from_local

### Description
Loads model from a local checkpoint directory.

### Method
`classmethod`

### Parameters
#### Path Parameters
- **ckpt_dir** (str or Path) - Required - Path to checkpoint directory containing ve.safetensors, t3_cfg.safetensors, s3gen.safetensors, tokenizer.json
- **device** (str) - Required - PyTorch device ("cuda", "cpu", or "mps")

### Returns
- ChatterboxTTS instance loaded from local files

### Example
```python
from pathlib import Path
model = ChatterboxTTS.from_local(Path("/path/to/checkpoints"), device="cuda")
```
```

--------------------------------

### Import Tokenizer Models

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/module-index.md

Import tokenizer models for both English and multilingual text, as well as S3 tokenizers for speech. These are crucial for converting text or speech into a format usable by the synthesis models.

```python
from chatterbox.models.tokenizers import EnTokenizer, MTLTokenizer
from chatterbox.models.s3tokenizer import S3Tokenizer, S3_SR, S3_TOKEN_RATE
```

--------------------------------

### Use CPU for Chatterbox TTS

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/errors.md

If GPU VRAM is insufficient for the model, use the CPU as an alternative by specifying device='cpu' during model loading.

```python
# Option 1: Use CPU
model = ChatterboxTTS.from_pretrained(device="cpu")
```

--------------------------------

### Configure Voice Encoder

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/configuration.md

Initialize VoiceEncConfig for audio processing. Default parameters are typically suitable and generally do not require modification.

```python
from chatterbox.models.voice_encoder.config import VoiceEncConfig

config = VoiceEncConfig()
# config.sample_rate = 16000
# config.ve_partial_frames = 160
# config.speaker_embed_size = 256
```

--------------------------------

### ChatterboxTTS.prepare_conditionals

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-tts-api.md

Prepares speaker conditioning data from a reference audio file. This method must be called before `generate()` unless an `audio_prompt_path` is specified.

```APIDOC
## ChatterboxTTS.prepare_conditionals

### Description
Prepares speaker conditioning data from a reference audio file. Must be called before `generate()` unless `audio_prompt_path` is specified.

### Method
`def prepare_conditionals(self, wav_fpath, exaggeration=0.5)`

### Parameters
#### Path Parameters
- **wav_fpath** (str) - Required - Path to reference audio file (mono WAV recommended)
- **exaggeration** (float) - Optional - Emotion/expressiveness factor (0.0 to 1.0+)

### Behavior
- Loads and resamples reference audio to 16 kHz for speaker embedding extraction
- Extracts speaker embeddings via VoiceEncoder
- Extracts speech tokens from reference audio
- Stores conditioning in `self.conds`

### Raises
- AssertionError if audio file cannot be loaded

### Example
```python
model.prepare_conditionals("speaker_sample.wav", exaggeration=0.6)
```
```

--------------------------------

### Load ChatterboxVC from Local Checkpoint

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/configuration.md

Use this method to load the ChatterboxVC model from a local directory containing checkpoint files. Ensure the directory structure matches the expected format.

```python
ChatterboxVC.from_local(ckpt_dir, device)
```

--------------------------------

### Load ChatterboxMultilingualTTS Model from Local Checkpoints

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/configuration.md

Load a ChatterboxMultilingualTTS model from a local directory using `from_local`. Specify the checkpoint directory, PyTorch device, and optionally a T3 model variant filename.

```python
ChatterboxMultilingualTTS.from_local(ckpt_dir, device, t3_model=None)
```

--------------------------------

### ChatterboxTurboTTS Fast and Natural Configuration

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/configuration.md

This configuration for ChatterboxTurboTTS balances speed and naturalness using specific temperature, top_k, and top_p settings.

```python
model.generate(
    text,
    audio_prompt_path="ref.wav",
    temperature=0.8,
    top_k=1000,
    top_p=0.95
)
```

--------------------------------

### S3Token2Mel Constructor

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/core-models-api.md

Initializes the S3Token2Mel decoder. Use meanflow=True for single-step Turbo decoding.

```python
def __init__(self, meanflow=False):
```

--------------------------------

### Load ChatterboxTurboTTS from Hugging Face Hub

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-turbo-api.md

Loads pre-trained Turbo model weights from Hugging Face Hub. Requires PyTorch device specification.

```python
import torchaudio as ta
from chatterbox.tts_turbo import ChatterboxTurboTTS

model = ChatterboxTurboTTS.from_pretrained(device="cuda")
```

--------------------------------

### Chatterbox TTS Generation with Audio Prompt

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/module-index.md

Demonstrates generating speech using ChatterboxTTS, incorporating an audio prompt for speaker embedding and reference.

```python
ChatterboxTTS.generate(text, audio_prompt_path="ref.wav")
  # prepare_conditionals() [if audio_prompt_path provided]
  #  librosa.load(ref)
  #  VoiceEncoder.embeds_from_wavs() → speaker_emb
  #  S3Gen.embed_ref() → ref_dict
  #  Store in self.conds
  # punc_norm(text)
  # EnTokenizer.text_to_tokens() → text_tokens
  # T3.inference(text_tokens, conds) → speech_tokens
  #  Autoregressive sampling loop
  # S3Gen.inference(speech_tokens, conds) → waveform
  #  CausalConditionalCFM.forward() → mel_spectrogram
  #  HiFiGAN.inference() → waveform
  # Perth watermarking
  # Return torch.Tensor(1, num_samples) @ 24 kHz
```

--------------------------------

### T3Config Initialization

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/types.md

The T3Config class constructor allows for detailed configuration of the T3 model's text and speech tokenization, vocabulary sizes, and other behavioral parameters.

```APIDOC
## T3Config

### Description
Configuration for T3 model architecture and behavior.

### Parameters
- **text_tokens_dict_size** (int) - Optional - Size of the text token dictionary.

### Attributes
- **start_text_token** (int) - Text sequence BOS token ID
- **stop_text_token** (int) - Text sequence EOS token ID
- **text_tokens_dict_size** (int) - Text vocabulary size (704 English, 2454 multilingual)
- **max_text_tokens** (int) - Maximum input text sequence length
- **start_speech_token** (int) - Speech sequence BOS token ID
- **stop_speech_token** (int) - Speech sequence EOS token ID
- **speech_tokens_dict_size** (int) - Speech token vocabulary size
- **max_speech_tokens** (int) - Maximum generated speech sequence length
- **llama_config_name** (str) - Transformer backbone name (see LLAMA_CONFIGS)
- **input_pos_emb** (Optional[str]) - Position embedding type ("learned" or None)
- **speech_cond_prompt_len** (int) - Length of speech conditioning prompt tokens
- **encoder_type** (str) - Speaker encoder type
- **speaker_embed_size** (int) - Speaker embedding dimension
- **use_perceiver_resampler** (bool) - Apply perceiver resampler to speech prompts
- **emotion_adv** (bool) - Enable emotion/expressiveness conditioning

### Properties
- **n_channels** (int) - Hidden size from LLAMA_CONFIGS[llama_config_name]
- **is_multilingual** (bool) - True if text_tokens_dict_size == 2454
```

--------------------------------

### T3Config Class Methods

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/types.md

Provides factory methods to create T3Config instances tailored for specific language configurations.

```APIDOC
## T3Config Class Methods

### english_only

#### Description
Create configuration for English-only TTS model.

#### Method
`@classmethod
def english_only(cls) -> T3Config:`

### multilingual

#### Description
Create configuration for multilingual TTS model.

#### Method
`@classmethod
def multilingual(cls) -> T3Config:`
```

--------------------------------

### Load ChatterboxVC from Hugging Face Hub

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-vc-api.md

Use this class method to load a pre-trained voice conversion model from the Hugging Face Hub. Specify the PyTorch device for model loading.

```python
from chatterbox.vc import ChatterboxVC

vc = ChatterboxVC.from_pretrained(device="cuda")
```

--------------------------------

### Reinstall PyTorch with MPS support

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/errors.md

If MPS is not available on macOS due to PyTorch not being compiled with MPS support, reinstall PyTorch using the provided command.

```bash
# Reinstall PyTorch with MPS support
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cpu
```

--------------------------------

### Import Public API (Top-Level Exports)

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/module-index.md

Import the main Chatterbox classes directly from the top-level package. Use this for general TTS and voice conversion functionalities.

```python
from chatterbox import ChatterboxTTS, ChatterboxVC, ChatterboxMultilingualTTS
```

--------------------------------

### Optional Dependencies for Chatterbox AI

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/module-index.md

These libraries provide additional functionalities or are required for specific features like watermarking or web UI demos.

```shell
perth  # Watermarking (via git)
pykakasi==2.3.0  # Japanese text processing
spacy-pkuseg  # Chinese segmentation
omegaconf  # Configuration management
gradio==6.8.0  # Web UI for demos
pyloudnorm  # Audio loudness normalization
conformer==0.3.2  # Conformer layers
```

--------------------------------

### T3Config Constructor

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/core-models-api.md

Initializes T3Config with default values for various parameters. The text_tokens_dict_size can be adjusted for different language models.

```python
def __init__(self, text_tokens_dict_size=704):

```

--------------------------------

### Configure S3Gen for Single-Step Decoding

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-turbo-api.md

Initializes S3Gen with meanflow enabled for single-step flow matching decoding, replacing the standard 10-step iterative decoding process.

```python
s3gen = S3Gen(meanflow=True)

```

--------------------------------

### Import Utility Functions

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/module-index.md

Import utility functions, such as AttrDict, which can be helpful for managing configurations and data structures within the library.

```python
from chatterbox.models.utils import AttrDict
```

--------------------------------

### Load ChatterboxVC from Pre-trained

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/configuration.md

Use this method to load the ChatterboxVC model with pre-trained weights. Specify the PyTorch device for model execution.

```python
ChatterboxVC.from_pretrained(device)
```

--------------------------------

### Usage of Supported Languages

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/types.md

Demonstrates how to access and validate language codes using the SUPPORTED_LANGUAGES dictionary and the ChatterboxMultilingualTTS class method.

```python
from chatterbox.mtl_tts import ChatterboxMultilingualTTS, SUPPORTED_LANGUAGES

# Get all supported languages
all_langs = SUPPORTED_LANGUAGES
print(all_langs["en"])  # "English"

# Validate language
if language_id not in SUPPORTED_LANGUAGES:
    raise ValueError(f"Unsupported language: {language_id}")

# Or use the class method
langs = ChatterboxMultilingualTTS.get_supported_languages()
```

--------------------------------

### Load ChatterboxMultilingualTTS Model from Pretrained

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/configuration.md

Load a ChatterboxMultilingualTTS model from HuggingFace, specifying the PyTorch device and optionally a T3 model variant.

```python
ChatterboxMultilingualTTS.from_pretrained(device, t3_model=None)
```

--------------------------------

### Configure T3 Model Architecture

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/configuration.md

Instantiate T3Config for English-only, multilingual, or custom model architectures. Key attributes like backbone and resampler usage can be specified.

```python
from chatterbox.models.t3.modules.t3_config import T3Config

# English
hp = T3Config.english_only()  # text_tokens_dict_size=704

# Multilingual
hp = T3Config.multilingual()  # text_tokens_dict_size=2454

# Custom
hp = T3Config(text_tokens_dict_size=704)
hp.llama_config_name = "Llama_520M"
hp.emotion_adv = True
hp.use_perceiver_resampler = True
```

--------------------------------

### Load ChatterboxTurboTTS from Local Checkpoint

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-turbo-api.md

Loads model from a local checkpoint directory. Ensure all required model weights and tokenizer files are present.

```python
model = ChatterboxTurboTTS.from_local("/path/to/turbo_ckpt", device="cuda")
```

--------------------------------

### Text-to-Speech Data Flow

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/module-index.md

Illustrates the step-by-step process for generating speech from text using Chatterbox TTS. This includes loading models, preparing speaker conditionals, generating speech tokens, and decoding to a waveform.

```python
# User input
text = "Hello, how are you?"
ref_audio = "speaker.wav"

# Step 1: Load models
model = ChatterboxTTS.from_pretrained(device="cuda")

# Step 2: Extract speaker embedding
model.prepare_conditionals(ref_audio)
# → Loads ref_audio at 24 kHz
# → Resamples to 16 kHz
# → VoiceEncoder extracts 256-dim embedding
# → S3Gen extracts reference tokens/mels
# → Stores in model.conds

# Step 3: Generate speech tokens
wav = model.generate(text)
# → punc_norm(text) → "Hello, how are you?."
# → EnTokenizer → [255, ..., 0]  (START...STOP tokens)
# → T3.inference(text_tokens, speaker_emb, emotion)
#   → Autoregressive sampling with CFG
#   → Returns speech tokens [6561, ..., 6562]
# → drop_invalid_tokens() → valid range [0-6560]

# Step 4: Decode to waveform
# → S3Gen.inference(speech_tokens, speaker_emb, mels)
#   → CausalConditionalCFM(n_steps=10) → mel-spectrogram
#   → HiFiGAN → waveform at 24 kHz
# → Perth watermarking

# Step 5: Return
return torch.Tensor shape (1, num_samples)
```

--------------------------------

### Prepare Speaker Conditionals

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/chatterbox-tts-api.md

Prepares speaker conditioning data from a reference audio file. This method extracts speaker embeddings and speech tokens, storing them in `self.conds`. It must be called before `generate()` unless an audio prompt is provided.

```python
model.prepare_conditionals("speaker_sample.wav", exaggeration=0.6)
```

--------------------------------

### ChatterboxTTS General Purpose Configuration

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/configuration.md

Use this configuration for general-purpose speech generation with ChatterboxTTS. It requires a reference audio file for voice cloning.

```python
model.generate(text, audio_prompt_path="ref.wav")
```

--------------------------------

### Handle empty text input for generation

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/errors.md

When the `generate` method is called with empty text, it defaults to synthesizing a predefined message. This is not an error but a logged behavior.

```python
model.generate("")
# Returns synthesis of: "You need to add some text for me to talk."
```

--------------------------------

### Configure HuggingFace Token and Load Multilingual Model

Source: https://github.com/resemble-ai/chatterbox/blob/master/_autodocs/configuration.md

Set the `HF_TOKEN` environment variable if needed for private models, then load a ChatterboxMultilingualTTS model with a specific T3 variant using `from_pretrained`.

```python
import os
os.environ["HF_TOKEN"] = "hf_..."  # If needed
model = ChatterboxMultilingualTTS.from_pretrained(device="cuda", t3_model="v3")
```