Files
UmbraAudio/specs
B.D. Murphy df36dad8aa Weekly commit: attribution QA, dramatic variations, GPU TTS, AR export
Squashes ~3 weeks of uncommitted work (2026-09-03 → 09-21). The repo is the
only durable copy; a single accidental `git checkout` on routes.py nearly lost
a month of work (recovered from an editor snapshot, not git). See AGENTS.md →
"Commit Cadence" — commit every Sunday.

Attribution & QA
- New umbraaudio/analysis/attribution_qa.py: mechanical check_attribution /
  fix_high_confidence / verify_conversation_flow (speech-tag mismatch, narrator
  dialogue, role-tag guessing) plus scripts/qa_attribution.py CLI.
- llm_attributor prompt rules 3e-3h (unnamed roles, pronoun coreference,
  repeated lines) with wider scene/position context.
- Per-utterance QA box in chapter audio detail UI: hover issues, Recheck
  (auto-fix loop) and Accept (persisted qa_accepted* + text/speaker signature,
  auto re-surfaces when either changes). New POST /api/utterance/{id}/recheck
  and /api/utterance/{id}/qa-accept. _ensure_utterance_columns migration fixes
  legacy DBs that lacked the columns.

Generation
- Dramatic utterance variations: 26 emotions + pace + custom instruct,
  composed into every TTS voice mode (clone/icl/ref/embedding) and all
  generation sites; markers record the instruct so edits re-trigger.
- Staleness markers are JSON {speaker,text}; legacy plain-text markers always
  stale.
- Scene-break segmentation (generation/scene_break.py) + resegment merge.
- AR package exporter (assembly/ar_export.py) with tests.
- Voice ref resolution: rglob refs, canonical alias / first-word fallback.
- Edge-TTS fallback visibility: durable voice_engines.json ledger + UI badge.

GPU / TTS server
- qwen_tts_server: instruct + clone/icl support (voice_description →
  instruct_ids prepended to the talker input).
- qwen_tts.py remote path sends voice_description alongside voice_ref/slug.

Config / ops
- .env: UMBRA_TTS__QWEN_TTS_URL=http://localhost:8881.
- .gitignore: book projects, tmp_out, logs, one-off samples A/B demo.
- AGENTS.md + README.md: Commit Cadence (commit at least weekly, on Sunday).

New tests: test_qa_acceptance, test_variations, test_ar_export,
test_scene_break, test_resegment_merge, test_vocals_project. Suite: 327 pass
(6 pre-existing voice-profile accent-wording failures, unrelated).
2026-09-21 06:44:22 -07:00
..

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