narratio/docs/internal/stage-transcribe.md

Stage: transcribe

Purpose

Generate raw per-speaker transcripts from prepared audio using WhisperX.

Inputs

• audio/*.flac from prepare

Outputs

• transcripts/raw/<speaker>.json

Key Behavior

• discovers prepared audio from manifest inputs or canonical audio directory.
• derives the transcript identity from the prepared .flac filename.
• dispatches WhisperX requests through a bounded worker pool.
• validates each output as JSON.
• writes run-local outputs then materializes canonical transcript outputs only after every planned request succeeds.

Invariants

• prepared audio identities must be unique; prepare disambiguates distinct source paths that share a basename.
• output path returned by adapter must match requested output path.
• an empty adapter result path means the requested path; adapters cannot select an alternate destination.
• each successful output is validated before stage success, and cancellation or incomplete dispatch cannot be reported as a successful result.

Related Contracts And Tests

• WhisperX owns HTTP, retry, timeout, and cancellation semantics.
• Configuration owns concurrency and other operator-selected values.
• Implementation and tests: internal/stage/transcribe.go, internal/stage/transcribe_test.go