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 one WhisperX request per prepared file through a bounded errgroup.
- 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.

## Resume Evidence

Transcribe records a versioned semantic-configuration fingerprint containing
the Narratio-visible WhisperX service URL and recognition language. Changes to
either rerun transcription and stale its fixed descendants while leaving
prepare reusable. Retry count/delay, concurrency, timeout, credentials, and
diagnostic locations are operational and do not change this evidence.

WhisperX models or private service configuration not exposed by Narratio's
adapter contract cannot be fingerprinted; use `--force` after changing them.
An existing successful transcribe record without evidence reruns once when
selected.

## Related Contracts And Tests

- [WhisperX](../integrations/whisperx.md) owns HTTP, retry, timeout, and
  cancellation semantics.
- [Configuration](../config.md#pipeline) owns concurrency and other
  operator-selected values.
- Implementation and tests: `internal/stage/transcribe.go`,
  `internal/stage/transcribe_test.go`,
  `internal/stage/semantic_contracts_initial.go`, and
  `internal/stage/semantic_contracts_initial_test.go`