Dotfiles_ArchAP/docs/quickshell-sway-hyprwhspr-integration-v1.md

QUICKSHELL_SWAY_HYPRWHSPR_INTEGRATION_V1

Integration implemented on 2026-11-07. Real recording tests remain manual.

Local audit

• Arch package hyprwhspr 1.52.1-1; hyprwhspr --version prints hyprwhspr unknown.
• System QuickShell 0.3.2; running instance uses 0.3.2 from ~/.local/opt/quickshell-qt612-popup/bin/quickshell (labfy local Qt 6.12 popup fix).
• hyprwhspr --help and hyprwhspr record --help both print the top-level help.
• record status stdout is exactly [INFO] Status: Idle\n, stderr empty, exit 0. This remains true with the service stopped and with an absent runtime directory. One local measurement: 98 ms; systemctl --user is-active hyprwhspr.service took 7 ms and returned inactive\n, exit 3.
• Installed CLI source emits [INFO] Status: Recording in progress\n when $XDG_RUNTIME_DIR/hyprwhspr/recording_status contains true. This recording output was verified in installed source and mocked tests, not by recording audio.
• record toggle sends normal start/stop commands. Installed source can print [ERROR] while returning 0; the backend checks both code and expected output.
• No Hyprwhspr binding found in Sway config/bind or /etc/sway/config.d. User config selects push_to_talk, with no primary shortcut override; installed default is SUPER+ALT+D. Actual keyboard operation remains manual.
• User service was inactive before and after integration. No service/config, shortcut, model or transcription changes were made.

Architecture and behavior

One HyprwhsprService in ShellRoot serves every Bar. Each RightStatusArea places a 26 x 26 indicator between network and Bluetooth. Nerd icon is 18 px, corner radius 4 px, with existing Theme and StatusTooltip components. No extra bar, terminal or action panel is created; the existing tooltip surface is reused for hover text.

The backend serializes availability checks, status reads and toggles using one asynchronous Process. Availability must be confirmed before status is accepted. Recording is only confirmed by the exact installed CLI response; there is no locally inverted recording boolean. The click lock lasts through command completion and the confirming read. Clicks are ignored during authentication. Errors never masquerade as recording.

Native recording_status notifications accelerate external keyboard and automatic changes. A single-shot timer starts after the preceding cycle finishes: 1000 ms at idle/error, 400 ms at recording/processing, plus command latency. At most one pending refresh is retained. Each command uses GNU timeout with 3 seconds before TERM and another second before KILL. No shell is invoked. A whole read cycle can require two commands; refresh timing is not a hard real-time guarantee.

visualizer_state is an additional native, optional signal. Installed mic_osd/runner.py writes processing/error/success labels and clears the file; FileView watches it without reading any transcript. A confirmed recording response has precedence. With CLI idle, processing displays a yellow mic and Transcription en cours; error displays a red warning. Missing marker, success, or another label does not invent a processing state. The service availability gate also applies to these labels. This mechanism depends on Hyprwhspr publishing its OSD marker and is not an independent transcription API.

Idle: muted grey mic, Dictée inactive. Recording: Theme.red (Mocha #f38ba8), Dictée en cours. Processing: Theme.yellow (Mocha #f9e2af). Unavailable/unreadable/command failure: red warning with a short fixed message. No animation. No command output, audio or transcript is logged by the backend. A read-only dictationStatus.state IPC returns status/tooltip/busy/cadence only.

Validation

• qmllint against installed Qt imports: all five changed/added QML files pass.
• git diff --check: pass.
• Production backend tested offscreen using isolated fake CLI executables and a temporary runtime directory; no windows and no live microphone access.
• Tests cover startup idle and already recording, external recording/stop, unavailable service/recovery, duplicate clicks, CLI failure with exit 0, unknown output, native processing/end, bounded slow command and recovery.
• Live existing bar reloaded successfully. IPC correctly reports service unavailable; no service restart or stop was performed.
• Captured bar region visually inspected: red warning between network and Bluetooth; other indicators remain visible. Radius/size/theme preserved.
• One live QuickShell instance remains, PID 2478 at validation time. Temporary offscreen test processes exit after testing. A stalled mocked command is bounded and repeated refresh requests coalesce.
• Existing log warnings about ControlCenter/DateCenter Keys attachments and I3 socket reconnection are outside this change; no new QML load error seen.
• Full live idle/recording/transcription, hover interaction and service outage during actual dictation have not been manually exercised.

Manual acceptance checklist

1. With Hyprwhspr running and idle, verify grey microphone and idle tooltip.
2. Left click: verify red only after recording is actually confirmed.
3. Left click again: normal transcription and insertion; never cancel.
4. Start with the existing keyboard shortcut: red updates automatically.
5. Stop with the keyboard: indicator follows actual state.
6. If native processing marker is published, verify yellow then idle/error.
7. When convenient, stop/restart the service and verify red warning/recovery without interruption or duplication of QuickShell.

Do not mark these steps passed until performed with user authorization. Pre-existing trier-photos changes and its untracked backup are unrelated and were preserved. No staging, commits or publication performed.