# Utterform 0.6.0 — Live Dictation

Speak and see text appear at your cursor while the microphone is still recording.
**This first Live Dictation release targets Windows and Omarchy/Hyprland.**

## Choose your cloud model

Open **Settings → Voice → Cloud transcription model**:

- **GPT Transcribe:** the existing recording → transcription → optional transformation
  → delivery workflow, unchanged and still the default for existing installations.
- **GPT Live Transcribe:** continuous audio streaming and append-only text at the cursor.
  Uses your saved OpenAI key plus the same vocabulary, language hints and recording context.
  Live requires network access and API access to `gpt-live-transcribe`.

Live is **Plain only**: no Clean/Polish pass and no retrospective edits in another app.
Local Whisper remains the existing offline recording workflow; it does not become streaming.

## How to use Live

1. Select GPT Live Transcribe in Settings and close Settings.
2. Put the cursor in the target application's text field.
3. Press your dictation key and wait for the recording start cue, then speak.
4. Press the key again to finish. Already typed text is **not** pasted again.

Windows uses the configured global dictation key. On Omarchy, retain the Hyprland
binding for `utterform --toggle`; the new Live input backend does not require `wtype`.
Starting from inside Utterform is intentionally not used for external Live input,
because the target field must keep focus.

## Focus and text preservation

- Observed target/window loss stops insertion for the rest of that recording, including
  a quick switch away and back. Transcription can continue in Utterform for recovery.
- No automatic focus restoration, reconnect replay, backspacing or whole-text retyping.
- Line breaks and tabs become spaces; no Enter key is pressed, so Live does not submit
  a chat message or execute a terminal command automatically.
- Final transcript revisions remain visible in Utterform without modifying already
  inserted text. Interrupted or uncertain input is never automatically retried.
- Clipboard and File remain optional finish-time outputs. Copy copies the full
  transcript: check the existing target text before pasting after a partial delivery.
- Audio and typing queues are bounded; connection, microphone and delivery failures
  are surfaced while received text remains available.

## Platform scope and known limits

- **Windows:** Unicode SendInput plus native foreground/control/desktop-change
  observation. An ordinary process cannot type into an elevated administrator window.
- **Omarchy / Hyprland:** a persistent Wayland virtual keyboard and Hyprland IPC
  focus observer. Missing/ambiguous seat, protocol or focus observation disables
  Live input rather than falling back to X11.
- **macOS, GNOME/KDE and X11 Live:** not included. macOS Live will be a separate
  development/test effort (a future version such as 0.7); the macOS download retains
  the existing finished-recording functionality.

Keep the cursor and target field unchanged and avoid typing while dictating. Neither
platform can reliably identify every browser-tab, field, selection or cursor change
inside the same window. Applications can reject synthetic input; OS/compositor receipt
is not confirmation of actual text insertion. Focus checks and injection are not one
atomic operation. Terminals, special editors, popups and input methods need practical
compatibility testing. This release does not promise universal application coverage.

## Verification and first-use testing

Automated coverage includes settings migration, Live UI and transcript recovery,
chunk-independent stereo/mono resampling, control-character protection, transcript
ordering/finalization, cancellation, and offline loopback WebSocket streaming/failure
cases. The release pipeline runs platform checks and packages the desktop downloads.

**Real microphone → OpenAI Live → target-app tests on Windows and Omarchy are still
pending user testing.** Offline protocol tests and successful builds are not a claim
that every application has been verified. In particular, check first characters,
Unicode, focus changes, stop/start and longer dictations on your Omarchy desktop.

The existing ribbon animation is retained. A floating mini-window/avatar is not part
of 0.6.0. Windows binaries remain unsigned; macOS packages remain ad-hoc signed.