Voice Assistant

Demo & usage

More examples

When to use

• A voice input surface where the user needs to know whether the microphone is actually being heard.
• A live transcript where the recogniser emits interim guesses that must not read as settled text.
• A call-style turn where the user has to be able to interrupt the assistant mid-sentence.

Async states

• loading
• error
• retry

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `levels`, `loading` and `error`.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• `[ambientLevels]` — the first second of capture, measured while nobody is talking — calibrates the silence threshold from the room. `SV_SILENCE_LEVEL` (0.04) is a guess about a quiet office: in a car, a café or a warehouse the ambient floor sits above it, so every frame reads as speech, the auto-stop never fires and the meter claims to hear a user who has not spoken. Derived from the 90th percentile of ambient rather than the mean (the mean sits under most of the room) and never from the maximum, so one cough cannot deafen the assistant for the session.
• The calibrated threshold is **capped at 0.35** and floored at 0.02. The cap is the important one: a café calibration would otherwise climb above ordinary speech and the assistant would stop hearing anybody at all — a worse failure than the one calibration fixes, and one the user cannot diagnose. When the cap is doing the deciding the component says so and tells the user to move somewhere quieter.
• `[consentRequired]` with two-way `[(consent)]` (`unknown` / `granted` / `declined`) gates capture behind an explicit 'this records your voice' prompt. The browser's microphone permission is not consent — it asks whether the page may use the microphone, not whether the user agrees to being transcribed, stored or sent to a third-party model. The gate is enforced in `dispatch`, the one entry point, so no control or host call routes around it, and it blocks `start` only: stop, interrupt and reset always work, because a gate that trapped a live microphone would be the opposite of what it is for.
• A **Recording** indicator (`role='status'`) shows whenever the microphone is open, in every variant, with no host opt-in. An indicator that appears only when somebody remembered to ask for it is not an indicator.
• Redaction, from the pack-wide policy (`X-2`): transcript segments AND the settled-text footer are masked — they are two renderings of the same words, so masking one would leave the secret six lines below where it was hidden. `copy: false` withdraws the footer entirely, because it exists to be selected and copied. People dictate what they cannot type one-handed: a card number read off the card, an address, a patient identifier. The mask covers every string that reaches the DOM, not only visible text: each segment's `aria-label` (what a screen reader reads instead of the text) and the settled-character count are built from the masked text too. The policy's `reveal` and `telemetry` flags are not read here, because there is nothing for them to govern: the component offers no unmask control and emits no analytics, and none of its outputs (`action`, `silenceDetected`, `retry`, `turnChange`, `consentChange`) carries transcript text. Telemetry of the transcript is therefore the host's own code, and the host should consult `svAiPrivacy().telemetry` there.
• `levels` (measured amplitude, 0–1) and `segments` are inputs defaulting to empty; import `DEMO_LEVELS` / `DEMO_TRANSCRIPT` for a demo.
• Three layouts via `variant`: `button` (the control and meter alone), `transcript` (plus the folded transcript) and `call` (plus interrupt and hang-up).
• The turn is a state machine — `idle`, `listening`, `thinking`, `speaking`, `denied` — driven by `start` / `stop` / `interrupt` / `reset`. `denied` is terminal until `reset`.
• `SV_SILENCE_LEVEL` (0.04, not zero) is the amplitude floor: a live microphone in a quiet room reads a non-zero noise floor, so a `> 0` test calls silence speech forever.
• The meter draws a 6 % floor while capturing, so a live-but-silent microphone is visibly live rather than indistinguishable from a dead one.
• `SV_LOW_CONFIDENCE` (0.6) flags settled text the recogniser was unsure about — never interim text, which is already drawn as provisional.

Best practices

• Do: Feed `levels` from a real AnalyserNode. A meter animated on a timer moves identically whether the microphone is live, muted or refused — which makes the one question it exists to answer the one question it cannot answer.
• Do: Mark interim segments with `final: false`. They render as provisional, and a final segment replaces its own running guess rather than following it.
• Don't: Do not let a `start` action climb out of `denied`. A refused microphone does not become available because the button was pressed again.
• Tip: Auto-stop on a run of quiet frames, never on the first one — the pause between two words is a quiet frame, and so is the breath before the important clause.

Accessibility

• The meter is `role="img"` with an accessible name stating whether input is being heard, not only drawn.
• A denied microphone gets a written explanation of where the browser hid the permission, not a dead-end "unavailable".
• The turn label and hint are text; the control reports what pressing it will do.