hex/sdk/.changeset/api-timestamps.md
Dax a38f6cb709
local api: native segment and word timestamps behind a labs toggle (#1658)
* local api: native segment and word timestamps behind a Labs toggle

POST /transcriptions takes timestamps=none|segment|word. Absent means
none and the response is unchanged. segment adds timestampGranularity
and segments; word adds segments and words, with text, startMs, and
endMs in whole milliseconds from the submitted audio's start.

The times are the model's own: the GGUF capabilities metadata decides
what it can produce, Apple Speech gives segments, and nothing estimates
or downgrades a level. A model without the requested level answers 422
unsupported-timestamps, decided after the model resolves on both the
shared dictation engine and the service's own copy. Chunked long clips
add each chunk's offset once from its sample position, and ends padded
past the decoded audio are clamped to durationMs.

Labs › Timestamps in API transcripts (labs.api_timestamps) gates it and
is off by default; off, a timed request answers 403 timestamps-disabled
before the audio body is read. The SDK takes timestamps and decodes the
new fields.

* local api timestamps: review follow-ups

* local api timestamps: correct embedded helper docs

* local api timestamps: align labs doc wording with the service spec
2026-11-10 17:07:52 -05:00

662 B
Raw Permalink Blame History

@kitlangton/hex
minor

transcribe() takes timestamps: "segment" | "word" and returns the speech model's own segments and words (TimedText: text, startMs, endMs, in milliseconds from the clip's start) with timestampGranularity, when Labs › Timestamps in API transcripts is on. The running app reads the lab live; the embedded helper loads no settings, so it reads the saved labs.api_timestamps once, on its first request, and a change takes effect after it restarts. "none" and absent send no parameter and keep the response as before. A model without that level answers unsupported-timestamps; the times are never estimated.