> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/yocxy2/chatterboxyocxy/llms.txt
> Use this file to discover all available pages before exploring further.

# ChatterboxVC

> API reference for the ChatterboxVC voice conversion class

## Overview

`ChatterboxVC` enables high-quality voice conversion, transforming the voice characteristics of input audio while preserving the linguistic content. This allows you to change the speaker identity of existing recordings.

## Class Signature

```python theme={null}
class ChatterboxVC:
    def __init__(
        self,
        s3gen: S3Gen,
        device: str,
        ref_dict: dict = None,
    )
```

## Parameters

<ParamField path="s3gen" type="S3Gen" required>
  The S3Gen vocoder model instance for audio conversion
</ParamField>

<ParamField path="device" type="str" required>
  Device to run inference on ("cuda", "cpu", or "mps")
</ParamField>

<ParamField path="ref_dict" type="dict">
  Optional pre-computed reference voice embeddings dictionary
</ParamField>

## Class Methods

### from\_pretrained()

Load the pre-trained ChatterboxVC model from Hugging Face.

```python theme={null}
@classmethod
def from_pretrained(cls, device: str) -> 'ChatterboxVC'
```

#### Parameters

<ParamField path="device" type="str" required>
  Device to load the model on ("cuda", "cpu", or "mps"). Automatically falls back to "cpu" if MPS is not available
</ParamField>

#### Returns

<ResponseField name="model" type="ChatterboxVC">
  Initialized ChatterboxVC model with pre-trained weights from `ResembleAI/chatterbox`
</ResponseField>

#### Example

```python theme={null}
from chatterbox import ChatterboxVC
import torch

# Load on GPU
device = "cuda" if torch.cuda.is_available() else "cpu"
vc_model = ChatterboxVC.from_pretrained(device)
```

### from\_local()

Load the model from a local checkpoint directory.

```python theme={null}
@classmethod
def from_local(cls, ckpt_dir: str, device: str) -> 'ChatterboxVC'
```

#### Parameters

<ParamField path="ckpt_dir" type="str" required>
  Path to the directory containing model checkpoint files
</ParamField>

<ParamField path="device" type="str" required>
  Device to load the model on ("cuda", "cpu", or "mps")
</ParamField>

#### Returns

<ResponseField name="model" type="ChatterboxVC">
  Initialized ChatterboxVC model with weights loaded from local directory
</ResponseField>

## Instance Methods

### set\_target\_voice()

Set the target voice for conversion from an audio file.

```python theme={null}
def set_target_voice(self, wav_fpath: str)
```

#### Parameters

<ParamField path="wav_fpath" type="str" required>
  Path to the audio file containing the target voice to convert to
</ParamField>

#### Example

```python theme={null}
# Set the target voice
vc_model.set_target_voice("target_speaker.wav")
```

### generate()

Convert the voice in the input audio to the target voice.

```python theme={null}
def generate(
    self,
    audio: str,
    target_voice_path: str = None,
) -> torch.Tensor
```

#### Parameters

<ParamField path="audio" type="str" required>
  Path to the audio file to convert
</ParamField>

<ParamField path="target_voice_path" type="str">
  Optional path to target voice audio file. If provided, will override the existing target voice
</ParamField>

#### Returns

<ResponseField name="audio" type="torch.Tensor">
  Converted audio waveform as a PyTorch tensor with shape `[1, samples]`. Sample rate is 44100 Hz (accessible via `vc_model.sr`). Audio includes perceptual watermarking
</ResponseField>

#### Example

```python theme={null}
import torchaudio
from chatterbox import ChatterboxVC

device = "cuda"
vc_model = ChatterboxVC.from_pretrained(device)

# Method 1: Set target voice, then convert
vc_model.set_target_voice("target_speaker.wav")
converted_audio = vc_model.generate("source_audio.wav")
torchaudio.save("converted_output.wav", converted_audio, vc_model.sr)

# Method 2: Convert with target voice in one call
converted_audio = vc_model.generate(
    audio="source_audio.wav",
    target_voice_path="target_speaker.wav"
)
torchaudio.save("converted_output.wav", converted_audio, vc_model.sr)
```

## Attributes

<ResponseField name="sr" type="int">
  Sample rate of generated audio (44100 Hz)
</ResponseField>

<ResponseField name="device" type="str">
  Device the model is running on
</ResponseField>

<ResponseField name="ref_dict" type="dict">
  Current target voice embeddings used for conversion
</ResponseField>

## Notes

* Voice conversion preserves the linguistic content and prosody while changing voice characteristics
* The model internally tokenizes the source audio at 16kHz before conversion
* Generated audio is automatically watermarked using the Perth implicit watermarker
* Both source and target audio are automatically resampled to the correct sample rates
* You must either call `set_target_voice()` first or provide `target_voice_path` to `generate()`