narratio/docs/internal/stage-transcribe.md

Stage: transcribe

Purpose

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

Inputs and Outputs

Inputs:

• audio/*.flac prepared by prepare

Outputs:

• transcripts/raw/<speaker>.json for each input audio file

Boundaries

Owns:

• Discovering prepared audio inputs
• Deriving speaker ids from audio basenames
• Parallel WhisperX invocation with bounded concurrency
• Validating produced JSON and promoting run-local outputs

Does not own:

• Transcript merge/polish/normalize/trim/analyze

Config Fields Used

• session.session_id
• session.campaign
• pipeline.workspace.root
• pipeline.whisperx.transcribe_url
• pipeline.whisperx.language
• pipeline.whisperx.timeout
• pipeline.whisperx.retries
• pipeline.whisperx.retry_delay
• pipeline.whisperx.concurrency

External Adapters Used

• WhisperX adapter (env.WhisperX.Transcribe).

State and Manifest Behavior

• Uses run-local output paths under runs/{run_id}/transcribe/outputs/... when run layout is enabled.
• Validates each generated transcript JSON before promotion.
• Promotes canonical outputs to transcripts/raw/*.json.
• Records per-file metadata (attempts/status/duration/output path) in stage metadata.

Skip and Resume Behavior

• Runner-level skip applies for previously succeeded stage unless forced.
• On forced upstream reruns, downstream succeeded stages can be marked stale by runner logic.

Failure Behavior

• Fails if no prepared audio exists, duplicate speaker basenames are detected, adapter output path mismatches expected path, any output JSON is invalid, or one worker fails.
• Cancels in-flight workers after first terminal error.

Tests to Inspect Before Changing

• internal/stage/transcribe_test.go
• internal/app/whisperx_wiring_test.go

Architectural Invariants

• Speaker identity is derived from .flac basename and must be unique.
• Every successful speaker output must be valid JSON before promotion.
• Canonical raw transcript set is the only supported merge input surface.