## STT
## stt.Transcriber
A lazily-loaded transcribe.cpp model with a single serialized compute lane.
Usage
``` python
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
``` python
>>> stt = Transcriber("parakeet-tdt-0.6b-v2")
>>> (await stt.transcribe(pcm)).text # doctest: +SKIP
```
'hello world'
#### Methods
| Name | Description |
|----|----|
| [stream()](#athome.stt.Transcriber.stream) | Open a streaming transcription that holds the compute lock for its whole lifetime. |
| [transcribe()](#athome.stt.Transcriber.transcribe) | Transcribe one float32 16 kHz mono PCM buffer into a [Transcript](stt.md#athome.stt.Transcript). |
| [transcribe_batch()](#athome.stt.Transcriber.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
``` python
stream(*, lookahead_ms)
```
##### transcribe()
Transcribe one float32 16 kHz mono PCM buffer into a [Transcript](stt.md#athome.stt.Transcript).
Usage
``` python
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
``` python
transcribe_batch(pcms)
```
Order-preserving with per-slot isolation: a slot that fails validation or transcription surfaces as an [SttError](stt.md#athome.stt.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
``` python
stt.SttStream(session, native, stack, load_ms)
```
Feed PCM chunks; each [feed()](stt.md#athome.stt.SttStream.feed) returns only the newly committed segment deltas (stream-absolute seconds, monotone starts). [finalize()](stt.md#athome.stt.SttStream.finalize) flushes the tail and returns the whole [Transcript](stt.md#athome.stt.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()](stt.md#athome.stt.SttStream.feed) or [finalize()](stt.md#athome.stt.SttStream.finalize) closes the stream and raises [SttError](stt.md#athome.stt.SttError); an invalid chunk rejected before any native call leaves the stream open.
#### Methods
| Name | Description |
|----|----|
| [aclose()](#athome.stt.SttStream.aclose) | Reset the native stream and release the compute lane and use-reference. Idempotent. |
| [feed()](#athome.stt.SttStream.feed) | Feed a float32 16 kHz mono chunk; return only the newly committed segment deltas. |
| [finalize()](#athome.stt.SttStream.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
``` python
aclose()
```
##### feed()
Feed a float32 16 kHz mono chunk; return only the newly committed segment deltas.
Usage
``` python
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
``` python
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
``` python
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
``` python
>>> transcript.text
```
'hello world'
``` python
>>> transcript.segments[0].start
```
0.0
## stt.Segment
A contiguous run of speech with its span in **seconds** and the words it covers.
Usage
``` python
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
``` python
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
``` python
stt.gguf_path(variant, quant=DEFAULT_QUANT)
```
Downloads only the matching quant (`allow_patterns`) at the pinned revision, then resolves the exact `-.gguf` file inside the snapshot.
#### Parameters
`variant: str`
An enrolled [VARIANTS](stt.md#athome.stt.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 `-.gguf` exists in the repo.
## stt.decode()
Decode any audio container to 16 kHz mono float32 PCM via an ffmpeg subprocess.
Usage
``` python
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
``` python
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
``` python
stt.SttServeSettings()
```
Env overrides derive from the section as `ATHOME_SERVE_STT_` (init kwargs \> env \> `~/.athome/config.toml` \> defaults).
#### Example
``` python
>>> load(SttServeSettings).port # doctest: +SKIP
```
8403
## stt.SttServer
The transcription app: one `~athome.stt.engine.Transcriber` behind an allowlist of routes.
Usage
``` python
stt.SttServer(settings)
```
`GET /v1/models` and `GET /health` answer from [SttServeSettings](stt.md#athome.stt.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
``` python
>>> server = SttServer(load(SttServeSettings)) # doctest: +SKIP
>>> uvicorn.run(server.app, host="127.0.0.1", port=8403) # doctest: +SKIP
```
#### Methods
| Name | Description |
|----|----|
| [health()](#athome.stt.SttServer.health) | Report liveness from configuration alone; never loads the model. |
| [models()](#athome.stt.SttServer.models) | List the one configured model without waking it. |
| [transcribe()](#athome.stt.SttServer.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
``` python
health(request)
```
##### models()
List the one configured model without waking it.
Usage
``` python
models(request)
```
##### transcribe()
Decode the uploaded `file` and return its transcript in the requested `response_format`.
Usage
``` python
transcribe(request)
```
## stt.serve_stt()
Run the STT server under uvicorn, binding the inherited `fd` or the configured host/port.
Usage
``` python
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](stt.md#athome.stt.SttServeSettings)'s `host`/`port` directly.
## stt.SttError
Raised when a transcription cannot be produced (bad input, an unknown variant, a decode failure).
Usage
``` python
stt.SttError()
```