@nhtio/adk/batteries/specialists/_shared

Structural contracts and normalization helpers shared by the on-device specialist batteries (STT / OCR / caption).

Remarks

This module imports nothing from @nhtio/adk core — not even a type-only import — per CONTRIBUTING.md → Design Decisions → #13 "Battery design — no concrete core-class coupling", tier 2 (locally-declared structural duck-types). A specialist adapter is handed media at runtime (an image to caption, an audio clip to transcribe) but never constructs a Media itself, so it has no genuine reason to import the class: SpecialistMediaLike declares the exact shape it reads (mimeType + asBytes()), and a real core Media instance satisfies it automatically, with zero import edge between the specialists domain and core.

defaultDecodeAudio is the one capability a specialist adapter cannot perform itself (turning arbitrary container bytes into PCM) — it lazily imports the optional audio-decode peer (already a package dependency, mirroring src/batteries/media/engines/audio_decode.ts) rather than requiring every consumer to inject a decoder. Consumers who want a different decode path (or want to avoid the peer entirely) inject their own DecodeAudioFn.

Interfaces

Interface	Description
SpecialistBytesInput	Raw bytes plus an optional MIME type — the plain-object form of image/document input.
SpecialistMediaLike	Structural duck-type of core Media: the exact shape a specialist adapter reads off a media value — its declared MIME type, and an async accessor for its raw bytes.
SpecialistPcmInput	Already-decoded mono PCM audio at a known sample rate — bypasses container decoding entirely.

Type Aliases

Type Alias	Description
DecodeAudioFn	Injected audio-decode seam: turns encoded container bytes into mono PCM at the container's source sample rate. Consumers may swap this for their own decoder (a different codec library, a cached/pre-warmed instance, or a test double) without the specialists domain ever depending on a concrete implementation.
SpecialistAudioInput	Any of the forms a specialist adapter accepts as audio input: an encoded container (any SpecialistImageInput form — bytes, bytes+mime, or media-like) that the adapter decodes via a DecodeAudioFn, or pre-decoded SpecialistPcmInput that skips decoding.
SpecialistImageInput	Any of the three forms a specialist adapter accepts as image/document input: a bare Uint8Array (MIME type unknown), a SpecialistBytesInput record (bytes + declared MIME), or a SpecialistMediaLike (a real Media or any duck-typed equivalent).

Variables

Variable	Description
defaultDecodeAudio	Default DecodeAudioFn: lazily imports the optional audio-decode peer, decodes the container, then downmixes to mono via downmixToMono.

Functions

Function	Description
isPcmInput	Narrows input to SpecialistPcmInput — true when it carries a Float32Array pcm field and a numeric sampleRate field.
toBytes	Normalizes any SpecialistImageInput form to plain bytes plus an optional MIME type.