Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

Utterance records

One typed record of numbers per committed spoken utterance (utterance.v1): its timings, levels and prosody, the device key that keeps baselines apart, the ADR 0044 rules (off by default, never audio or words, computed after the commit), the Admin's per-day Utterances row and the fields later slices append.

Living doc, checked against the code 2026-11-14

utterance.v1 — one typed record per committed spoken utterance

  • Status: built, off by default ([utterance] rows). The record, its switch and its Admin read. Nothing changes behavior on it yet. Adaptive endpointing (a shadow) shares its prosody estimator, not the record.
  • The types: UtteranceRecord and its blocks, AdminUtterances and AdminUtteranceDevice, in crates/protocol/src/utterance.rs. ts-rs generates the TypeScript bindings into packages/protocol.
  • The writer: crates/voice_gateway/src/utterance.rs.

The rules (ADR 0044)

  • Off by default. [utterance] rows = false. Off, a session allocates no ring, keeps no counter and writes no row, and the Admin row is absent. On, each session keeps a 12 s, 16 kHz mic ring in memory, overwritten, never stored.
  • Numbers only. A record holds numbers, closed words and the channel’s labels. It never holds audio or a word of the transcript. The first partial is held in memory until the commit, to say whether the commit kept it, then dropped. Nothing in the record is a diagnosis. Nothing in it changes behavior until the metric admission gate admits it.
  • Kept where it is heard. The record is a row of the gateway’s own session trace (utterance), on the gateway’s host. It never goes into git, a receipt or a report. Receipts carry aggregates.
  • Per device, never mixed. Every record names its device (device.key). Every baseline or aggregate is kept per key. A dedicated microphone on an audio interface is the reference channel for level and voice-quality numbers. A laptop’s built-in mic is a room and context channel, because the OS AGC flattens its loudness.
  • Off the dispatch path. At the commit the gateway reads the counters and the ring’s sample index (microseconds). The blocking pool copies the utterance out of the ring, measures it and writes the row. Each record carries its own cost (compute_us).

The record

One row per committed spoken utterance. A typed commit has no audio and gets no row. The trace row’s event is utterance and its data is the record:

field content
schema utterance.v1
turn_id the committed turn’s id, to join the session’s other rows
committed_at_ms the commit, Unix ms
device key (<kind>:<source>, the baseline key), kind, role, source, room?, sample_rate_hz
timing see below
text chars, words: the transcript’s size, never its words
level see below
prosody see below
compute_us the blocking task’s cost, microseconds

timing, from the recognizer’s metrics rows:

field content
segment_ms the last speech segment’s length (stt_speech_end)
segments speech segments closed since the previous commit
endpoint_reason the endpoint’s closed word (hold_expired, no_hold, max_segment, flushed, held_chunk)
hold_ms the end-of-utterance hold in force
decided_after_end_ms the speech end to the endpoint’s decision (stream time)
speech_end_to_commit_ms the speech end to the commit: the turn budget’s speech_end_to_commit leg
partials partial transcripts since the previous commit
first_partial_kept whether the commit begins with the first partial’s words; absent with no partial
since_last_commit_ms the session’s previous commit to this one; absent on the first

level, over the utterance’s 16 kHz audio (dB re full scale, 20 ms frames):

field content
audio_ms the audio read: the segment, clipped to the ring
peak_dbfs the loudest sample
level_dbfs the median level of the active frames (within 35 dB of the loud ones)
floor_dbfs the 10th-percentile level over the segment and the 250 ms before it
snr_db level_dbfs - floor_dbfs
clipped_share samples at or over 0.999 of full scale

prosody, the live estimator’s numbers: speech_ms, voiced_share, reliable, chars_per_s, pause_mean_ms, monoloudness_db, monotony_st, f0_spread_st. The estimator is crates/voice_gateway/src/operator_affect/prosody.rs, the same Rust YIN the operator-affect row uses, so one baseline serves both. Nothing reads the f0 fields as behavior.

A new field is optional and appended at the end of its block, so a v1 reader keeps working.

The Admin’s Utterances row

AdminPerformanceSnapshot.utterances, in the Performance section’s answer, holds:

  • the UTC day and the day’s record count;
  • per device, at most eight (later keys count under other): the record count, and over its newest 500 records the medians of speech_ms, speech_end_to_commit_ms, the level, the signal-to-floor ratio (tenths of a dB) and the speaking rate (tenths of a character per second).

The row is absent while [utterance] rows is off. The socket’s bound (validate_performance_snapshot) refuses a row whose devices do not add up to its count. The fixture answer is in benchmarks/fixtures/admin-sections.v1.json.

Rollback

Set [utterance] rows = false (the default) and restart: no ring, no row, no Admin row. An older Admin reads the field as absent.

Was this page helpful?