Dictation buttonPro
Speech to text in the field: a mic that listens, interim words in grey that settle when final, inserted at the caret, with cancel and an error state.
oxyn add dictation-buttonThe preview stays free for everyone. Pro opens the code of every Pro component, screen, agent-app template, block and kit, plus the Pro CLI.
Rendered from Rust at build time · goes live when visible
When to use
- The user wants to talk instead of type: dictate a long prompt, think out loud, or answer an agent's question with their hands busy.
- Two different intents share the composer and must look different (research note 04 found most chat apps ship them side by side: a mic for dictation and a waveform button for live voice):
When not to use
- Send, stop, queue and steer in one control, in twelve styles: use Send control instead.
- Messages typed while the agent works wait above the composer: use Queue stack instead.
- Prompt composer with model picker, voice input, app connections and approval request: use Chat Composer instead.
Installation
Dictation button is part of Oxyn Pro; the preview is free. Pro items install with the oxyn CLI once your licence is signed in; until then Pro members copy the code from this page.
oxyn add dictation-buttonUsage
The preview is free. Pro opens the code of every Pro component, screen and template.
Examples
Field
Mic inside the field; words stream in grey.
Code Pro
The preview is free. Pro opens the code of every Pro component, screen and template.
Pill
Round mic beside the field.
Code Pro
The preview is free. Pro opens the code of every Pro component, screen and template.
Insert
Dictation inserts at the caret.
Code Pro
The preview is free. Pro opens the code of every Pro component, screen and template.
Error
Recognition failed.
Code Pro
The preview is free. Pro opens the code of every Pro component, screen and template.
API reference
DictationButton
| Prop | Type | Default | Description |
|---|---|---|---|
now_msrequired | u64 | — | Host clock (ms). |
script | String | "add a thirty second leeway to the token expiry check and rerun the auth tests" | What the "speaker" says (demo script). |
wpm | f32 | 150.0 | Words per minute. |
value | String | Default::default() | Initial text. |
fail | bool | Default::default() | Recognition fails after a second. |
placeholder | String | "Type or dictate…" | Placeholder. |
variant | String | "field" | Variant: `field` or `pill` (the mic as a round button beside the field). |
on_change | EventHandler<String> | — | Text changed. |
Read from the Rust signature and doc comments.
Keyboard interactions
| Key | Action |
|---|---|
| EnterorSpace on the mic | Start or stop dictation |
| Escape | Cancel and drop the interim words |
Accessibility
- The mic button is named for its action: “Dictate” or “Stop dictation”.
- Interim words are aria-hidden; a polite region announces listening, done and cancel.
From the spec
- Labels per state: Idle "Start dictation"; Recording "Stop dictation and insert text" (✓) and "Cancel dictation" (✕); PTT "Hold to dictate"; Denied "Microphone blocked. Activate to see how to allow it"; Disabled "Dictation unavailable: <reason>"; voice-mode "Start voice conversation".
- Live region (polite): "Listening", "Didn't catch anything", "Transcribing", "Inserted 24 words", "Dictation cancelled", "Language: Spanish". Assertive only for permission denied and device errors. Partial transcript text is not announced word by word (it would talk over the user); the final text is readable in the input after confirm.
- Recording indicator has a text equivalent ("Recording, 0:07") exposed on the strip, and the
aria-pressed/toggled state on the mic. - Contrast: waveform bars ≥ 3:1 against the strip background; partial words at 60 % opacity must still meet 4.5:1 (darken the base ink token if needed); danger and warning tones carry an icon, never colour alone.
- Focus order: mic → (strip appears) language chip → ✕ → ✓. Focus moves to ✓ on start only for pointer starts; keyboard starts keep focus in the input so Enter/Esc work. On end, focus returns to where dictation began.
- Reduced motion: see timing table; level bar always present.
- Screen-reader users and dictation often already use OS dictation; the component must not steal OS dictation hotkeys.
Motion & interaction
- Mic hover / press. Hover tints the 32 px hit area (icon 18 px). Press scales the glyph 0.94. A press longer than 200 ms (
hold_threshold, proposed) is push-to-talk; shorter is a toggle. - Composer → strip morph. The input text crossfades out while the strip fades and scales in from the mic's x-position (transform-origin at the mic). The send ↑ morphs to ✓ in the same frame, reusing the send control's glyph morph. Draft text that existed before dictation is kept: the transcript is inserted at the caret on confirm, never replacing the draft.
- Waveform. Bars 2 px wide, 2 px gap, 2–24 px tall, rounded caps. New bars append at the playhead (a 1 px accent line at the write head). When the strip is full, history scrolls left at a constant rate so the playhead stays at 85 % of the strip width. Bar height = smoothed RMS level mapped from −60…0 dBFS (attack 30 ms, release 150 ms, proposed).
- Level / noise meter. The breathing dot doubles as a level meter (scale 1.0–1.35 with level). Two hints, each shown once per session (proposed thresholds): Too quiet — speech-band level stays under −45 dBFS for 3 s while Capturing; Noisy room — noise floor above −35 dBFS for 2 s in Listening. Clipping (> −1 dBFS) paints the top 2 px of the bar in warning tone.
- Live transcript. Region above the strip, 14 px text, 1–3 lines visible (grows upward, then scrolls with a top fade mask 16 px). Partial words blur-in (4 px → 0) at 60 % opacity; when the recogniser finalises them they settle to 100 % without moving. Words never reflow backwards once final; partials may be replaced in place.
- Timer.
0:07at the strip's leading edge, tabular figures; at 4:30 of a 5:00 cap it turns warning tone and shows "30 s left"; at the cap it auto-confirms (goes toFinalizing). - Confirm. Final transcript translates down into the input baseline and becomes ordinary draft text; the strip collapses; ✓ morphs back to ↑ (or to the busy-state control). Optional Cuelume-style success tick sound [R110] (off by default).
- Cancel. Strip shrinks back into the mic; transcript fades; no shake (cancel is not an error).
- No-input. Waveform dims, hint slides up 8 px. The mic stays open for 2 s more in case speech starts (then closes), so "Try again" rarely needs a second permission round-trip.
- Language switch. A 2-letter chip (
EN) at the strip's trailing edge opens the language menu (recent 3 on top, then Auto-detect, then all). Switching mid-capture closes the current segment and opens a new one; text so far stays. RTL languages flip the transcript region's direction per segment. - Permission denied. Mic does one 2-cycle 4 px shake, then shows the slash. "How to allow" opens platform-specific steps (browser site settings vs. macOS Privacy & Security, proposed copy).
- Voice-mode entry. Waveform-bars button beside the mic. Press → the whole composer row morphs into the voice-session bar (height grows by 8 px max, upward). Exit returns the draft untouched.
Timing
Easing names refer to the composer motion tokens in composer.md.
| Transition | Duration | Easing / spring | Notes |
|---|---|---|---|
| Mic hover tint | 100 ms | ease.out | |
| Mic press scale 1 → 0.94 → 1 | 80 ms down, 140 ms up | ease.out / spring.snap | |
| Tap vs hold decision | 200 ms | — | hold_threshold, proposed |
| Input fade-out → strip in | 120 ms out, 180 ms in, 40 ms overlap | ease.out | strip scales 0.96 → 1 from mic origin |
| ↑ → ✓ glyph morph | 160 ms | spring.snap (critically damped) | same as send control |
| "Starting mic…" text appears | delay 300 ms, fade 120 ms | ease.out | only if Arming is slow |
| Waveform frame rate | 30 fps (60 fps in expressive) | — | shared motion clock |
| Level smoothing | attack 30 ms, release 150 ms | exponential | proposed |
| Breathing dot (Listening) | 1600 ms loop | sine | scales with level while Capturing |
| Partial word blur-in | 140 ms, 30 ms stagger (cap 6 words) | ease.out | blur 4 → 0 px, opacity 0 → 0.6 |
| Partial → final settle | 120 ms | ease.out | opacity 0.6 → 1, no movement |
| No-input timeout | 8 s silence in Listening | — | proposed; mic closes 2 s after hint |
| No-input hint slide | 160 ms | ease.out | y +8 → 0 |
| Max dictation / warning | 5:00 cap, warn at 4:30 | — | proposed, app-configurable |
| Finalizing timeout | 15 s | — | then TranscriptionError |
| Confirm: transcript → input | 200 ms | ease.in-out | strip collapse 160 ms, starts at 80 ms |
| Cancel: strip → mic | 140 ms | ease.in | transcript fade 100 ms |
| Permission-denied shake | 240 ms, 2 cycles, 4 px | linear | |
| Language chip flash | 1 frame accent + 200 ms fade | ease.out | |
| Voice-mode morph | 240 ms | spring.soft | owned jointly with voice-session |
| Reduced motion | all morphs become 80 ms opacity crossfades; waveform replaced by a single horizontal level bar updated at 10 fps (level is information, so it stays); no blur-in, no shake (slash + text only); breathing dot static | — | — |
Responsive behaviour
- The field grows to its container; the mic never wraps.
Edge cases (spec)
- Long dictation. Transcript region caps at 3 visible lines then scrolls; on confirm the draft may exceed the input's max rows, so the input-shell's own overflow applies. 5-min cap prevents runaway.
- Existing draft. Insert at caret with a single leading space if the char before the caret isn't whitespace; never overwrite a selection silently (selection is replaced only when the user started dictation with text selected — proposed "dictate to replace").
- Agent busy. Dictation works during
Thinking/Streaming/ToolRunning. Confirm inserts into the draft; the send control is then inWorkingWithDraftand itsbusy_actionapplies. WithInsertAndSend, the text goes to the queue as a normal queued message. - Awaiting approval / question card. Confirmed text answers the open card (send control
Answering). Saying "approve" is not treated as approval (proposed: no voice commands for consequential actions in v1). - Voice mode while agent speaks. Mic is
Disabled("Agent is speaking — tap to interrupt")unless the session supports barge-in; then the interrupt belongs to voice-session. - RTL / mixed scripts. Strip layout mirrors (timer trailing, chip leading). Transcript direction is per segment; bidi isolation around each segment.
- Tiny sizes. At 16–20 px the mic is glyph-only; the strip needs ≥ 160 px width, below that the variant falls back to
voice-input/pill. In a 28 px IDE row the waveform drops to 1 px bars, max 14 px tall. - Touch. 44 × 44 px minimum hit area. PTT on touch: hold ≥ 200 ms; slide up 48 px or off-target to cancel; haptic tick on start and on cancel (mobile, proposed).
- Slow network (server STT). Partials may lag: show the waveform immediately and keep a "Transcribing…" shimmer at the tail; never block capture on the network. Offline with server-only STT →
Disabled("Offline — dictation needs a connection"); on-device STT keeps working. - Very fast recogniser / very short utterance. Under 400 ms of speech with no text → treat as NoInput, not error.
- Device changes. Unplugging the active mic mid-capture →
DeviceError, transcript so far kept as draft. A new default device is not auto-adopted mid-capture (avoids recording the wrong room). - Window loses focus. Capture continues (it's a dictation, not a hover); the
notchPro variant or OS mic indicator is the reminder. Toggle mode keeps recording; PTT with a key ends on key-up even if focus moved (proposed). - Hotkey collisions. Every global candidate collides with some OS or IME shortcut (e.g. input switching), so Oxyn ships no global PTT default; apps set one. The in-composer hotkey is configurable and shown in the mic tooltip.
Notes for AI
- Import
DictationButtonfromoxyn_dioxusand includeCOMPOSER_CSSplus the token stylesheet once. - A GPUI version exists:
DictationElinoxyn_gpui. - Props to set first:
now_ms. - It reads a clock (
now) for live timers; pass one clock for the whole page rather than one per component. - Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.