standard_asr

Open vocabulary for a reason that prevents explicit acquisition.

Raised when an explicit or implicit artifact acquisition fails.

Describe an external action needed before artifact acquisition.

Open vocabulary for an external action required from an operator.

Request information available before audio reaches an engine.

Describe one ordered artifact-acquisition progress update.

Callback that observes validated artifact progress updates.

Raised after acquisition succeeds but its progress callback fails.

Open vocabulary for an artifact operation's current phase.

Open vocabulary for artifact progress-count units.

Open vocabulary for aggregate inference readiness.

Report artifact requirements and aggregate inference readiness.

Report one logical artifact requirement for a resolved context.

Open vocabulary for one logical artifact requirement's state.

Raised when artifact status inspection fails unexpectedly.

Raised when required artifacts cannot support inference or warm-up.

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. 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 the current generation: 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 / artifact_status / acquire_artifacts), or the optional prepare engine method, returned an awaitable or a value outside its 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.)

An HTTPS display URL that Standard ASR never dereferences.

Raised when an engine's declared protocol cannot be used by this core.

The error reports a version compatibility boundary, not a missing Python attribute. It covers both directions: an engine on an older protocol line than the core supports, and an engine on a newer one. Generic consumers raise it before they inspect a member the declared protocol does not define.

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.

Gate ownership: the ProtocolCompatibilityError raises documented on the members below are kept by the standard's own checks -- they are not a duty every implementation's method body carries. ModelRegistry.create() refuses an engine on an unsupported protocol line before callers can reach these members, and EngineBase checks again at each entry as a second net; an implementation built directly on this protocol does not have to repeat those checks. A host that obtains an engine without the registry (direct construction, a custom loader, injection) MUST run require_engine_protocol on the object once before using it (AR.1).

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.