STT

stt.Transcriber

A lazily-loaded transcribe.cpp model with a single serialized compute lane.

Usage

Source

stt.Transcriber(
    variant,
    *,
    quant=DEFAULT_QUANT,
    backend="auto",
    idle_s=300.0,
)

One anyio.Semaphore(1) serializes every run, batch, and stream feed: the 0.x binding allows at most one in-flight compute per loaded model, and overlapping runs corrupt each other. A semaphore rather than a lock because a stream may be opened in one task and finalized or closed in another — lock release is task-affine, semaphore release is not, and max_value=1 makes an over-release raise instead of silently widening the lane. The model loads on first use and unloads after idle_s idle via ~athome.idle.IdleResource; an open stream holds both a use-reference and the compute lane for its whole lifetime, so the reaper cannot unload mid-stream and a stuck stream starves batch (bounded upstream by the activator).

Example

>>> stt = Transcriber("parakeet-tdt-0.6b-v2")
>>> (await stt.transcribe(pcm)).text  # doctest: +SKIP

‘hello world’

Methods

Name	Description
stream()	Open a streaming transcription that holds the compute lock for its whole lifetime.
transcribe()	Transcribe one float32 16 kHz mono PCM buffer into a Transcript.
transcribe_batch()	Transcribe several buffers in one dispatch; each slot is a Transcript or its own error.

stream()

Open a streaming transcription that holds the compute lock for its whole lifetime.

Usage

Source

stream(*, lookahead_ms)

transcribe()

Transcribe one float32 16 kHz mono PCM buffer into a Transcript.

Usage

Source

transcribe(pcm)

Raises

SttError

The buffer is invalid, or the native run failed (binding errors are mapped here so callers — the server’s 400 path included — never see a binding type).

transcribe_batch()

Transcribe several buffers in one dispatch; each slot is a Transcript or its own error.

Usage

Source

transcribe_batch(pcms)

Order-preserving with per-slot isolation: a slot that fails validation or transcription surfaces as an SttError in its position while the others return their transcripts. Only valid slots reach the native batch; a batch with no valid slot never wakes the model.

stt.SttStream

A live streaming transcription; use it as an async context manager to guarantee close.

Usage

Source

stt.SttStream(session, native, stack, load_ms)

Feed PCM chunks; each feed() returns only the newly committed segment deltas (stream-absolute seconds, monotone starts). finalize() flushes the tail and returns the whole Transcript without duplicating or dropping any fed segment. Streamed segment timing is derived from the binding’s audio_committed_ms watermark — the stream path exposes committed text, not native per-segment timestamps — so each committed delta spans from the previous watermark to the current one. A native failure inside feed() or finalize() closes the stream and raises SttError; an invalid chunk rejected before any native call leaves the stream open.

Methods

Name	Description
aclose()	Reset the native stream and release the compute lane and use-reference. Idempotent.
feed()	Feed a float32 16 kHz mono chunk; return only the newly committed segment deltas.
finalize()	Flush the final hypothesis, close the stream, and return the full transcript.

aclose()

Reset the native stream and release the compute lane and use-reference. Idempotent.

Usage

Source

aclose()

feed()

Feed a float32 16 kHz mono chunk; return only the newly committed segment deltas.

Usage

Source

feed(pcm)

Raises

SttError

The chunk is invalid (raised before any native call; the stream stays open), the stream is already closed, or the native feed failed (the stream is closed).

finalize()

Flush the final hypothesis, close the stream, and return the full transcript.

Usage

Source

finalize()

Raises

SttError

The stream is already closed, or the native finalize failed; the stream is closed either way.

stt.Transcript

A fully materialized transcription.

Usage

Source

stt.Transcript(text, segments, words, load_ms, language=None)

Every offset is in seconds (the native t0_ms/t1_ms are divided once, at the engine boundary). load_ms is the model’s first-party cold/warm load timing for this run, carried through so callers can size their own cold-start budgets. language is the model-reported language tag, None where the path exposes none (streaming).

Parameter Attributes

text: str

segments: tuple[Segment, …]

words: tuple[Word, …]

load_ms: float

language: str | None = None

Example

>>> transcript.text

‘hello world’

>>> transcript.segments[0].start

0.0

stt.Segment

A contiguous run of speech with its span in seconds and the words it covers.

Usage

Source

stt.Segment(text, start, end, words=())

Parameter Attributes

text: str

start: float

end: float

words: tuple[Word, …] = ()


stt.Word

One recognized word with its span in seconds from the start of the audio.

Usage

Source

stt.Word(text, start, end)

Parameter Attributes

text: str

start: float

end: float

stt.VARIANTS

stt.VARIANTS: tuple[str, …] = (
    "parakeet-tdt-0.6b-v2",
    "parakeet-unified-en-0.6b",
    "granite-speech-4.1-2b",
    "moonshine-tiny",
    "parakeet-tdt-0.6b-v3",
    "whisper-large-v3-turbo",
    "nemotron-speech-streaming-en-0.6b",
)


stt.gguf_path()

Materialize one quant of variant from the HF cache and return its .gguf path.

Usage

Source

stt.gguf_path(variant, quant=DEFAULT_QUANT)

Downloads only the matching quant (allow_patterns) at the pinned revision, then resolves the exact <variant>-<quant>.gguf file inside the snapshot.

Parameters

variant: str

An enrolled VARIANTS name.

quant: str = DEFAULT_QUANT


The GGUF quantization tag (e.g. "Q8_0", "F16").

Returns

Path

The local path of the .gguf weights file.

Raises

SttError

variant is not enrolled, or no <variant>-<quant>.gguf exists in the repo.

stt.decode()

Decode any audio container to 16 kHz mono float32 PCM via an ffmpeg subprocess.

Usage

Source

stt.decode(data)

ffmpeg reads a seekable temp copy of data (so trailing-moov m4a/mp4 — an iMessage voice note — decodes) and writes f32le to stdout. This is server/CLI-only; the in-process engine wrapper takes already-decoded PCM.

Parameters

data: bytes

The encoded audio bytes (wav, m4a, mp3, …).

Returns

array.array

A float32 array.array of 16 kHz mono samples.

Raises

SttError

ffmpeg exited non-zero or produced no audio.

stt.f32_from_s16()

Convert little-endian signed-16-bit PCM to float32 samples in [-1.0, 1.0).

Usage

Source

stt.f32_from_s16(data)

This is the single s16 → f32 conversion point: the decode pipeline emits s16le mono 16 kHz, the native binding wants float32, and every caller routes through here rather than dividing inline.

Parameters

data: bytes

Raw little-endian int16 PCM bytes.

Returns

array.array

A float32 array.array of the same sample count.

stt.SttServeSettings

The [serve.stt] section: the served variant, quant, bind address, and idle window.

Usage

Source

stt.SttServeSettings()

Env overrides derive from the section as ATHOME_SERVE_STT_<FIELD> (init kwargs > env > ~/.athome/config.toml > defaults).

Example

>>> load(SttServeSettings).port  # doctest: +SKIP

8403

stt.SttServer

The transcription app: one ~athome.stt.engine.Transcriber behind an allowlist of routes.

Usage

Source

stt.SttServer(settings)

GET /v1/models and GET /health answer from SttServeSettings without touching the model, so a health probe never loads weights; only POST /v1/audio/transcriptions decodes audio and runs the model, and the lifespan reaps it once idle.

Example

>>> server = SttServer(load(SttServeSettings))  # doctest: +SKIP
>>> uvicorn.run(server.app, host="127.0.0.1", port=8403)  # doctest: +SKIP

Methods

Name	Description
health()	Report liveness from configuration alone; never loads the model.
models()	List the one configured model without waking it.
transcribe()	Decode the uploaded file and return its transcript in the requested response_format.

health()

Report liveness from configuration alone; never loads the model.

Usage

Source

health(request)

models()

List the one configured model without waking it.

Usage

Source

models(request)

transcribe()

Decode the uploaded file and return its transcript in the requested response_format.

Usage

Source

transcribe(request)

stt.serve_stt()

Run the STT server under uvicorn, binding the inherited fd or the configured host/port.

Usage

Source

stt.serve_stt(*, fd=None)

Parameters

fd: int | None = None

A pre-bound listener fd to serve on (the activator’s {LISTEN_FD} handoff); None binds SttServeSettings’s host/port directly.

stt.SttError

Raised when a transcription cannot be produced (bad input, an unknown variant, a decode failure).

Usage

Source

stt.SttError()