Files
UmbraAudio/specs
B.D. Murphy 829a03b89f Action the controller alignment proposal: source_unit_key + phase reports
The controller (oldbox) sent a data-model alignment proposal and asked for six
additive changes on this node, the validation protocol, and an honest report.
Six of the seven changes are done; the seventh is declared missing rather than faked.

Stage 0 - reachability verified exactly as documented: health 200, heartbeat 401
(the correct answer - auth is refusing), missing Host 400. Nothing else was sent.

source_unit_key (controller 5.1, the blocking item)
  umbraaudio/source_units.py. sha256("uk1" | chapter_source_text_sha256 |
  occurrence | text_sha256). Nothing positional in the key: "occurrence"
  disambiguates repeated text in document order.
  - 18,181/18,181 units keyed across all four projects, 0 collisions
  - chapter 1 renumbered +100 -> 0 keys changed (the load-bearing proof)
  - backfill 10,015 rows in 0.11s, second run stamps 0 (idempotent)
  - alignment phase 3: 200/200 probe units resolved with used_index: false
  - tolerates the older projects that have no chapters.chapter_index
  Recorded at generation time in chapter_builder, BEFORE the rows are read and
  BEFORE the marker is written, so every path that renders audio also produces
  identity and the clip can name its source unit.

5.7 recorded: utterance_index is KEPT as a display ordinal and made
  non-load-bearing. spec 21 §10.

Blob hashes and effect chain (5.2)
  Markers now carry the full sha256 of the delivered bytes and the effects that
  produced them. Verified the existing order is already correct - write_marker
  runs AFTER apply_effects - and closed the remaining hole: a changed trait list
  changed the hash with no recorded cause. sha256 verification is opt-in, since
  hashing every file on every validation pass would re-read gigabytes.

Vocabularies published (5.4) - umbraaudio/definitions.py, 19 sets, 126 values,
  each value carrying whether it is 'declared' (spec/controller) or 'extracted'
  (read out of code), so a diff shows a difference of meaning, not of wording.

Alignment report tool (6.6) - scripts/alignment_report.py --phase all. Emits the
  controller's envelope with the per-phase evidence shapes, and obeys the two
  rules they set: no evidence means blocked, never pass; a field we cannot produce
  is null PLUS a finding, never omitted. Phase 2 is deliberately 'fail' - the
  three-way store disagreement is real, and a pass there would be a check that
  passed by doing nothing.

Fingerprint discipline (5.5) - the drift detector reported its OWN fingerprint
  change when source_unit_key was added rather than hiding it. Node profile
  updated with the new fingerprints and an honest note that they moved.

Node report extended - per-project source-unit-key coverage, per-voice-asset
  sha256 + object_key, definition_set_version, controller stage reached.

Six gaps found in the proposal (spec 21 §11), including the one they invited plus
five more. The sharpest: "hash at generation" ignores that audio is
post-processed afterwards, and our key is anchored to chapters.source_text - a
second copy of the manuscript - so any change to chapter storage silently
invalidates every key in that chapter.

5.6 deliberately NOT faked: personality has no versioned artifact here, only
  unversioned LLM prose in speakers.json. Reported as phase 6b finding B-03
  instead, because wrapping unversioned inputs in a version field would produce
  artifacts claiming a lineage they do not have.

Answered the controller's two open questions (infra/controller-handoff-2026-10-03.md):
forward-only link for a revealed recurring character, and yes - a new edition may
contradict a frozen state, since this node's correction path IS a regeneration.

Full suite 484 passed / 8 failed - the same 8 pre-existing and unrelated failures.
ruff clean on every file touched. The parallel session's chapter_builder hunk
(helper_url) was filtered out of the commit and left intact in the working tree.
2026-10-02 20:16:06 -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