e8944fcd88
Design-phase contract for moving UmbraAudio + the future UmbraTrans review UI
onto the shared enterprise PostgreSQL database without interrupting audiobook
production. No database contacted, no migration SQL, no production data written.
Verified against the real schema (infra/postgres/001_control_plane.sql, 13
tables, all identity/tenancy/audit) and the full current audio codebase.
Key findings:
- No local accounts exist to migrate; the only identity traces are the literal
string 'user' in two review tables. One canonical enterprise user.
- No durable utterance identity: artifacts are named by mutable
utterance_index (ch{N}/utt_{idx:04d}.wav), which spec 18 forbids as a
durable ID. Proposes a content-addressed source_unit_key recorded at
generation time, leaving on-disk names untouched for continuity.
- BLOCKER: umbracontrol_worker matches zero RLS rows and cannot attribute an
audit event, so worker identities are unrepresentable. Needs
service_identities + job_leases, not a GUC workaround.
- RLS machinery is owned by the postgres superuser because the bootstrap pipes
the schema through psql -U postgres. FORCE ROW LEVEL SECURITY would cause
42P17 infinite recursion; recorded as a load-bearing invariant.
- 10 verified application defects, incl. download traversal via string-prefix
containment and raw upload filenames.
No UmbraAudio behaviour changes. Adapter boundary keeps SQLite+filesystem as
the default repository so cutover is a flag flip and always reversible.
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 |