• 10 languages — Chinese, English, Japanese, Korean, German, French, Russian, Portuguese, Spanish, Italian
• 9 premium voices — Male and female speakers across languages, dialects, and age ranges
• Multi-format support — .md, .markdown, .txt, .rst, .text
• Intelligent text cleaning — Strips markdown syntax, code blocks, links, and front-matter before synthesis
• Batch processing — Convert multiple files in a single command
• Chunked synthesis — Splits long text at sentence boundaries for consistent quality
• Rich CLI output — Progress bars, tables, and styled panels via Rich
• GPU accelerated — Runs on CUDA with auto-detection fallback to CPU

• Python 3.10+
• NVIDIA GPU with CUDA support (recommended) or CPU
• uv (recommended) or pip

git clone https://github.com/luis-codex/qwen-reader.git
cd qwen-reader

# Create virtual environment and install
uv venv
uv pip install -e .

# Install PyTorch with CUDA support (adjust cu128 to your CUDA version)
uv pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu128

# (Optional, Linux only) Install FlashAttention 2 for ~2x faster inference
pip install -U flash-attn --no-build-isolation

# Install with dev dependencies (pytest, pytest-cov)
uv pip install -e ".[dev]"

# Run the test suite
python -m pytest

Add the virtual environment's Scripts (Windows) or bin (Linux/macOS) directory to your system PATH:

# Windows (PowerShell) — run once
$scriptsPath = "$PWD\.venv\Scripts"
[Environment]::SetEnvironmentVariable("Path", "$([Environment]::GetEnvironmentVariable('Path', 'User'));$scriptsPath", "User")

# Linux / macOS — add to ~/.bashrc or ~/.zshrc
export PATH="/path/to/qwen-reader/.venv/bin:$PATH"

Then open a new terminal and use qwen-reader from anywhere.

Usage: qwen-reader [OPTIONS] COMMAND [ARGS]

Commands:
  read      Convert one or more files to audio
  speak     Convert inline text to audio
  speakers  List available TTS voices
  list      List previously generated audio files

# Single file
qwen-reader read article.md

# Multiple files at once
qwen-reader read notes.txt report.md spec.rst

# Choose a voice and language
qwen-reader read article.md --speaker Ryan --lang English

# Custom output directory
qwen-reader read article.md --output-dir ./my-audio

# Custom output filename
qwen-reader read article.md --name my-podcast

qwen-reader speak "Hello world, this is a test."
qwen-reader speak "Hola mundo, esto es una prueba." --lang Spanish --speaker Vivian

Pre-generated audio samples across all 10 supported languages are available in the demos/ folder. Listen to them to hear the quality before setting up the tool yourself!

To regenerate all demos: pwsh scripts/generate_demos.ps1

qwen-reader speakers

qwen-reader list

         📂 ~/qwen-reader-audio
┌──────────────────────┬────────┬──────────────────┐
│ File                 │   Size │ Modified         │
├──────────────────────┼────────┼──────────────────┤
│ 🔊 article.wav       │ 4.2 MB │ 2026-04-25 22:10 │
│ 🔊 spoken_text.wav   │ 0.1 MB │ 2026-04-25 21:52 │
├──────────────────────┼────────┼──────────────────┤
│ 2 files              │ 4.3 MB │                  │
└──────────────────────┴────────┴──────────────────┘

This project follows Clean Architecture with strict layer boundaries and a unidirectional dependency rule.

┌───────────────────────────────────────────────────────────┐
│  Interface Layer                           cli/           │
│  app.py · commands.py · options.py · rendering.py         │
│  click + rich · args, output, exit codes                  │
├───────────────────────────────────────────────────────────┤
│  Use-Case Layer                    core/synthesis.py      │
│  Orchestration · chunking → TTS → WAV assembly            │
├──────────────────────┬────────────────────────────────────┤
│  Domain Layer        │  Infrastructure Layer              │
│  core/text.py        │  core/model.py                     │
│  core/storage.py     │  Model lifecycle, GPU management   │
│  Pure transforms,    │  torch, qwen_tts (deferred import) │
│  file listing        │                                    │
│  stdlib only         │                                    │
└──────────────────────┴────────────────────────────────────┘

Interface → Use-Case → Domain
                     → Infrastructure → External Systems

No inner layer ever imports an outer layer. Core modules never call print(), sys.exit(), or import click/rich.

qwen_reader/
├── __init__.py              # Package version
├── __main__.py              # python -m qwen_reader entry
├── cli/
│   ├── __init__.py          # Re-exports cli, main
│   ├── app.py               # Click group, entry point, Windows UTF-8
│   ├── commands.py          # read, speak, speakers, list commands
│   ├── options.py           # Shared option decorators
│   └── rendering.py         # Rich console, progress bars, result panel
└── core/
    ├── __init__.py          # Docstring only — no re-exports
    ├── text.py              # Domain: text cleaning & chunking
    ├── storage.py           # Domain: audio file listing & output dir
    ├── model.py             # Infrastructure: lazy model singleton
    └── synthesis.py         # Use-Case: audio generation orchestration

tests/
├── conftest.py              # FakeModel stub + shared fixtures
├── test_text.py             # Domain layer — no mocks, stdlib only
├── test_storage.py          # Domain layer — file listing, no mocks
├── test_synthesis.py        # Use-Case layer — mocked infrastructure
└── test_cli.py              # Interface layer — click CliRunner

Each architectural layer has its own test file with a tailored testing approach:

# Quick run
python -m pytest

# With coverage report
python -m pytest --cov=qwen_reader --cov-report=term-missing

# Single layer
python -m pytest tests/test_text.py -v

Core modules never call sys.exit() — they raise typed exceptions. Only cli/commands.py converts exceptions to exit codes.

Configuration follows a strict priority order: CLI flags → Environment variables → Dataclass defaults.

Environment variables are read inside default_factory on config dataclasses — never scattered through application logic.

Dev dependencies (optional):

Every item must pass before merge to main.

• Interface layer (cli/) imports no infrastructure/domain heavy deps
• Domain layer (core/text.py, core/storage.py) has zero third-party imports
• Core modules never call print(), sys.exit(), or import click/rich
• All cross-layer data flows via @dataclass or callbacks
• Heavy imports (torch, model libs) are deferred inside functions

• pyproject.toml has [project.scripts] entry
• __main__.py exists and delegates to cli:main
• __init__.py exports only __version__
• pip install -e . + qwen-reader --help succeeds

• -h/--help available on every group and command
• -v/--version prints version and exits
• All options have show_default=True where applicable
• Success output is a structured Rich panel/table
• Error output uses [red]❌ prefix
• Exit codes follow contract (0/1/2)

• Empty file / empty text raises ValueError, not crash
• Unsupported extension raises ValueError with list of valid types
• File encoding fallback (UTF-8 → Latin-1) is implemented
• Windows UTF-8 stdout reconfiguration is present
• Batch processing continues on per-file errors

• Every public function has a docstring with Args/Returns/Raises
• Module-level docstring states purpose and dependency contract
• Type annotations on all public function signatures
• No # type: ignore without adjacent comment explaining why
• Constants use UPPER_SNAKE_CASE, classes PascalCase

• Domain layer has unit tests with no mocks (46 tests)
• Use-Case layer has tests that mock infrastructure (17 tests)
• CLI layer has click CliRunner tests (19 tests)

This project is licensed under the MIT License.