### Install chatterbox-streaming

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/README.md

Install the chatterbox-streaming library using pip.

```bash
pip install chatterbox-streaming
```

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

### Example: Text to Tokens Conversion

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/api-reference-utilities.md

Demonstrates how to create an instance of EnTokenizer and convert a sample text string into token IDs.

```python
tokenizer = EnTokenizer("tokenizer.json")
tokens = tokenizer.text_to_tokens("Hello world")
# Returns: tensor([[ id1, id2, ... ]])
```

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

### Install Chatterbox Streaming

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/quick-start.md

Install the Chatterbox Streaming library using pip. Ensure you are using Python 3.10 or higher and have a virtual environment activated.

```bash
python3.10 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install chatterbox-streaming
```

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

### Python Logging Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/api-reference-utilities.md

Demonstrates the usage of Python's standard logging module for warnings. Useful for tracking potential issues during execution.

```python
import logging

logger = logging.getLogger(__name__)
logger.warning("Reference mel length is not equal to 2 * reference token length")
```

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

### Voice Conversion Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/MANIFEST.md

Provides an example of using the ChatterboxVC class for voice conversion. This involves setting a target voice and converting source audio to that voice.

```python
from chatterbox import ChatterboxVC

# Initialize the VC model
vc = ChatterboxVC.from_pretrained("vc_models/conversion_model")

# Load source audio and target voice sample
source_audio, sr = soundfile.read("source_audio.wav")
target_voice, sr = soundfile.read("target_voice.wav")

# Set the target voice for conversion
vc.set_target_voice(target_voice)

# Perform voice conversion
converted_audio = vc.generate(source_audio)

# Save the converted audio (optional)
import soundfile as sf
sf.write("converted_output.wav", converted_audio, vc.sr)

```

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

### Real-time Streaming Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/MANIFEST.md

Shows how to use the `generate_stream()` method for real-time, streaming text-to-speech synthesis. This is useful for applications requiring low latency.

```python
from chatterbox import ChatterboxTTS

# Initialize the TTS model for streaming
tts = ChatterboxTTS.from_pretrained("tts_models/en/ljspeech/tacotron2-v1")

# Stream speech synthesis
text = "Streaming audio in real time."
stream = tts.generate_stream(text)

# Process the audio stream (e.g., play it back)
for chunk in stream:
    # Play audio chunk
    pass

```

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

### Configuration from Environment Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/MANIFEST.md

Shows how to configure Chatterbox Streaming components by reading settings from environment variables. This is a common practice for managing application configurations in different deployment environments.

```python
# Example for configuration from environment variables (conceptual)
# This would involve reading environment variables to set parameters like device, model paths, etc.
# import os
# from chatterbox import ChatterboxTTS
# 
# device = os.environ.get("CHATTERBOX_DEVICE", "cpu")
# model_path = os.environ.get("CHATTERBOX_MODEL_PATH", "default_model")
# 
# tts = ChatterboxTTS.from_pretrained(model_path, device=device)

```

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

### ChatterboxVC.from_pretrained

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/api-reference-chatterboxvc.md

Loads a pre-trained voice conversion model from the Hugging Face Hub. This is the recommended way to get started with ChatterboxVC.

```APIDOC
## ChatterboxVC.from_pretrained

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

### Method
`classmethod`

### Signature
`from_pretrained(device: str) -> ChatterboxVC`

### Parameters
#### Path Parameters
- **device** (str) - Required - Device placement: "cuda", "cpu", or "mps". Falls back to CPU if MPS unavailable on macOS.

### Returns
- **ChatterboxVC** - `ChatterboxVC` instance with S3Gen model loaded

### Raises
- Model loading may fail if weights cannot be downloaded from HF Hub
- MPS device availability is checked; falls back to CPU on unsupported systems

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

model = ChatterboxVC.from_pretrained(device="cuda")
# Now ready for voice conversion
```
```

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

### Streaming with Progress Tracking Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/MANIFEST.md

Demonstrates how to track the progress of real-time streaming speech synthesis. This is valuable for providing user feedback, such as a progress bar or status updates, during long syntheses.

```python
# Example for streaming with progress tracking (conceptual)
# This would involve monitoring the output of generate_stream() and calculating progress.
# from chatterbox import ChatterboxTTS
# 
# tts = ChatterboxTTS.from_pretrained("tts_models/en/ljspeech/tacotron2-v1")
# text = "Tracking progress during streaming."
# total_length = len(text) # Approximate length for progress calculation
# synthesized_chars = 0
# 
# stream = tts.generate_stream(text)
# for chunk in stream:
#     # Process audio chunk
#     # Update synthesized_chars based on chunk processing
#     progress = (synthesized_chars / total_length) * 100
#     print(f"Progress: {progress:.2f}%")

```

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

### Basic Text-to-Speech Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/MANIFEST.md

Demonstrates the fundamental usage of the ChatterboxTTS class for standard text-to-speech synthesis. Ensure the ChatterboxTTS class is imported and initialized.

```python
from chatterbox import ChatterboxTTS

# Initialize the TTS model
tts = ChatterboxTTS.from_pretrained("tts_models/en/ljspeech/tacotron2-v1")

# Synthesize speech from text
text = "Hello, world! This is a test."
audio = tts.generate(text)

# Save the audio to a file (optional)
import soundfile as sf
sf.write("output.wav", audio, tts.sr)

```

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

### Flask API Server Integration Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/MANIFEST.md

Shows how to integrate Chatterbox Streaming into a Flask web application to provide text-to-speech or voice conversion as a service. This example would typically involve setting up API endpoints.

```python
# Example for Flask API server integration (conceptual)
# This would involve creating Flask routes to handle requests and use Chatterbox models.
# from flask import Flask, request, jsonify, Response
# from chatterbox import ChatterboxTTS
# 
# app = Flask(__name__)
# tts = ChatterboxTTS.from_pretrained("tts_models/en/ljspeech/tacotron2-v1")
# 
# @app.route('/synthesize', methods=['POST'])
# def synthesize():
#     data = request.get_json()
#     text = data.get('text')
#     if not text:
#         return jsonify({'error': 'No text provided'}), 400
#     
#     audio_data = tts.generate(text)
#     # Return audio data as a response
#     return Response(audio_data.tobytes(), mimetype='audio/wav')
# 
# if __name__ == '__main__':
#     app.run(debug=True)

```

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

### Install Chatterbox TTS

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/README.md

Install the chatterbox-streaming package using pip. Ensure you are using Python 3.10 and have a virtual environment activated.

```bash
python3.10 -m venv .venv
source .venv/bin/activate
pip install chatterbox-streaming
```

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

### High-Quality Streaming Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/MANIFEST.md

Demonstrates how to achieve high-quality audio output while streaming speech synthesis. This may involve specific model choices or post-processing steps.

```python
# Example for high-quality streaming (details depend on specific model and parameters)
# This might involve using generate_stream() with higher quality settings or specific decoders.
# from chatterbox import ChatterboxTTS
# tts = ChatterboxTTS.from_pretrained("high_quality_streaming_model")
# text = "Crystal clear audio."
# audio_stream = tts.generate_stream(text, quality="high") # Hypothetical parameter

```

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

### Batch Voice Conversion Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/MANIFEST.md

Illustrates how to perform voice conversion on multiple audio files in a batch. This is useful for processing large datasets or applying voice conversion to many clips efficiently.

```python
from chatterbox import ChatterboxVC
import glob

# Initialize the VC model
vc = ChatterboxVC.from_pretrained("vc_models/conversion_model")

# Load target voice sample
target_voice, sr = soundfile.read("target_voice.wav")
vc.set_target_voice(target_voice)

# Process all WAV files in a directory
source_files = glob.glob("source_audios/*.wav")
for source_file in source_files:
    source_audio, sr = soundfile.read(source_file)
    converted_audio = vc.generate(source_audio)
    output_file = f"converted_audios/{os.path.basename(source_file)}"
    sf.write(output_file, converted_audio, vc.sr)

```

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

### Build Chatterbox TTS for Development

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/README.md

Clone the repository and install the package in editable mode for development. This allows you to make changes and test them directly.

```bash
git clone https://github.com/davidbrowne17/chatterbox-streaming.git
pip install -e .
```

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

### Initialize EnTokenizer

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/api-reference-utilities.md

Loads the tokenizer from a BPE vocabulary file. Ensure the vocabulary file exists and contains START and STOP special tokens, otherwise an AssertionError will be raised.

```python
def __init__(self, vocab_file_path: str) -> None:
    pass
```

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

### Real-time Audio Playback with Threading Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/MANIFEST.md

Illustrates how to integrate real-time streaming audio synthesis with playback, often using threading to avoid blocking the main application loop. This is essential for interactive audio experiences.

```python
# Example for real-time audio playback with threading (conceptual)
# This would involve a TTS model generating audio chunks and a separate thread playing them.
# import threading
# from queue import Queue
# from chatterbox import ChatterboxTTS
# 
# tts = ChatterboxTTS.from_pretrained("tts_models/en/ljspeech/tacotron2-v1")
# audio_queue = Queue()
# 
# def audio_player():
#     while True:
#         chunk = audio_queue.get()
#         if chunk is None: break
#         # Play audio chunk using a library like sounddevice or pyaudio
#         pass
# 
# player_thread = threading.Thread(target=audio_player)
# player_thread.start()
# 
# text = "Playing audio in real time."
# stream = tts.generate_stream(text)
# for chunk in stream:
#     audio_queue.put(chunk)
# audio_queue.put(None) # Signal end of stream
# player_thread.join()

```

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

### EnTokenizer Constructor

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/api-reference-utilities.md

Initializes the EnTokenizer with a vocabulary file path. It loads the tokenizer and validates the presence of START and STOP special tokens.

```APIDOC
## EnTokenizer Constructor

### Description
Initializes the EnTokenizer with a vocabulary file path. It loads the tokenizer and validates the presence of START and STOP special tokens.

### Parameters
#### Path Parameters
- **vocab_file_path** (str) - Required - Path to tokenizer vocabulary JSON file (e.g., "tokenizer.json")

### Notes
- Loads tokenizer from BPE vocabulary file.
- Validates presence of START and STOP special tokens.
- Throws AssertionError if required tokens are missing.
```

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

### Batch Processing with Caching Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/MANIFEST.md

Demonstrates efficient batch processing of text for speech synthesis, leveraging caching mechanisms to speed up repeated syntheses. This is beneficial for generating multiple audio outputs quickly.

```python
from chatterbox import ChatterboxTTS

# Initialize the TTS model
tts = ChatterboxTTS.from_pretrained("tts_models/en/ljspeech/tacotron2-v1")

# Prepare conditionals for caching (e.g., voice embeddings)
conditionals = tts.prepare_conditionals(reference_audio="reference_voice.wav")

# Synthesize speech for multiple texts in a batch
texts = ["First sentence.", "Second sentence."]
audios = tts.generate(texts, conditionals=conditionals)

# Process the batch of audio outputs

```

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

### Voice Cloning Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/MANIFEST.md

Illustrates how to perform voice cloning using the ChatterboxTTS class. This requires a pre-trained model and a reference audio file for the target voice.

```python
from chatterbox import ChatterboxTTS

# Initialize the TTS model with voice cloning capabilities
tts = ChatterboxTTS.from_pretrained("tts_models/en/ljspeech/tacotron2-v1", voice_cloning=True)

# Load a reference voice sample
reference_audio, sr = soundfile.read("reference_voice.wav")

# Synthesize speech in the cloned voice
text = "This is a sample of the cloned voice."
audio = tts.generate(text, reference_audio=reference_audio)

# Save the audio to a file (optional)
import soundfile as sf
sf.write("cloned_output.wav", audio, tts.sr)

```

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

### StreamingMetrics Example Interpretation

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/types.md

Illustrates how to instantiate and interpret the StreamingMetrics dataclass with sample values. This helps in understanding the performance characteristics of the streaming generation.

```python
metrics = StreamingMetrics(
    latency_to_first_chunk=0.472,
    rtf=0.499,
    total_generation_time=2.915,
    total_audio_duration=5.840,
    chunk_count=6
)
# First audio available in ~472ms
# Complete 5.84s of audio generated in 2.9s (2.0x real-time speed)
```

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

### Model Export and Deployment Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/MANIFEST.md

Illustrates the process of exporting a trained Chatterbox model for deployment. This typically involves saving the model weights and configuration in a format suitable for inference environments.

```python
# Example for model export and deployment (conceptual)
# This would involve using a method to save the model, potentially in ONNX or TorchScript format.
# from chatterbox import ChatterboxTTS
# 
# tts = ChatterboxTTS.from_pretrained("tts_models/en/ljspeech/tacotron2-v1")
# 
# # Hypothetical export method
# tts.export("exported_model/model.onnx", format="onnx")
# tts.export("exported_model/model.pt", format="torchscript")

```

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

### Get ChatterboxVC Sample Rate

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/api-reference-chatterboxvc.md

Initializes the ChatterboxVC model and prints its sample rate. Ensure CUDA is available for GPU acceleration.

```python
model = ChatterboxVC.from_pretrained(device="cuda")
print(model.sr)  # Output: 24000
```

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

### Example Streaming Metrics

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/streaming-implementation.md

Illustrates the metrics collected during a streaming audio generation process, including latency, chunk details, generation time, audio duration, and Real-Time Factor (RTF).

```text
Input: "This is a test sentence with several words."
Device: NVIDIA 4090 GPU
Settings: chunk_size=25, context_window=50, cfg_weight=0.5

Output:
├─ Latency to first chunk: 0.472s (time to first yield)
├─ Chunk 1: (24000 samples = 1.0s audio)
├─ Chunk 2: (24000 samples = 1.0s audio)
├─ Chunk 3: (24000 samples = 1.0s audio)
├─ Chunk 4: (24000 samples = 1.0s audio)
├─ Chunk 5: (24000 samples = 1.0s audio)
├─ Chunk 6: (20160 samples = 0.84s audio)
├─ Total generation time: 2.915s
├─ Total audio duration: 5.84s
├─ RTF: 0.499 (2.0x real-time speed)
└─ Total chunks: 6
```

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

### AttrDict Usage Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/api-reference-utilities.md

Demonstrates how to use the AttrDict class for accessing data. It shows both attribute-style and dictionary-style access, highlighting the flexibility of AttrDict.

```python
output = model.forward(...)  # Returns AttrDict
logits = output.speech_logits  # Attribute access
hidden = output['hidden_states']  # Dict access (both work)
```

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

### Real-Time Streaming Audio Generation

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/examples.md

Generate audio in real-time chunks for immediate playback. This example demonstrates collecting audio chunks, tracking the time to the first chunk, and calculating the Real-Time Factor (RTF).

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

model = ChatterboxTTS.from_pretrained(device="cuda")
text = "Streaming audio generation is now available. Each chunk is generated and can be played immediately."

# Collect chunks
audio_chunks = []
first_chunk_time = None

for audio_chunk, metrics in model.generate_stream(
    text,
    chunk_size=25,
    context_window=50,
    print_metrics=True,
):
    audio_chunks.append(audio_chunk)
    
    # Track first chunk time
    if metrics.chunk_count == 1:
        first_chunk_time = metrics.latency_to_first_chunk
        print(f"✓ First chunk available in {first_chunk_time:.3f}s")
        print("  Audio playback can start now!")

# Combine chunks
final_audio = torch.cat(audio_chunks, dim=-1)
ta.save("streamed_output.wav", final_audio, model.sr)

print(f"\nGeneration complete!")
print(f"Total RTF: {metrics.rtf:.3f} (generation {1/metrics.rtf:.1f}x faster than playback)")
```

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

### Expressive Speech Synthesis Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/MANIFEST.md

Shows how to achieve expressive speech synthesis by utilizing advanced parameters or conditioning. This example might involve specific model configurations or input formats.

```python
# Example for expressive speech synthesis (details depend on specific model capabilities)
# This might involve custom conditioning or specific generation parameters.
# from chatterbox import ChatterboxTTS
# tts = ChatterboxTTS.from_pretrained("expressive_model")
# text = "I am so excited about this!"
# audio = tts.generate(text, emotion="happy") # Hypothetical parameter

```

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

### Streaming TTS with Progress Tracking

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/examples.md

Monitor streaming text-to-speech generation progress in real-time using callbacks. This example shows how to track audio duration, elapsed time, and real-time factor (RTF) for each chunk.

```python
import time
from chatterbox.tts import ChatterboxTTS

model = ChatterboxTTS.from_pretrained(device="cuda")
text = "Track the progress of streaming generation in real-time."

start = time.time()
total_audio_duration = 0.0

print("Generation progress:")
print("Chunk | Audio (s) | Elapsed (s) | RTF")
print("------|-----------|-------------|-----")

for chunk, metrics in model.generate_stream(text, chunk_size=25):
    elapsed = time.time() - start
    total_audio_duration += (chunk.shape[1] / model.sr)
    
    if metrics.rtf:
        print(f"{metrics.chunk_count:5d} | {total_audio_duration:9.2f} | {elapsed:11.2f} | {metrics.rtf:.2f}")

print("------|-----------|-------------|-----")
print(f"Complete! Total: {total_audio_duration:.2f}s audio in {elapsed:.2f}s")
```

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

### Low-Latency Optimization Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/MANIFEST.md

Focuses on techniques and configurations for achieving low-latency speech synthesis, likely using streaming or optimized inference methods. This is crucial for real-time interactive applications.

```python
# Example for low-latency optimization (details depend on specific model and parameters)
# This might involve using generate_stream() with specific chunking or buffer settings.
# from chatterbox import ChatterboxTTS
# tts = ChatterboxTTS.from_pretrained("low_latency_model")
# text = "Fast response."
# audio_stream = tts.generate_stream(text, chunk_size=64) # Hypothetical parameter

```

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

### Real-Time Audio Playback with Threading in Python

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/examples.md

Stream audio and play it in real-time using background processing with threading. This example utilizes `sounddevice` for audio output and a custom `RealtimePlayer` class to manage audio buffering.

```python
import threading
import numpy as np
import sounddevice as sd
import torch
from chatterbox.tts import ChatterboxTTS

class RealtimePlayer:
    def __init__(self, sample_rate, buffer_size=8192):
        self.sr = sample_rate
        self.buffer = np.array([], dtype=np.float32)
        self.lock = threading.Lock()
        self.stream = None
        self.playing = False
    
    def start(self):
        def audio_callback(outdata, frames, time, status):
            with self.lock:
                if len(self.buffer) >= frames:
                    outdata[:, 0] = self.buffer[:frames]
                    self.buffer = self.buffer[frames:]
                else:
                    available = len(self.buffer)
                    if available > 0:
                        outdata[:available, 0] = self.buffer
                    outdata[available:, 0] = 0
                    self.buffer = np.array([], dtype=np.float32)
        
        self.stream = sd.OutputStream(
            samplerate=self.sr,
            channels=1,
            callback=audio_callback,
            blocksize=4096,
        )
        self.stream.start()
        self.playing = True
    
    def add_audio(self, chunk_tensor):
        chunk_np = chunk_tensor.squeeze().numpy().astype(np.float32)
        with self.lock:
            self.buffer = np.concatenate([self.buffer, chunk_np])
    
    def stop(self):
        while len(self.buffer) > 0:
            threading.Event().wait(0.05)
        self.stream.stop()
        self.stream.close()
        self.playing = False

# Use it
model = ChatterboxTTS.from_pretrained(device="cuda")
player = RealtimePlayer(model.sr)
player.start()

text = "This audio is playing in real-time as it's generated!"

for chunk, metrics in model.generate_stream(text):
    player.add_audio(chunk)
    if metrics.chunk_count == 1:
        print("▶ Audio playback started!")

print("✓ All chunks played")
player.stop()
```

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

### Error Handling and Fallback Example

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/MANIFEST.md

Demonstrates robust error handling strategies and fallback mechanisms within Chatterbox Streaming. This ensures the application remains functional even when errors occur during synthesis or processing.

```python
# Example for error handling and fallback (conceptual)
# This would involve try-except blocks around API calls and potentially fallback logic.
# from chatterbox import ChatterboxTTS, ChatterboxError
# 
# tts = ChatterboxTTS.from_pretrained("tts_models/en/ljspeech/tacotron2-v1")
# text = "A sentence to synthesize."
# 
# try:
#     audio = tts.generate(text)
# except ChatterboxError as e:
#     print(f"Error during synthesis: {e}")
#     # Fallback logic: use a default voice, log the error, etc.
#     audio = generate_fallback_audio(text)

```

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

### Basic Text-to-Speech Generation

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/README.md

Load the ChatterboxTTS model and generate speech from text. Save the output audio to a WAV file. Ensure you have torchaudio installed for saving audio.

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

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

# Generate speech
wav = model.generate("Hello world")

# Save to file
ta.save("output.wav", wav, model.sr)
```

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

### Continuous Buffer for Real-Time Audio Playback

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/streaming-implementation.md

Implements an audio buffer to manage incoming audio chunks for continuous playback. Requires numpy and sounddevice. Ensure the audio stream is properly started and stopped.

```python
import numpy as np
import sounddevice as sd
import threading

class AudioBuffer:
    def __init__(self, sample_rate, buffer_ms=1000):
        self.sr = sample_rate
        self.buffer = np.array([], dtype=np.float32)
        self.stream = None
        self.lock = threading.Lock()
    
    def start(self):
        def callback(outdata, frames, time, status):
            with self.lock:
                if len(self.buffer) >= frames:
                    outdata[:, 0] = self.buffer[:frames]
                    self.buffer = self.buffer[frames:]
                else:
                    available = len(self.buffer)
                    outdata[:available, 0] = self.buffer
                    outdata[available:, 0] = 0
                    self.buffer = np.array([], dtype=np.float32)
        
        self.stream = sd.OutputStream(
            samplerate=self.sr,
            channels=1,
            callback=callback
        )
        self.stream.start()
    
    def add_chunk(self, chunk_tensor):
        chunk_np = chunk_tensor.squeeze().numpy().astype(np.float32)
        with self.lock:
            self.buffer = np.concatenate([self.buffer, chunk_np])

# Usage
player = AudioBuffer(24000)
player.start()

# Assuming 'model' and 'text' are defined elsewhere
# for chunk, metrics in model.generate_stream(text):
#     player.add_chunk(chunk)
#     if metrics.latency_to_first_chunk:
#         print(f"Audio playback started! Latency: {metrics.latency_to_first_chunk:.3f}s")

# player.stream.stop()
```

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

### Real-time Streaming Text-to-Speech

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/README.md

Generate speech in chunks for real-time processing. This allows for immediate playback or processing of audio as it becomes available. The example shows how to access metrics like chunk count and real-time factor (RTF).

```python
for audio_chunk, metrics in model.generate_stream("Your text here"):
    # Process chunk immediately
    # Latency to first chunk: ~0.47 seconds
    # RTF: ~0.5 (2x real-time speed)
    print(f"Chunk {metrics.chunk_count}: {metrics.rtf:.3f} RTF")
```

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

### Type Checking Example for Streaming TTS

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/types.md

Demonstrates type annotations and checking for streaming Text-to-Speech generation. This snippet shows how to iterate over audio chunks and metrics, verifying the types of the audio chunk and streaming metrics.

```python
from chatterbox.tts import ChatterboxTTS, StreamingMetrics, Conditionals
from chatterbox.models.t3.modules.cond_enc import T3Cond
import torch

# Type annotations for proper IDE support
model: ChatterboxTTS = ChatterboxTTS.from_pretrained("cuda")
text: str = "Hello world"
conds: Conditionals = model.conds
t3_cond: T3Cond = conds.t3

for audio_chunk, metrics in model.generate_stream(text):
    chunk_tensor: torch.Tensor = audio_chunk  # Shape: (1, samples)
    timing: StreamingMetrics = metrics
    print(f"Chunk {timing.chunk_count}, RTF: {timing.rtf}")
```

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

### Model Initialization Flow

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/architecture-overview.md

Details the steps involved in initializing the ChatterboxTTS model from pre-trained weights, including downloading components, loading state dicts, and device placement.

```text
ChatterboxTTS.from_pretrained()
    ↓
HuggingFace Hub Download:
├── ve.pt (voice encoder)
├── t3_cfg.pt (T3 model)
├── s3gen.pt (S3Gen token-to-wav)
├── tokenizer.json (text tokenizer)
└── conds.pt (pre-computed default voice)
    ↓
    [State dict loading with CPU fallback]
    ↓
    [Device placement to specified device]
    ↓
ChatterboxTTS instance ready
    ├── self.t3: T3 model
    ├── self.s3gen: S3Gen model
    ├── self.ve: VoiceEncoder
    ├── self.tokenizer: EnTokenizer
    ├── self.device: Device string
    ├── self.conds: Conditionals (from conds.pt)
    └── self.watermarker: PerthWatermarker
```

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

### ChatterboxVC.from_local

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/api-reference-chatterboxvc.md

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

```APIDOC
## ChatterboxVC.from_local

### Description
Load voice conversion model from a local checkpoint directory.

### Method
`classmethod`

### Signature
`from_local(ckpt_dir: str | Path, device: str) -> ChatterboxVC`

### Parameters
#### Path Parameters
- **ckpt_dir** (str or Path) - Required - Directory containing checkpoint files: `s3gen.pt` and `conds.pt` (optional)
- **device** (str) - Required - Device placement: "cuda", "cpu", or "mps"

### Returns
- **ChatterboxVC** - `ChatterboxVC` instance

### Checkpoint files
- `s3gen.pt` - Required. S3Gen model weights
- `conds.pt` - Optional. Pre-computed speaker conditionals

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

model = ChatterboxVC.from_local(Path("./checkpoints"), device="cuda")
```
```

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

### Apply Context Window for Synthesis

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/streaming-implementation.md

Includes prior tokens to ensure continuity with previously synthesized audio. Handles token sequence length mismatches.

```python
if len(all_tokens_so_far) > 0:
    context_tokens = all_tokens_so_far[-context_window:]
    tokens_to_process = torch.cat([context_tokens, new_tokens], dim=-1)
    context_length = len(context_tokens)
```

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

### Get Resampler (S3Gen)

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/api-reference-utilities.md

Retrieves a cached audio resampler for efficient sample rate conversion. Caches up to 100 configurations and reuses existing resamplers for identical source and destination sample rates.

```python
@lru_cache(100)
def get_resampler(src_sr: int, dst_sr: int, device: str) -> ta.transforms.Resample:

```

```python
from chatterbox.models.s3gen.s3gen import get_resampler
import torch

# Get resampler 16kHz → 24kHz on GPU
resampler = get_resampler(16000, 24000, "cuda")
audio_24k = resampler(audio_16k)

```

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

### Real-time Conversational AI Workflow

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/README.md

This snippet illustrates the flow for real-time conversational AI using ASR, LLM, and ChatterboxTTS streaming generation. Recommended configuration: chunk_size between 15-25 and cfg_weight between 0.4-0.5.

```text
User speech → ASR → LLM → ChatterboxTTS.generate_stream() → Audio playback
```

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

### Parameter Tuning for Deterministic Output

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/quick-start.md

Achieve deterministic and consistent speech output by setting a low temperature and a high guidance weight.

```python
wav = model.generate(
    text,
    temperature=0.1,     # Low randomness
    cfg_weight=0.8,      # Strong guidance
)
```

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

### ChatterboxVC Voice Cloning and Synthesis Workflow

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/api-reference-chatterboxvc.md

Demonstrates initializing the ChatterboxVC model and performing voice conversion. This includes converting speech to a target voice and batch conversion to a specified voice.

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

# Initialize model
vc_model = ChatterboxVC.from_pretrained(device="cuda")

# Scenario 1: Convert to a specific voice
converted = vc_model.generate(
    "input_english_speech.wav",
    target_voice_path="spanish_speaker_reference.wav"
)
ta.save("output_spanish_voice.wav", converted, vc_model.sr)

# Scenario 2: Batch conversion to same voice
vc_model.set_target_voice("celebrity_voice_sample.wav")
for i in range(5):
    output = vc_model.generate(f"batch_input_{i}.wav")
    ta.save(f"batch_output_{i}.wav", output, vc_model.sr)
```

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

### Sequential and Parallel Batch Processing in Python

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/configuration.md

Demonstrates how to process a list of texts sequentially or in parallel using `concurrent.futures.ThreadPoolExecutor`. Ensure proper device management when using multiprocessing.

```python
texts = ["Hello", "How are you?", "Goodbye"]

# Process sequentially
for text in texts:
    wav = model.generate(text)
    ta.save(f"output_{texts.index(text)}.wav", wav, model.sr)

# Or in parallel with multiprocessing (with device management)
from concurrent.futures import ThreadPoolExecutor

with ThreadPoolExecutor(max_workers=1) as executor:
    futures = [executor.submit(model.generate, text) for text in texts]
    outputs = [f.result() for f in futures]
```

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

### Streaming Generation Data Flow

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/architecture-overview.md

Illustrates the step-by-step process of generating audio in chunks, from text input to processed audio chunks with metrics. Key features include context window maintenance, fade-in smoothing, watermarking, and real-time metric tracking.

```text
Text Input
    ↓
[punc_norm + EnTokenizer]
    ↓
[T3 inference_stream]  ← Yields chunks of speech_tokens
    │
    ├─→ Token Chunk 1 (25 tokens)
    │     ↓
    │   [_process_token_buffer]
    │     │
    │     ├─ Include context window (50 prior tokens)
    │     ├─ Tokenize with S3 tokenizer
    │     ├─ S3Gen inference (Tokens → Mel → Waveform)
    │     ├─ Extract new portion (skip context region)
    │     ├─ Apply fade-in smoothing
    │     ├─ Watermark
    │     └─→ Yield (audio_chunk, metrics)
    │
    ├─→ Token Chunk 2 (25 tokens)
    │     ↓
    │   [_process_token_buffer]
    │     └─→ Yield (audio_chunk, metrics)
    │
    └─→ ... (continue until EOS)

Metrics updated:
- latency_to_first_chunk: Set on first yield
- chunk_count: Incremented per chunk
- rtf: Calculated at end (total_time / audio_duration)
```

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

### Initialize ChatterboxTTS Instance

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/api-reference-chatterbottts.md

Illustrates the signature for initializing a ChatterboxTTS instance with its core model components. Direct instantiation is not recommended; use class methods instead.

```python
def __init__(
    self,
    t3: T3,
    s3gen: S3Gen,
    ve: VoiceEncoder,
    tokenizer: EnTokenizer,
    device: str,
    conds: Conditionals = None,
) -> None:
```

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

### Integrate Chatterbox TTS into Flask API

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/examples.md

Integrate Chatterbox TTS into a Flask API to provide a text-to-speech synthesis endpoint. This example shows how to handle POST requests with text and exaggeration parameters, returning synthesized audio as a WAV file.

```python
from flask import Flask, request, jsonify, send_file
from io import BytesIO
import torchaudio as ta
from chatterbox.tts import ChatterboxTTS

app = Flask(__name__)
model = ChatterboxTTS.from_pretrained(device="cuda")

@app.route("/synthesize", methods=["POST"])
def synthesize():
    data = request.json
    text = data.get("text", "")
    exaggeration = data.get("exaggeration", 0.5)
    
    if not text:
        return jsonify({"error": "No text provided"}), 400
    
    try:
        wav = model.generate(
            text,
            exaggeration=exaggeration,
        )
        
        # Convert to bytes
        buffer = BytesIO()
        ta.save(buffer, wav, model.sr, format="wav")
        buffer.seek(0)
        
        return send_file(
            buffer,
            mimetype="audio/wav",
            as_attachment=True,
            download_name="synthesis.wav"
        )
    
    except Exception as e:
        return jsonify({"error": str(e)}), 500

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)
```

```bash
curl -X POST http://localhost:5000/synthesize \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "exaggeration": 0.6}' \
  -o output.wav
```

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

### Exporting Synthesized Audio with Torchaudio

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/configuration.md

Demonstrates saving synthesized audio in various formats and sample rates using torchaudio. Ensure ChatterboxTTS is initialized with the correct device.

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

model = ChatterboxTTS.from_pretrained(device="cuda")
wav = model.generate("Hello world")

# Save as 24 kHz WAV (lossless)
ta.save("output.wav", wav, model.sr)

# Save as 16 kHz WAV (resampled)
resampler = ta.transforms.Resample(model.sr, 16000)
wav_16k = resampler(wav)
ta.save("output_16k.wav", wav_16k, 16000)

# Save as MP3 (lossy, but watermark survives)
ta.save("output.mp3", wav, model.sr, format="mp3")
```

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

### Streaming TTS Generation with Optimized Parameters

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/configuration.md

This snippet demonstrates how to stream audio generation in chunks, allowing for real-time processing or playback. It includes optimized parameters for chunk size, context window, and fade duration for smoother transitions. Metrics for timing are also printed.

```python
# Streaming configuration (alternative)
print("Streaming with optimized parameters:")
for chunk, metrics in model.generate_stream(
    text=text,
    audio_prompt_path="custom_voice.wav",
    exaggeration=0.6,
    cfg_weight=0.4,
    temperature=0.75,
    chunk_size=30,        # Moderate chunk size
    context_window=60,    # Good context window
    fade_duration=0.02,   # Smooth boundaries
    print_metrics=True,   # Show timing info
):
    # Process chunk (e.g., real-time playback)
    print(f"Chunk {metrics.chunk_count} received")
```

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

### Loading Chatterbox Models from Local Checkpoints

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/configuration.md

Demonstrates how to load ChatterboxTTS and ChatterboxVC models from local checkpoint directories.

```APIDOC
## Loading from checkpoints

### Description
Loads ChatterboxTTS and ChatterboxVC models from local checkpoint directories.

### Code Examples

**TTS from custom checkpoint**:
```python
from pathlib import Path
from chatterbox.tts import ChatterboxTTS

tts = ChatterboxTTS.from_local(Path("/path/to/checkpoints"), device="cuda")
```

**VC from custom checkpoint**:
```python
from pathlib import Path
from chatterbox.vc import ChatterboxVC

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

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

### Classifier-Free Guidance (CFG) Interpolation

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/architecture-overview.md

Illustrates the process of interpolating between conditioned and unconditional logits to enhance synthesis quality. Use higher weights to enforce conditioning, but be mindful of potential naturalness reduction.

```text
Generate with 2x batch size:
├── [0] Conditioned sequence (with speaker, emotion, etc.)
└── [1] Unconditional sequence (zeroed conditioning)

At each token step:
1. Get logits for both: logits_cond, logits_uncond
2. Apply CFG interpolation:
   logits = logits_cond + cfg_weight * (logits_cond - logits_uncond)
3. Sample next token from interpolated distribution
```

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

### Full TTS Generation with Configuration

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/configuration.md

Use this snippet to generate a complete audio file with all parameters specified, including voice cloning, expressiveness, guidance, and temperature. Ensure you have the necessary libraries (torch, torchaudio) and the ChatterboxTTS model loaded.

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

# Device configuration
device = "cuda" if torch.cuda.is_available() else "cpu"

# Initialize model
model = ChatterboxTTS.from_pretrained(device=device)

# Text processing configuration
text = "This is a comprehensive example with all parameters specified."

# Generation configuration
wav = model.generate(
    text=text,
    audio_prompt_path="custom_voice.wav",  # Voice cloning
    exaggeration=0.6,                       # Moderate expressiveness
    cfg_weight=0.4,                         # Slight guidance reduction
    temperature=0.75,                       # Some variation
)

# Output configuration
output_path = "configured_output.wav"
ta.save(output_path, wav, model.sr)
```

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

### Load ChatterboxVC from Local Checkpoint

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/api-reference-chatterboxvc.md

Load a voice conversion model from a local checkpoint directory. This directory must contain `s3gen.pt` and optionally `conds.pt`.

```python
@classmethod
def from_local(cls, ckpt_dir: str | Path, device: str) -> 'ChatterboxVC':
```

```python
from pathlib import Path
from chatterbox.vc import ChatterboxVC

model = ChatterboxVC.from_local(Path("./checkpoints"), device="cuda")
```

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

### Initialize ChatterboxVC Constructor

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/api-reference-chatterboxvc.md

The constructor for ChatterboxVC requires an S3Gen model and a device. A dictionary of pre-computed target voice embeddings can optionally be provided; otherwise, it must be set later using `set_target_voice()`.

```python
def __init__(
    self,
    s3gen: S3Gen,
    device: str,
    ref_dict: dict = None,
) -> None:
```

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

### Load ChatterboxVC from Local Checkpoint

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/configuration.md

Load a Chatterbox Voice Conversion (VC) model from a local checkpoint directory. Provide the `Path` to the checkpoint directory and specify the target device, such as 'cuda'.

```python
from pathlib import Path
from chatterbox.vc import ChatterboxVC

# VC from custom checkpoint
vc = ChatterboxVC.from_local(Path("/path/to/checkpoints"), device="cuda")
```

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

### Basic Text-to-Speech Synthesis

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/examples.md

Generate audio from text and save it to a WAV file. Requires initialization of the ChatterboxTTS model.

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

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

# Generate speech
text = "Welcome to Chatterbox TTS. This is a demonstration of text-to-speech synthesis."
wav = model.generate(text)

# Save to file
ta.save("welcome.wav", wav, model.sr)
print(f"Generated audio saved. Duration: {wav.shape[1] / model.sr:.2f} seconds")
```

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

### prepare_conditionals

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/api-reference-chatterbottts.md

Pre-computes and caches necessary data from a reference audio file for voice cloning, such as speaker embeddings and tokenized features.

```APIDOC
## `prepare_conditionals(wav_fpath, exaggeration=0.5)`

### Description
Pre-compute and cache conditionals (embeddings, tokens) from a reference audio file.

### Method Signature
```python
def prepare_conditionals(self, wav_fpath: str, exaggeration: float = 0.5) -> None:
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| wav_fpath | str | Yes | — | Path to reference audio file (.wav) for voice cloning |
| exaggeration | float | No | 0.5 | Emotion exaggeration factor to apply |

### Side effects
Updates `self.conds` (Conditionals) with speaker embeddings and reference data

### Processing
1. Load reference audio at both 16 kHz and 24 kHz
2. Extract voice encoder speaker embeddings
3. Tokenize reference with S3 tokenizer
4. Extract mel-spectrogram features from reference
5. Store all data in `Conditionals` object

### Example
```python
model = ChatterboxTTS.from_pretrained(device="cuda")

# Prepare voice once
model.prepare_conditionals("my_voice.wav", exaggeration=0.6)

# Generate multiple utterances with same voice
for text in ["Hello", "How are you?", "Goodbye"]:
    wav = model.generate(text)
```
```

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

### Parameter Tuning for Low-Latency Streaming

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/quick-start.md

Optimize streaming generation for lower latency by reducing chunk size and context window. This allows the first audio chunk to arrive faster.

```python
for chunk, metrics in model.generate_stream(
    text,
    chunk_size=15,       # Small chunks
    context_window=30,   # Minimal context
):
    # First chunk arrives faster
    print(f"Latency: {metrics.latency_to_first_chunk:.3f}s")
```

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

### Real-time Audio Playback with Sounddevice

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/quick-start.md

Stream audio chunks generated by `generate_stream` and play them in real-time using the `sounddevice` library. Buffers audio before playback to ensure smooth output.

```python
import sounddevice as sd
import numpy as np
from chatterbox.tts import ChatterboxTTS

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

# Create audio buffer
buffer = np.array([], dtype=np.float32)

# Generate and play in parallel
for audio_chunk, metrics in model.generate_stream(text):
    chunk_np = audio_chunk.squeeze().numpy().astype(np.float32)
    buffer = np.concatenate([buffer, chunk_np])
    
    # Once we have enough, start playback
    if len(buffer) > model.sr:  # 1 second buffered
        sd.play(buffer, model.sr)
        buffer = np.array([], dtype=np.float32)

# Play remaining audio
if len(buffer) > 0:
    sd.play(buffer, model.sr)
    sd.wait()
```

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

### Streaming TTS Generation

Source: https://github.com/davidbrowne17/chatterbox-streaming/blob/master/_autodocs/streaming-implementation.md

Main entry point for streaming synthesis. Prepares text, generates speech tokens chunk-by-chunk, synthesizes waveforms, and yields audio tensors with metrics.

```python
def generate_stream(
    self,
    text: str,
    audio_prompt_path: Optional[str] = None,
    exaggeration: float = 0.5,
    cfg_weight: float = 0.5,
    temperature: float = 0.8,
    chunk_size: int = 25,
    context_window: int = 50,
    fade_duration: float = 0.02,
    print_metrics: bool = True,
) -> Generator[Tuple[torch.Tensor, StreamingMetrics], None, None]:
    # ... implementation details ...
    pass
```