f19ada75fb
The operator's chapter 6 review found a line attributed to Hallr that the text
gives to a scum boy, and no part of the system had flagged it. Spec 24 §2
diagnosed why: the duplicate scan only compares names that already exist, so it
cannot see a line given to the wrong EXISTING speaker. Spec 24 §4A proposed a
mechanical evidence gate. This is that gate, measured.
New umbraaudio/analysis/speech_evidence.py, model-free, plus
scripts/report_speech_evidence.py (read-only) and 44 tests.
For every dialogue line: extract the speaker the narration actually names, build
the candidate set from the cast rather than from the guess, and return
supported / contradicted / unsupported / unconstrained.
Last Dwarf, all 49 chapters, 3,918 dialogue lines:
supported 1,844 47.06%
unconstrained 2,032 51.86%
contradicted 34 0.87%
unsupported 8 0.20%
review queue 42 1.07%
It catches the chapter 6 defect exactly: "The leader on the right for Hallr
says," / "We want to be the ones to claim we killed the last dwarf" assigned to
Hallr, with the two leaders who could own it. attribution_qa reports 11 findings
book-wide and this one is not among them.
Two design decisions carried the precision, and both were forced by measurement.
First, "no tag" is not a finding: most dialogue has no tag because a tag
introduces only the first line of a conversation, so unconstrained and
unsupported are separate verdicts. The first working version queued 60% of the
book for this reason, which is the same as having no gate. Second, "ambiguous"
was removed as a verdict - it hid the case that matters, since a line assigned to
Hallr under "The leader on the right" is wrong no matter how many leaders exist.
Candidate count now decides whether a suggested fix is confident or a question.
Two corrections to spec 24, both from measurement. The 20 role-tag violations
reported in section 3 are really 11; my ad-hoc probe was worse than the checker
it was meant to replace. And identity coverage is already 100% - every dialogue
line resolves to a profile or alias - so the defect is never a missing speaker,
it is a line given to the wrong existing one.
Six extractor bugs the measurement exposed are now regression tests: a role
phrase with a spatial qualifier produced no tag at all; a coordinated predicate
spoke as its first subject instead of its last; a possessive voice resolved to a
profile called Voice; irregular plurals and superlatives never matched; and the
subject was read off trailing participial clauses. Two generalisable rules came
out of them - a speech tag's subject is a noun phrase and a prepositional
qualifier is still part of it, and a subordinating conjunction opens a clause of
its own ("The dragon swallows when Hallr says" is Hallr).
Reports carry chapter_id AND title because chapter_id and chapter_index differ
by one in every project here; a bare "ch8 utt264" sent the operator to the wrong
chapter, and the line they asked about is chapter 9 utt264.
Full suite 619 passed / 8 failed, the same 8 pre-existing failures. ruff clean.
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 |
| 18-UmbraTrans.md | Multilingual | Meaning-preserving translation, target voices, and multilingual audiobook production |
| 19-enterprise-control-plane.md | Enterprise | Multi-tenant projects, access control, artifact lineage, and commercial voice library |
| 20-enterprise-database-integration.md | Enterprise DB | Shared-PostgreSQL contract, blockers, cutover phases P1-P4 |
| 21-umbra-system-nodes-tasks-and-changes.md | System | Worker nodes, task assignment, cross-product change management, UI topology |
| 22-releases-and-the-publish-flag.md | Release | The publish flag, pinned artifact sets, post-publication change, and the Deal Hunter lesson |
| 23-speaker-duplicate-detection.md | Speakers | Duplicate-speaker scan, approval-safe merging, and the crowd veto |
| 24-analysis-quality-plan.md | Analysis | Why the ch6 speakers were missed, and a ranked plan to improve attribution |
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 |