standard_asr

An already-decoded raw waveform.

Unlike the other variants, an array does not self-describe its sample rate. When sample_rate is None the global strict / best_effort policy decides whether to raise or assume the canonical 16 kHz.

eq is disabled because NumPy arrays do not support scalar equality; instances therefore compare by identity.

Base64-encoded (or data-URI) encoded audio.

Encoded audio held in memory.

The sample rate is self-describing via the file header.

Declared wire format for raw PCM frames fed to a streaming session.

A local audio file on disk.

The sample rate is self-describing via the file header.

Raised when an error occurs during audio loading or processing.

The audio loading and conversion functions in standard_asr.audio raise this.

A provider cloud-storage URI the engine resolves with its own credentials.

Whole engine classes are addressable only by a provider-native storage URI: AWS Transcribe batch requires an S3 URI (Media.MediaFileUri) and Google STT v2 requires a gs:// URI. These are not HTTPS-fetchable public URLs: the engine resolves them with its own cloud-SDK credentials, so -- unlike AudioUrl -- the standard MUST NOT run the HTTPS public-IP SSRF validator over them. The standard never fetches a storage URI itself; it only forwards it to an engine that declares "storage_uri" support.

Like AudioUrl / AudioBase64, this variant requires explicit construction: a bare str always coerces to AudioPath, never to a storage URI (the same SSRF safety stance against attacker-controlled strings). The scheme is validated against STORAGE_URI_SCHEMES at construction; file://, http(s)://, an empty value, or an unknown scheme is rejected with a clear error.

A remote URL the engine or cloud service fetches server-side.

The semantics are "the server can fetch this". Security constraints (HTTPS-only, private/loopback/link-local-address rejection) are enforced before the URL is forwarded to an engine, by standard_asr.audio.negotiation.validate_fetchable_url at plan execution. In v1 the standard never fetches the URL itself.

Per-channel transcription for multi-channel audio.

Raised when the CONFIGURATION -- supplied or ambient -- is invalid.

The type asserts fault ownership: the configuration's SUPPLIER can fix it (a bad init-config field, a default_language not in selectable_languages, a malformed --config / --set). Who that supplier is depends on the surface, and each surface maps the SAME error accordingly:

• CLI: the invoking user owns the config -- the flags AND the env vars -- so every ConfigError is caller-actionable there: usage exit 2, with the sanitized message naming the field to fix.
• Reference server: a wire client cannot supply engine config at all (construction is zero-arg; options are the portable WireRuntimeParams), so a ConfigError reaching the server -- at construction, transcription, or session establishment -- is a deployment-side fault and maps to a scrubbed 500 (WS internal_error); the client-fixable rejections have their own types (UnsupportedFeatureError -> 422, request validation -> 422). See ConfigurationRequiredError for the absent-config 503 state.

Engine-DECLARATION defects (a malformed declared language tag, an unsatisfiable prepare shape, an IC.6 violation) are NOT this type: they raise EngineContractError, because no configuration value fixes them. An engine that raises ConfigError (or lets a construction-time ValidationError, which ModelRegistry.create wraps into one, escape its factory) for a fault that is NOT about the supplied configuration mis-asserts this ownership contract -- the compliance suite's zero-arg construction check fails such engines (engine_construction_failed); consumers do not second-guess the type. The ValueError mixin serves IN-PROCESS callers, who genuinely can pass a bad config value to a constructor.

The one machine-distinguishable sub-state is ABSENT required configuration: raise (or catch) ConfigurationRequiredError for that -- consumers such as the compliance suite treat "config missing from this environment" (skip) differently from "config invalid" (fail).

Raised when required runtime configuration is ABSENT, not invalid.

The narrow, machine-distinguishable subtype of ConfigError for the one state that is a fact about the ENVIRONMENT rather than about any code or declaration: a required config field (typically a credential) was neither passed explicitly nor found in the environment. Consumers use the distinction to keep two very different verdicts apart:

• the compliance suite SKIPS instantiation-level checks on this error (a credentialed engine on a clean CI is behaving correctly; the verdict must not depend on the runtime's credential state), while
• any other ConfigError -- an invalid supplied value, an internally inconsistent declaration, a factory contract bug -- stays a compliance FAILURE (skipping those would let a broken plugin read as green-with-warning).

from_env raises this automatically when construction failed solely because required fields are missing, so engines following the documented explicit > env > raise pattern get the classification for free. An engine building its config another way should raise this type itself for the missing-credential state.

Transport mapping: the reference server maps this state to HTTP 503 (REST) / a service_unavailable frame (WS) with a stable generic detail -- whether it surfaces at zero-arg engine construction or lazily at transcription/session establishment (an engine deferring its credential check past __init__). An operator-side availability state, never the caller's 422, and never the absent field names (those are deployment detail, safe-logged for the operator only).

A structured, non-fatal notification from the standard layer.

Diagnostics report lossy conversions, assumed parameters, best_effort degradations, and similar non-ideal paths.

Request marker for speaker diarization ("who said what").

Presence enables diarization: RuntimeParams(diarization=DiarizationRequest()) (or the DIARIZE convenience constant) requests speaker labels; diarization=None (the default) means not requested. There is no []-analog -- a "requested-but-empty" state is meaningless for an on/off feature, so None vs an instance is the whole state space. On the wire the marker maps three ways: "diarization": {} -> DiarizationRequest(); "diarization": null -> None; key absent -> None.

The model is a deliberately empty frozen marker in v1: tuning parameters (num_speakers / min/max hints, granularity selection) are deferred because today's engine landscape cannot honor them portably -- they graduate additively onto this model once support is broad enough. extra="forbid" keeps that evolution honest: an unknown key (for example, a client guessing num_speakers) fails loudly (a 422 on the wire) instead of being silently ignored. An import-time assert in standard_asr.runtime.gating additionally forces sub-gating to be written the moment a field is added here.

Base class for discovery and plugin-related errors.

Raised when a constructed engine breaks the protocol contract.

The runtime counterpart of a compliance failure, in two shapes:

• Runtime behavior: a SYNCHRONOUS StandardASR member (transcribe / start_transcription / supports / recommended_wire_format / prepare) returned an awaitable (an async def implementation, or a sync wrapper delegating to one) or a value outside its protocol-pinned return type. Raised by standard_asr.runtime.protocol_boundary.require_sync_result at the consumer call sites (CLI, reference server) so the defect is loud at the boundary instead of surfacing as a confusing secondary AttributeError (or a silent misreading) deep inside another subsystem.
• Declaration shape: the engine DECLARED something the contract forbids -- a prepare that is a coroutine function, non-callable, or parameter-requiring; a malformed selectable_languages / detectable_languages tag; a language axis without the IC.6 default_language obligation. No caller-side value can fix these, which is what separates them from ConfigError (an invalid configuration VALUE, fixable by whoever supplies the config).

An engine/plugin fault, never a caller mistake -- deliberately NOT a ValueError: transports and the CLI map the ValueError family to caller-fixable surfaces (HTTP 422 / usage exit 2), while this must land on the engine-fault surfaces (scrubbed HTTP 500 / internal_error frame / CLI exit 1). If you hit it as an application developer, report it to the engine's author. Messages carry type names only, never the offending value.

Raised when an entry point name or metadata is invalid.

Raised when FFmpeg is required but not found in the system PATH.

Raised when FFprobe is required but not found in the system PATH.

Raised when an entry point target cannot be imported or is not callable.

Raised when no viable conversion path exists for the provided audio.

This happens when the shape an application provides cannot be negotiated into any shape the engine accepts (for example, a local array given to an engine that only accepts a server-fetchable URL).

Raised when provider_params are invalid for the target engine.

Unlike standard-set parameters, provider_params errors are always raised regardless of strict / best_effort -- they indicate a code-level bug (such as passing one engine's params model to another after a swap).

Raised when a streaming session is driven incorrectly while still live.

A caller-side programming error against an open session -- distinct from StreamClosedError (the stream genuinely ended). It covers the still-live-session usage breaches that are NOT lifecycle-close:

• mixing managed feed() with manual send_audio / end_audio (only one input mode may own a session);
• calling feed() more than once (a session owns at most one fed source);
• iterating the event stream more than once (single-consumer contract).

The session is not closed in any of these cases -- the mistake is in how the application used it. Catching StreamClosedError here would lead an application to wrongly conclude the session terminated and rebuild it. Mixes in ValueError (like ConfigError / InvalidProviderParamError): it is a bad-call programming error. (It has no HTTP mapping: it fires only against an in-process session object, and the server drives its own sessions correctly by construction.)

Container for discovered ASR engine factories.

ModelRegistry holds the results of plugin discovery and provides methods to list, query, and instantiate ASR engines. It does not perform discovery itself—use discover_models() to create a populated registry.

Typical Usage:

>>> from standard_asr import discover_models
>>> registry = discover_models()
>>>
>>> # List all available models
>>> registry.names()  # ['faster-whisper/large-v3', 'whisper/base', ...]
>>>
>>> # Create an ASR instance
>>> asr = registry.create("faster-whisper/large-v3", device="cuda")
>>> result = asr.transcribe(audio)

Key Methods:

• names(): List all discovered model keys.
• keys_by_engine(engine_id): List models for a specific engine.
• create(name, **kwargs): Instantiate an ASR engine.
• spec(name): Get metadata for a model.

Initialize with a mapping of model specs (internal use).

Metadata for a discovered ASR model entry point.

Closed per-request parameter container.

Segment-level detail, shared between batch results and streaming events.

Structural protocol for a Standard ASR engine.

Any object exposing these members is a compliant engine, regardless of how it is implemented. The protocol describes the full public surface every engine exposes -- batch (transcribe / transcribe_async) and the streaming entry point (start_transcription). start_transcription is always present; streaming support itself is optional, so a batch-only engine raises UnsupportedFeatureError from it. Because the surface is complete, callers (for example, the server) can type an engine as StandardASR and call the streaming entry point without a cast.

Base class for every domain error the Standard ASR runtime raises.

It does not cover data-model construction, which is pydantic's: a malformed field on RuntimeParams, on a result model, or on a config raises pydantic.ValidationError. That is a ValueError, not a StandardASRError. Plain caller misuse likewise raises a built-in: ValueError for a bad value (two mutually exclusive arguments), TypeError for a wrong type (an unsupported input type).

except (StandardASRError, ValueError) catches the domain errors and the value mistakes. A TypeError stays outside both on purpose -- a wrong input type is a code bug to fix, not a state to handle.

Raised when audio is delivered to a streaming session that is closed.

Strictly a lifecycle-close breach: the input side is over, so the audio can no longer be consumed. Covers send_audio after end_audio() and send_audio after the session already delivered a terminal event (the audio queue has no consumer anymore). It does NOT cover usage mistakes against a still-live session (mixing feed with manual input, calling feed twice, or iterating the event stream twice) -- those raise InvalidSessionUseError, so an application can tell "the session ended" apart from "my code drove the session incorrectly".

Application-side overrides for a session's termination deadlines.

Pass to StandardASR.start_transcription(deadlines=...). Only fields you explicitly set are applied; unset fields keep whatever the engine (or the standard default) chose. Precedence: application explicit > engine construction choice > standard default.

The fields mirror the TranscriptionSession deadline parameters -- see there for full semantics. Each accepts None to explicitly disable that deadline.

Base for errors that carry machine-readable context beside the message.

Gives the error half of the contract the same "don't make me parse the message" property the diagnostics have: an application can read .param (the offending field/parameter), .hint (actionable guidance), and .details (structured context -- for example, the sanitized pydantic error entries behind a wrapped config failure) without scraping str(exc). Every context field is optional and keyword-only, so Error("message") keeps working while Error("message", param="base_url", hint="use https") is now valid too -- removing the asymmetry where only some exceptions accepted structured fields (spec: explicit > implicit; structured over stringly typed).

Raised by to_srt / to_vtt when segments cannot render as visible cues.

A subtitle cue is an interval claim -- "this text occurs at this time" -- and it must survive the output's millisecond grid to be seen at all. A segment is therefore UNRENDERABLE in either of two ways: it lacks a measured span (Segment.timestamp_status is "start_only" or "unavailable"), or its measured span quantizes to zero milliseconds on the output grid (end and start format to the same timestamp -- players silently drop such cues, so emitting one silently hides the text while the render call reports success). Neither dropping the text nor fabricating timing is the renderer's to choose silently: under the default policy (on_unrenderable="error") it raises this error, and the caller picks the loss explicitly ("omit" drops the unrenderable segments' text from the timed cues; "collapse" renders one whole-text cue with no real timeline). Mixes in ValueError: the caller can fix the call -- choose a policy, or supply renderable segments.

Synchronous bridge over an async TranscriptionSession.

Runs a single background event loop in a dedicated thread (owned by this object and torn down on close), so applications can drive an async engine synchronously and authors only ever write async code.

Lifecycle submits (__enter__ / input calls / __exit__) carry a timeout: a hanging engine _open / _close can never deadlock the calling thread, and on every cooperative path the background loop + thread are torn down even on timeout (from an external thread, no deadlock). A truly blocking, non-awaiting engine can survive the join and leave the daemon thread alive with the loop unclosed -- see _shutdown; the sync-bridge compliance check reports that state as a thread leak.

Wrap an async session.

Raised when an engine fails during batch transcription (the cardinal sin guard).

This is the portable batch error contract: when an engine's model inference, network call, or SDK fails inside _transcribe, the failure MUST surface as a TranscriptionError (with the original exception preserved as __cause__ via raise ... from) so an application can catch one type across every engine instead of each engine's native exception (RuntimeError, an SDK error, requests.HTTPError, and so on). It is the batch counterpart of the streaming error event's engine_error code. It denotes an engine/runtime fault, not a caller mistake (those raise ConfigError / UnsupportedFeatureError / InvalidProviderParamError / AudioProcessingError), so the server maps it to a generic 5xx.

Carries the StructuredError fields plus .retriable: when an engine knows a failure is transient (a 503 / timeout / rate-limit) it MAY pass retriable=True so an application can decide whether to retry. None (the default) means "unknown" -- the safe reading is do not assume it is safe to retry.

A single streaming transcription event.

The constant-shape result returned by transcribe and stream reduction.

The top-level text / segments / words are always the complete, channel- and speaker-agnostic transcription. For multi-channel audio they are the time-merge of all channels (never channel-0-only), so ignoring channels is always safe and lossless.

Async-first, full-duplex streaming session base.

Authors implement _produce (and optionally _open / _close), reading fed audio via audio_chunks and yielding TranscriptionEvent objects. The base manages input ownership, bounded backpressure, lifecycle enforcement, a bounded rolling audio buffer

• reconnect scaffolding, termination deadlines, and result reduction.

Reconnect contract -- base vs engine:

• The base owns a bounded rolling audio buffer (the most recent fed chunks) and exposes replay_buffer, the source replayable classification, and note_reconnect. It cannot detect a reconnect itself (it owns no network connection).
• The engine detects the disconnect, re-establishes the connection, replays replay_buffer audio, keeps segment_id / timestamps / detected language / speaker-label mapping continuous, then calls note_reconnect. For speaker labels the safe default is mint-fresh: the engine MUST NOT reuse a pre-reconnect label for a post-reconnect cluster without identity evidence (blind clustering restarts from zero after a reconnect) -- it MUST mint fresh labels (speaker_2, speaker_3, and so on) and emit a speaker_labels_reset diagnostic via emit_diagnostic -- the fidelity-warning counterpart of content_lost, which is an error event -- because over-counting speakers is the safe direction while silently merging two people under one label is not. The base then emits the progress(reconnect=True, gap_start, gap_end) event and, iff the engine passed content_lost=True (its own determination that the reconnect + replay could not cover the gap), a trailing error(code="content_lost", recoverable=True) fidelity warning.

Initialize the session.

An AudioUrl failed the SSRF security policy and MUST NOT be forwarded.

Raised before a URL is handed to an engine when the URL fails the SSRF policy: a malformed URL or port, a non-HTTPS scheme, or a missing host. Unless allow_private_addresses opts out, it also covers a host that does not resolve, and any resolved address (in whole or in part) that is not globally routable -- private / loopback / link-local and their relatives. Under that opt-in the validator returns after the structural checks and never resolves the host, so an unresolvable name reaches the engine and fails there instead. Subclasses IncompatibleAudioInputError so existing audio-input error handling catches it, while remaining distinguishable.

Raised in strict mode when a requested standard feature is unsupported.

In best_effort mode the unsupported parameter is ignored and a structured diagnostic is returned instead of raising. The strict path carries the same structured context as that diagnostic so callers can inspect which feature was rejected without parsing the message.

Word-level detail, shared between batch results and streaming events.

Granularity for requested word timestamps.

The member values are the single source of truth shared with the declaration-side capability vocabulary WordTimestampGranularityName (a Literal). A module-level assertion (below) and a drift test bind the two sets so an additive change to one cannot silently desync the other.

Discover all installed ASR plugins and return a registry.

This is the main entry point for the plugin discovery system. It scans the standard_asr.models entry point group and returns a ModelRegistry containing all discovered ASR engine factories.

Render a transcription result as SRT.

Cue text is sanitized so it cannot forge cue structure (line terminators normalized, interior blank-line runs collapsed). Unlike to_vtt, SRT has no character-reference mechanism, so & and angle brackets in transcript text are emitted verbatim: an engine-leaked <unk> token or <i> is passed through as-is. Most SRT players render angle-bracket text literally, but some interpret a subset of HTML-like tags; if a downstream consumer must neutralize tags, do so on the transcript text before rendering. (WebVTT, which mandates escaping, is handled by to_vtt.)

Speaker rendering: SRT has no speaker syntax, so opting in mutates the cue text itself -- each labeled cue is prefixed with [<label>]: . The default is False on text-purity grounds (the renderer is a projection of the transcript; injecting labels uninvited would surprise every consumer that treats the cue text as speech), not for backward compatibility. Cues whose speaker is None are rendered unchanged; empty-text segments are skipped even when labeled (a label with no payload is not a cue).

Unrenderable segments: a segment without a measured span, or whose measured span quantizes to zero milliseconds on the output grid (its T --> T cue would be silently dropped by players), cannot render as a visible cue. By default that raises SubtitleRenderingError -- the render never silently drops, hides, or fabricates -- and the caller opts into a loss explicitly: on_unrenderable="omit" renders only the renderable cues (the other segments' text is absent from the file), "collapse" renders one synthetic whole-text cue [0, duration] (or [0, 3 s] when duration is unknown or quantizes to zero milliseconds; the fallback exists for the same player behavior). result.segments is None (segmentation not requested/applicable) uses the same whole-text fallback under every policy; segments == [] (requested but empty, for example, silence) ALWAYS yields no cues. The synthetic cue carries no speaker label -- a whole-text cue has no single attributable speaker -- so include_speakers has no effect on it. Pass a fully renderable result for time-accurate (and speaker-attributed) subtitles.

Render a transcription result as WebVTT.

Cue text is escaped per the W3C WebVTT cue-text grammar (& -> &, < -> <, > -> >) so payload text -- including engine-leaked <unk> / <|...|> tokens or "AT&T" -- is shown verbatim instead of being silently dropped by the browser's cue-span tokenizer. Cue structure is also protected (line terminators normalized, blank-line runs collapsed, --> neutralized by the > escape).

Speaker rendering: opting in wraps the whole cue body of each labeled cue in WebVTT's native voice span, <v <label>>. The default is False on text-purity grounds (the renderer is a projection of the transcript), not for backward compatibility. Cues whose speaker is None are rendered unchanged; empty-text segments are skipped even when labeled.

Unrenderable segments: identical policy contract to to_srt -- a segment without a measured span, or whose span quantizes to zero milliseconds on the output grid, raises by default (SubtitleRenderingError), and the caller opts into "omit" (renderable cues only) or "collapse" (one synthetic whole-text cue) explicitly. segments is None uses the whole-text fallback under every policy; segments == [] always yields zero cues; the synthetic cue carries no speaker label.