Integration: WhisperX

Purpose

WhisperX transcribes each prepared speaker audio file for Narratio's transcribe stage. Narratio uses an HTTP boundary and installs each successful response as that speaker's raw transcript JSON.

HTTP Boundary

Narratio sends an HTTP POST to the configured transcription URL using multipart/form-data with:

file: the audio file, retaining its base filename; and
language: the configured language string.

The server must return a 2xx response whose body is valid JSON. Narratio does not currently require a more specific response schema at this boundary.

Request And Result Contract

Each adapter request identifies a speaker, a readable audio file, and the destination for the raw transcript. The HTTP request carries the audio and language; the speaker identifier remains Narratio orchestration metadata.

On success, Narratio atomically writes the response body to the requested destination. The adapter result reports that logical output together with the attempt count, final HTTP status when available, elapsed duration, and adapter identity metadata. A failed or invalid response is not installed as the transcript output.

Retry, Timeout, And Cancellation

The configured timeout applies independently to each HTTP attempt.
retries means additional attempts after the first.
HTTP 429, HTTP 5xx, attempt timeouts, and network errors are retryable.
Other HTTP 4xx responses and explicit cancellation are not retryable.
Narratio waits the configured retry delay between attempts and aborts that wait when the parent context is canceled.

Validation And Failure Semantics

Client construction rejects a missing or invalid absolute transcription URL, a missing language, a non-positive timeout, negative retries, or a negative retry delay. A request fails before transmission when its audio or output path is missing.

Non-2xx status, transport failure, response-size overflow, invalid JSON, or failure to install the output causes the transcription to fail. Errors include attempt context, and the result retains attempts, final status when available, and elapsed duration for diagnostics.

Determinism And Concurrency

Each audio request has stable multipart field names, and successful bytes are installed atomically. The transcribe stage may process speaker files in parallel, bounded by the configured concurrency. It records results in stable speaker order after all work completes; any speaker failure fails the stage.

Configuration defines the operator-selected WhisperX URL, language, timeouts, retry policy, and concurrency.
Adapter implementation describes internal wiring.
Transcribe stage describes stage mechanics, durable artifacts, and manifests.

2.8 KiB Raw Blame History