UmbraAudio

Quality-first multi-pass audiobook generation from English manuscripts.

Features

• 5-pass pipeline: Analysis → Voice Design → Mapping → Test → Generate
• Multi-engine TTS: Chatterbox (primary), Qwen3-TTS (secondary)
• LLM-enhanced: BookNLP for NLP, LLM for profiling/emotion/pronunciation
• Web review: FastAPI + HTMX at checkpoints for human approval

Quick Start

python -m umbraaudio.cli init <manuscript.epub> --name 'My Book'
python -m umbraaudio.cli analyze
python -m umbraaudio.cli voices
python -m umbraaudio.cli review

Requirements

• Python 3.11+
• NVIDIA GPU with CUDA support (RTX 3060 or better recommended)
• ffmpeg

Development

pip install -e ".[dev]"
ruff check umbraaudio/
pytest tests/ -v

Rebuilding from source

The repo tracks source only; large runtime data is reconstructed as needed.

1. Models: weights are not committed (see .gitignore). Download them:

   bash scripts/download_models.sh   # ~9 GB, targets ./models
   

2. Qwen3-TTS is a git submodule pinned to upstream commit 022e286:

   git submodule update --init --recursive
   

   The tts_server/web-demo backend includes a local UI customization to qwen_tts/cli/demo.py. It is preserved as a patch — reapply it after checking out the submodule:

   cd Qwen3-TTS && git apply ../scripts/qwen3_tts_demo_umbra_patch.patch
   

3. Environment: copy/keep .env (contains secrets) and set UMBRA_TTS__* model paths under models/.

Book projects (e.g. DealHunterShip_...) are committed separately under their own project directories and are not part of this program repository.