1bbbe5d92c
Persist per-utterance attribution transparency so the system can auto-accept high-confidence lines and surface only a small review queue: - DB: utterances gains attribution_evidence_kind, attribution_tag_name, attribution_uncertain, needs_review, review_reason; attribution_confidence default -> NULL. Idempotent migrations in database._migrate, routes _ensure_utterance_columns, and a new ensure in reattribute_all (raw-sqlite driver must add columns itself). - llm_attributor: accumulates scene-level mechanical evidence across batches and stamps evidence kind + tag name on attributed utterances. - New umbraaudio/analysis/clarity.py: deterministic evidence classification (name/role/pronoun/address_only/none), in-scene pronoun resolvability (gender-filtered candidate count), and composite needs_review rule: QA issues (long_monologue excluded), non-unique pronoun referent, role tag with no profile, none/address_only evidence < 0.75, unresolved uncertain flag, narrator-left dialogue, confidence < 0.7. Addressee counts only for known names/titles (guards 'But where...' false positives). - Drivers persist all fields: reattribute_all (per-chapter clarity pass), run_llm_attribution (via update_utterance_speaker), both web attribution paths. _populate_exceptions keys off needs_review (was confidence<0.7 + keyword sniff) and fixes a latent NameError (pid not in scope). - tests/test_clarity.py: 25 tests. Eval on Last Dwarf: 3918 dialogue lines -> 173 needs_review (4.4%), within the 1-5% target. Full suite 380 passed; 6 pre-existing voice_profile_manager accent failures. ruff/mypy clean on new code; routes.py baseline unchanged (73 pre-existing).
UmbraAudio Specifications
Index of all specification documents for the UmbraAudio audiobook generation system.
Specifications
| File | Topic | Description |
|---|---|---|
| 00-project-overview.md | Architecture | Pipeline overview, tech stack, data layout |
| 01-parsing.md | Pass 1a | EPUB, PDF, TXT, MD manuscript parsing |
| 02-analysis.md | Pass 1b | BookNLP, character profiling, pronunciation |
| 03-voice-design.md | Pass 2 | Per-character voice reference generation |
| 04-mapping.md | Pass 3 | Text segmentation, speaker attribution, manifests |
| 05-generation.md | Pass 5 | Audio generation, caching, retry, CUDA management |
| 06-normalization-watermarking.md | Post-gen | Audio normalization, ACX compliance, Perth watermark |
| 07-assembly-export.md | Export | M4B, MP3, WAV export via FFmpeg |
| 08-database.md | Database | SQLite schema, entity relationships, CRUD API |
| 09-web-review-ui.md | Web UI | FastAPI + HTMX review interface |
| 10-cli-orchestrator.md | CLI | Click commands, full pipeline orchestration |
| 11-configuration-dependencies.md | Config | Pydantic settings, dependencies, build system |
| 12-quality.md | Quality | MOS, WER, consistency, ACX compliance |
Quick Reference
Pipeline Passes
1a: Parse → chapters table
1b: Analyze → characters, pronunciation_guide
2: Voices → voice_ref WAVs
3: Map → manifests/*.json
4: Test → sample audio (optional)
5: Generate → audio/*.wav, audio_normalized/*.wav
Export → export/*.m4b, *.mp3
Key Entry Points
| Component | File | Class/Function |
|---|---|---|
| CLI | cli.py |
main Click group |
| Pipeline | orchestrator.py |
run_pipeline() |
| TTS | voices/chatterbox.py |
ChatterboxEngine |
| Segmenter | mapping/segmenter.py |
Segmenter |
| Generator | generation/chapter.py |
ChapterGenerator |
| Normalizer | assembly/normalize.py |
AudioNormalizer |
| Web UI | web/__init__.py |
create_app() |
| Database | database.py |
Database |