67 lines
2.8 KiB
Markdown
67 lines
2.8 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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|