eric/narratio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 27 Wiki Activity

Document resumable transcription and replay

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-22 00:31:32 +00:00
parent 6e6054f744
commit 96b4e73f53
8 changed files with 299 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/operations.md
View File

@@ -116,8 +116,8 @@ Execution rules:
perpetually rerun dependent work.
Every aggregate stage except analyze currently provides semantic-configuration
evidence; analyze retains its more precise per-artifact fingerprints and
validator.
evidence; transcribe additionally reconciles per-speaker completion evidence,
while analyze retains its more precise per-artifact fingerprints and validator.
Prepare additionally validates current stable/local/S3 source identity and the
checksums of its durable prepared copies before reuse. Changed bytes, audio
membership, S3 object identity, or missing/tampered copies rerun prepare and
@@ -187,6 +187,54 @@ shared session lifecycle. In particular, render does not require Notarius or
Scriptorium, extract does not require Scriptorium, and analyze does not require
the transcription, Seriatim, Audita, or Notarius adapters.
### Transcription continuation and replacement
Transcribe checkpoints each validated speaker independently. If a later
speaker exhausts HTTP retries, the process is canceled, or the aggregate stage
save fails, the aggregate stage is not successful and downstream merge cannot
consume the partial set. The last successfully saved speaker records and their
canonical `transcripts/raw/<speaker>.json` files remain durable, however.
After correcting the underlying problem, retry normally:
```bash
narratio run-stage transcribe 2026-04-04
```
Narratio hashes the current prepared audio, validates recorded transcript JSON,
checksum, size, and location, and calls WhisperX only for missing or obsolete
speakers. A changed audio file replaces only its speaker; a changed WhisperX
URL or language makes every current speaker non-reusable. Retry, timeout, and
concurrency tuning do not invalidate completed speakers.
Use force only when every current transcript must be replaced, including after
a WhisperX model or private server-side configuration changes behind the same
URL and language:
```bash
narratio run-stage transcribe 2026-04-04 --force
```
Force durably clears the reusable collection before sending requests. If that
forced attempt fails, a later ordinary retry reuses only replacement speakers
checkpointed after the reset; it does not revive pre-force results. Do not edit
speaker checksums or copy older JSON into the canonical directory to influence
reuse.
The first current Narratio invocation that selects transcribe for an older
aggregate-only manifest retranscribes every current speaker once because the
old record cannot prove which audio bytes produced each file. Subsequent runs
reuse the new versioned evidence normally. The overall session-manifest schema
identifier is unchanged, but older strict-decoding Narratio binaries may reject
a manifest after current Narratio writes the additive speaker fields; retain a
backup or complete the upgrade before relying on downgrade.
Restoring a manifest does not implicitly publish or restore every raw speaker
file. If a recorded canonical transcript is absent locally, ordinary
reconciliation schedules that speaker again. Removing run directories does not
remove canonical checkpointed transcripts and does not by itself invalidate
them.
## Artifact Development Workflows
Choose the narrowest workflow that matches the intended replacement: