# 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. The transcription URL must be an absolute `http` or `https` URL. Each application attempt creates one bounded multipart framing and streams the audio from an open file between that framing; it does not buffer the complete audio or spool a multipart copy. The file field precedes the language field. WhisperX response acquisition is capped at 10 MiB. The initial request body and any transport-requested replay use the same multipart boundary and framing. Every body opens an independent audio handle and replay starts at the beginning. Narratio closes all bodies created for the attempt on response, failure, timeout, or cancellation, including when a transport abandons an earlier body. Genuine source read/close failures remain request failures; deliberate early closure of an abandoned original does not poison a valid replay. ## 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. Transport replay occurs inside one application attempt and does not consume an entry from the configured retry budget or increment the reported attempt count. The standard HTTP redirect policy remains in effect; body replay can also support body-preserving redirects. ## Validation And Failure Semantics Client construction rejects a missing or non-HTTP(S) 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. Replay makes a fresh request body available to the HTTP transport; it does not provide an exactly-once server guarantee and does not prove recovery from every proxy or protocol-level failure. A server may have received work before the client learns that a request failed. WhisperX operations should therefore be safe to retry for the same input when practical. ## 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. Each validated speaker is checkpointed independently; any speaker failure still fails the aggregate stage, while committed earlier speakers remain reusable on an ordinary retry. ## Related Canonical Docs - [Configuration](../config.md#pipeline) defines the operator-selected WhisperX URL, language, timeouts, retry policy, and concurrency. - [Adapter implementation](../internal/adapters.md) describes internal wiring. - [Transcribe stage](../internal/stage-transcribe.md) describes stage mechanics, durable artifacts, and manifests.