# 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

```bash
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

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

> **Commit cadence:** commit at least once every **Sunday**. Never leave a week (let alone a
> month) of work uncommitted — a single accidental `git checkout` on 2026-09-20 wiped out a
> month of changes to `umbraaudio/web/routes.py`. See `AGENTS.md` → *Commit Cadence*.

`scripts/commit_check.sh` enforces the nudge: it exits non-zero once the tree has been dirty
longer than a week. The LaunchAgent `com.umbraaudio.commitcheck` runs it every **Sunday at
18:00** and posts a macOS notification when there is uncommitted work.

```bash
scripts/commit_check.sh            # warn if dirty > 7 days
scripts/commit_check.sh --days 3   # tighter threshold
scripts/commit_check.sh --any      # warn on any uncommitted change
```

## 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
   bash scripts/download_models.sh   # ~9 GB, targets ./models
   ```

2. **Qwen3-TTS** is a git submodule pinned to upstream commit `022e286`:
   ```bash
   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:
   ```bash
   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.