93 lines
4.3 KiB
Markdown
93 lines
4.3 KiB
Markdown
# 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.
|