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

# Quickstart

> Get started with Qwen3-TTS in minutes with practical examples

This guide will walk you through generating your first speech with Qwen3-TTS using all three model types: CustomVoice, VoiceDesign, and Base (voice cloning).

## Prerequisites

Before you begin, make sure you have:

* Python 3.9 or higher (Python 3.12 recommended)
* A CUDA-compatible GPU (optional but recommended)
* Installed the `qwen-tts` package (see [Installation](/installation))

## CustomVoice: Generate with Preset Speakers

The CustomVoice models provide 9 premium preset voices across multiple languages.

<Steps>
  <Step title="Import and load the model">
    ```python theme={null}
    import torch
    import soundfile as sf
    from qwen_tts import Qwen3TTSModel

    model = Qwen3TTSModel.from_pretrained(
        "Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
        device_map="cuda:0",
        dtype=torch.bfloat16,
        attn_implementation="flash_attention_2",
    )
    ```
  </Step>

  <Step title="Generate speech with a preset speaker">
    ```python theme={null}
    wavs, sr = model.generate_custom_voice(
        text="Hello, welcome to Qwen3-TTS!",
        language="English",
        speaker="Ryan",
    )

    sf.write("output_custom_voice.wav", wavs[0], sr)
    ```

    <Note>
      Available speakers: Vivian, Serena, Uncle\_Fu, Dylan, Eric (Chinese); Ryan, Aiden (English); Ono\_Anna (Japanese); Sohee (Korean). See the [Custom Voice guide](/guides/custom-voice) for details.
    </Note>
  </Step>

  <Step title="Add instruction control (1.7B model only)">
    ```python theme={null}
    wavs, sr = model.generate_custom_voice(
        text="I'm so excited to announce this!",
        language="English",
        speaker="Ryan",
        instruct="Very happy and enthusiastic.",
    )

    sf.write("output_with_instruction.wav", wavs[0], sr)
    ```
  </Step>
</Steps>

## VoiceDesign: Create Custom Voices

The VoiceDesign model lets you create voices from natural language descriptions.

<Steps>
  <Step title="Load the VoiceDesign model">
    ```python theme={null}
    import torch
    import soundfile as sf
    from qwen_tts import Qwen3TTSModel

    model = Qwen3TTSModel.from_pretrained(
        "Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign",
        device_map="cuda:0",
        dtype=torch.bfloat16,
        attn_implementation="flash_attention_2",
    )
    ```
  </Step>

  <Step title="Generate with a voice description">
    ```python theme={null}
    wavs, sr = model.generate_voice_design(
        text="Welcome! I'm here to help you get started.",
        language="English",
        instruct="Male, 30s, professional and friendly tone, clear articulation",
    )

    sf.write("output_voice_design.wav", wavs[0], sr)
    ```

    <Tip>
      Be specific in your instructions. Include age, gender, tone, emotion, accent, and speaking style for best results.
    </Tip>
  </Step>
</Steps>

## Base: Clone Any Voice

The Base models can clone a voice from just 3 seconds of reference audio.

<Steps>
  <Step title="Load the Base model">
    ```python theme={null}
    import torch
    import soundfile as sf
    from qwen_tts import Qwen3TTSModel

    model = Qwen3TTSModel.from_pretrained(
        "Qwen/Qwen3-TTS-12Hz-1.7B-Base",
        device_map="cuda:0",
        dtype=torch.bfloat16,
        attn_implementation="flash_attention_2",
    )
    ```
  </Step>

  <Step title="Prepare reference audio">
    You need a reference audio file (3+ seconds) and its transcript.

    ```python theme={null}
    ref_audio = "path/to/reference.wav"
    ref_text = "This is the text spoken in the reference audio."
    ```

    <Note>
      The reference audio can be a local file path, URL, base64 string, or numpy array with sample rate.
    </Note>
  </Step>

  <Step title="Clone the voice">
    ```python theme={null}
    wavs, sr = model.generate_voice_clone(
        text="Now I can speak any text in this voice!",
        language="English",
        ref_audio=ref_audio,
        ref_text=ref_text,
    )

    sf.write("output_voice_clone.wav", wavs[0], sr)
    ```
  </Step>
</Steps>

## Batch Processing

All models support batch processing for efficiency:

```python theme={null}
# Batch generate with CustomVoice
wavs, sr = model.generate_custom_voice(
    text=[
        "First sentence.",
        "Second sentence.",
        "Third sentence."
    ],
    language=["English", "English", "English"],
    speaker=["Ryan", "Aiden", "Ryan"],
)

# Save all outputs
for i, wav in enumerate(wavs):
    sf.write(f"output_{i}.wav", wav, sr)
```

## Common Parameters

All generation methods support these optional parameters:

| Parameter            | Type  | Default | Description                             |
| -------------------- | ----- | ------- | --------------------------------------- |
| `do_sample`          | bool  | True    | Enable sampling for more natural speech |
| `temperature`        | float | 1.0     | Controls randomness (0.0-1.0)           |
| `top_k`              | int   | 50      | Top-k sampling parameter                |
| `top_p`              | float | 1.0     | Nucleus sampling parameter              |
| `max_new_tokens`     | int   | 2048    | Maximum tokens to generate              |
| `non_streaming_mode` | bool  | False   | Force non-streaming generation          |

Example with custom parameters:

```python theme={null}
wavs, sr = model.generate_custom_voice(
    text="Hello world!",
    language="English",
    speaker="Ryan",
    temperature=0.7,
    top_k=100,
    top_p=0.95,
)
```

## Model Selection Guide

<CardGroup cols={3}>
  <Card title="CustomVoice" icon="microphone">
    **Use when:**

    * You need consistent, high-quality preset voices
    * You want instruction-based control (1.7B)
    * You need multilingual support

    **Models:**

    * 0.6B: 9 preset speakers
    * 1.7B: 9 speakers + instructions
  </Card>

  <Card title="VoiceDesign" icon="wand-magic-sparkles">
    **Use when:**

    * You need custom voice characteristics
    * You want to describe voices in natural language
    * You need creative voice variations

    **Model:**

    * 1.7B only
  </Card>

  <Card title="Base" icon="clone">
    **Use when:**

    * You need to clone specific voices
    * You have reference audio samples
    * You want to fine-tune for your use case

    **Models:**

    * 0.6B and 1.7B
    * Both support 3-second cloning
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Explore Guides" icon="book-open" href="/guides/custom-voice">
    Learn about advanced features and workflows
  </Card>

  <Card title="API Reference" icon="code" href="/api/model/overview">
    Explore the complete API documentation
  </Card>

  <Card title="Performance Tips" icon="gauge-high" href="/advanced/performance">
    Optimize for speed and quality
  </Card>

  <Card title="Fine-tuning" icon="screwdriver-wrench" href="/advanced/fine-tuning">
    Customize models for your specific needs
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Model downloads are slow">
    Models are downloaded from Hugging Face on first use. For faster downloads in China, use ModelScope:

    ```bash theme={null}
    pip install modelscope
    modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local_dir ./models
    ```

    Then load from the local directory:

    ```python theme={null}
    model = Qwen3TTSModel.from_pretrained("./models/Qwen3-TTS-12Hz-1.7B-CustomVoice", ...)
    ```
  </Accordion>

  <Accordion title="Out of memory errors">
    Try these solutions:

    1. Use the 0.6B model instead of 1.7B
    2. Reduce batch size
    3. Use `dtype=torch.float16` instead of `bfloat16`
    4. Generate shorter text segments
  </Accordion>

  <Accordion title="Audio quality is poor">
    Check these factors:

    1. Use the 12Hz models (better quality than 25Hz)
    2. Set appropriate language explicitly
    3. For voice cloning, ensure reference audio is clear (3+ seconds, good quality)
    4. Adjust temperature (try 0.7-0.9 for more stable output)
  </Accordion>

  <Accordion title="FlashAttention 2 installation fails">
    FlashAttention 2 is optional but recommended:

    * Requires CUDA 11.8 or higher
    * On machines with limited RAM, use: `MAX_JOBS=4 pip install flash-attn --no-build-isolation`
    * If it fails, the model will work without it (just slower)
  </Accordion>
</AccordionGroup>

## Getting Help

<Card title="Join the Community" icon="comments" href="https://github.com/QwenLM/Qwen3-TTS/issues">
  Ask questions, report issues, and get help from the community on GitHub
</Card>