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](../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`