HootVoice — User Manual

Basic Usage

Place the cursor in any text field in your OS and press the recording hotkey (Ctrl+Shift+R by default). Speak and stop recording; the speech is transcribed and, if auto‑paste is enabled, inserted into that field.

Words that are often misrecognized can be corrected by adding replacements in Settings → Dictionary.

Local processing (no cloud)

HootVoice runs speech recognition entirely on your device. Audio is not sent to external servers.

• Privacy: meeting content and sensitive information never leave your machine.
• Performance: no network latency; speed depends on your CPU/GPU and model size.
• Cost: no API usage fees — fully free to use.
• Network note: only the initial Whisper model download uses the network. For offline use, pre‑place the ggml model under your app data models/ folder.

Quick Start

• Windows: run hootvoice.exe
• macOS/Linux: run ./hootvoice (works from dist/ builds as well)

On first run HootVoice downloads the selected Whisper model to your user config directory (default Large‑v3 ~3.1 GB). You can switch models in Settings → Speech Model.

The Whisper models are provided by OpenAI under the MIT License; review the Whisper license before redistributing models that you download with HootVoice.

Default controls:

• Toggle recording: Ctrl+Shift+R (configurable in Settings → General)
• Linux/macOS: send SIGUSR1 to toggle, SIGUSR2 to open Settings

Floating Toolbar

A tiny always‑on‑top window shows the current state and a record/stop button. It also has a Settings button and a drag handle to move it.

• States: Idle (○), Recording (● red), Processing (● yellow)
• Wayland: with the wayland_layer feature a sidecar (hootvoice-float) provides layer‑shell floating that behaves like a panel.

Tip: You can switch between Settings and the floating window via the Settings screen.

Settings

Open the Settings window from the floating toolbar or at launch (default). Tabs:

• General
  • Hotkey for recording, UI language, auto‑paste toggle
  • Show floating toolbar / Open model & dictionary folders
• Devices
  • Select input device/host and output device
  • Input level meter and sensitivity (gain)
  • Quick test recording to verify microphone levels
• Speech Model
  • Choose a preset (Tiny/Base/Small/Medium/Large‑v3) with quality/speed guidance
  • Download/apply the selected model; view the model folder
• Dictionary
  • Define replacements with standard form, aliases and Include conditions
  • Search, add/edit/delete and Apply to activate
• Logs
  • Show recording/processing/copy/paste logs with timestamps

Changes are saved automatically. Apply model/dictionary changes via the Apply button.

LLM Post-processing

Open the LLM tab in Settings and enable Enable LLM post-processing to send Whisper transcripts to a local LLM that can clean up punctuation, switch tone, or generate summaries.

• Set the API base URL and model name to match your OpenAI-compatible server (Ollama, LM Studio, etc.).
• Select one of the presets (format/summary) or define a custom prompt to tailor the output.
• If the request fails, HootVoice falls back to the raw Whisper transcript and logs the error.

See the LLM post-processing setup guide for full platform instructions and recommended models.

Recording Flow

1. Trigger recording via hotkey or toolbar
2. Speak; elapsed time and input level are shown
3. Stop to run transcription
4. The result is copied to the clipboard and pasted into the front app if enabled

Notes:

• On macOS, auto‑paste requires Accessibility + Automation permissions
• On Linux, auto‑paste requires wtype (Wayland) or xdotool (X11). Without them copy‑only still works.

Tips

• Use a smaller model (Tiny/Base/Small) to maximise speed on low‑power systems
• Linux/Windows: GPU acceleration via Vulkan improves performance greatly; install runtime/driver and glslc
• macOS: Metal/Core ML acceleration is used automatically by whisper‑rs

Troubleshooting

• Auto‑paste blocked on macOS
  • System Settings → Privacy & Security
  • Accessibility: enable “HootVoice”
  • Automation: allow “HootVoice” → “System Events”
• Linux auto‑paste does nothing
  • Install wtype (Wayland) or xdotool (X11). Otherwise only copy occurs.
• Vulkan build/runtime issues on Linux
  • Install glslc libvulkan-dev vulkan-tools mesa-vulkan-drivers (Ubuntu 24.04) and verify with vulkaninfo
• No microphone devices
  • Check aplay -l / arecord -l and your audio server configuration

Update

Download the latest release from the official site or distribution page and overwrite the existing application. Settings and models remain in your user data directory, so no reconfiguration is needed. There is currently no automatic updater.

Uninstall

Delete the application and, optionally, remove the user data directory to reclaim model space:

• Linux: ~/.config/HootVoice
• macOS: ~/Library/Application Support/HootVoice
• Windows: %APPDATA%\HootVoice

Advanced

• Waybar integration
  • HootVoice writes status to the OS‑standard config dir (e.g., ~/.config/HootVoice/status.json)
  • Create a Waybar custom module that reads this file periodically

Enjoy faster, hands‑free text input with HootVoice!