Audio version — Estimated duration: 5 min 26 sec
Turn Markdown documents into natural speech using Alibaba’s Qwen3-TTS neural TTS model, optimised for NVIDIA GPUs. Everything runs locally — your text never leaves your machine, no API keys, no internet required after setup.
The suite provides two Python scripts (md_to_audio_base.py and md_to_audio_custom.py) that handle the full pipeline: reading Markdown, cleaning formatting, splitting text into speech-friendly chunks, running GPU-based inference, and writing a 24 kHz WAV file.
Features
- Local & private — All model weights stored on disk, no data sent anywhere
- Two workflows — Voice cloning with a reference sample, or pick from 9 built-in speakers
- GPU-optimised — SDPA attention, TF32 matmul,
bfloat16support, adaptive token budgets - Batch processing — Process multiple chunks in parallel on GPU for throughput
- Resilient — Automatic fallback to sequential generation on batch failure
- Zero dependencies beyond PyTorch — No flash-attn required, works on Windows too (but see Windows performance note)
Model comparison
| Base model | CustomVoice model | |
|---|---|---|
| Script | md_to_audio_base.py | md_to_audio_custom.py |
| What you need | Reference audio + its transcript | Just a speaker name |
| Voice control | Clone any voice from a sample | 9 preset speakers |
| Speed | Good (batch_size 4 default) | Faster per-chunk (adaptive token budget) |
| VRAM usage | Higher (larger batches) | Lower (batch_size 1 default) |
| Best for | Custom voice replication | Quick, consistent narration |
Project structure
project-root/
├── md_to_audio_base.py # Voice cloning script
├── md_to_audio_custom.py # Preset voices script
├── requirements.txt # Python dependencies
├── sample.md # Example input file
├── Qwen3-TTS-12Hz-0.6B-Base/ # Base model weights (download separately)
├── Qwen3-TTS-12Hz-0.6B-CustomVoice/ # CustomVoice weights (download separately)
├── content/ # This documentation
└── assest/
└── qwen-tts-demo.png # Gradio UI screenshot
In a hurry?
# Install
pip install -r requirements.txt
# Quick test with a preset voice
python md_to_audio_custom.py sample.md --speaker "Ryan"
# Or clone a voice
python md_to_audio_base.py sample.md --ref_audio my.wav --ref_text "my transcript"That’s it — you’ll get output_custom.wav or output.wav.
Quick nav
| Section | What’s there |
|---|---|
| Installation | pip install, model download, environment setup |
| Quickstart | Get a .wav in 2 commands |
| Voice Cloning (Base) | Reference-based cloning — full guide |
| Preset Voices (CustomVoice) | 9 built-in speakers — full guide |
| Base Script CLI | md_to_audio_base.py — every argument explained |
| CustomVoice Script CLI | md_to_audio_custom.py — every argument explained |
| Architecture | Pipeline internals, chunking, token estimation |
| GPU Optimisation | VRAM, dtype, batch size — tuning guide |
| Troubleshooting | Common errors, OOM, quality fixes |
Tech stack: Python 3 · PyTorch (CUDA) · Qwen3-TTS 0.6B · 24 kHz mono WAV · SDPA attention