Installation

Audio version — Estimated duration: 6 min 12 sec

System requirements

Requirement	Minimum	Recommended
GPU	Any NVIDIA with CUDA compute 7.0+	Ampere (RTX 30xx) or newer
VRAM	6 GB	8 GB+
RAM	8 GB	16 GB
Python	3.9	3.11
Disk space	3 GB per model	6 GB for both
OS	Linux / Windows	Linux (CUDA tooling easier)

The suite is tested on an RTX 3050 6 GB. It will work on older cards (GTX 1080, RTX 2060) but with smaller batch sizes and slower inference.

Step-by-step

1. Create a Python environment (recommended)

Isolate dependencies to avoid conflicts:

python -m venv .venv
source .venv/bin/activate      # Linux
# .venv\Scripts\activate       # Windows PowerShell

2. Install dependencies

pip install -r requirements.txt

What gets installed:

Package	Role
torch	Core deep learning framework, GPU tensor ops
torchaudio	Audio I/O and signal processing for PyTorch
qwen-tts	Alibaba’s Qwen3-TTS model library
transformers	Hugging Face transformers (dependency of qwen-tts)
accelerate	Device mapping and memory optimisations
soundfile	Writing WAV files (sf.write)
numpy	Array operations for audio concatenation
tqdm	Progress bars during synthesis

If you have a specific CUDA version (12.1, 12.4, 11.8), you may want to pre-install the matching PyTorch from pytorch.org before running pip install -r requirements.txt.

3. Download model weights

Both model directories are gitignored — you must download them separately.

Option A — Git LFS (recommended):

git lfs install
git clone https://huggingface.co/Qwen/Qwen3-TTS-12Hz-0.6B-Base
git clone https://huggingface.co/Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice

Option B — Hugging Face CLI:

pip install huggingface-hub
huggingface-cli download Qwen/Qwen3-TTS-12Hz-0.6B-Base --local-dir ./Qwen3-TTS-12Hz-0.6B-Base
huggingface-cli download Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice --local-dir ./Qwen3-TTS-12Hz-0.6B-CustomVoice

Place them in the project root so the directory looks like:

project-root/
├── Qwen3-TTS-12Hz-0.6B-Base/
├── Qwen3-TTS-12Hz-0.6B-CustomVoice/
├── md_to_audio_base.py
├── md_to_audio_custom.py
├── sample.md
├── requirements.txt
└── content/

Each model directory should contain a config.json, model safetensors (model-00001-of-00002.safetensors etc.), tokenizer files, and other metadata.

4. Verify GPU and CUDA

python -c "
import torch
print(f'PyTorch: {torch.__version__}')
print(f'CUDA available: {torch.cuda.is_available()}')
if torch.cuda.is_available():
    print(f'GPU: {torch.cuda.get_device_name(0)}')
    print(f'VRAM: {torch.cuda.get_device_properties(0).total_mem / 1e9:.1f} GB')
"

Expected output:

PyTorch: 2.4.0+cu124
CUDA available: True
GPU: NVIDIA GeForce RTX 3050
VRAM: 6.0 GB

If CUDA available is False:

• Run nvidia-smi to confirm your GPU and driver
• Reinstall PyTorch matching your CUDA version: pip install torch --index-url https://download.pytorch.org/whl/cu124
• On Windows, ensure you have the NVIDIA CUDA Toolkit installed

---

Windows performance note

The flash-attn library is not supported on Windows. It only works on Linux and provides a further ~1.5–2× speedup over the sdpa backend used by these scripts.

On Windows (native), the script falls back to the eager attention backend if sdpa is also unavailable, which is ~2–3× slower than Linux with sdpa and ~4–6× slower than Linux with flash-attn.

For optimal performance on Windows, use WSL2 (Windows Subsystem for Linux). It provides native Linux CUDA support and full access to sdpa and flash-attn. See Microsoft’s WSL + CUDA guide.

Environment	Attention backend	Relative speed
Linux native	sdpa (or flash-attn if installed)	Fastest
WSL2	sdpa (or flash-attn)	~same as Linux native
Windows native	sdpa (or eager fallback)	2–6× slower

---

Next: Quickstart to generate your first audio.