tomi
c2aea05000
- Document hush profiles subcommands and --profile flag in command table - Add Profiles section with file format, creation flow, and hotkey example - Expand configuration table with fireworks_api_key, provider fields, system_prompt - Add profile name completion via _hush_profiles helper in zsh completion - Add --profile/-p completion for toggle and stop commands - Add profiles subcommand completion
123 lines
4.1 KiB
Markdown
123 lines
4.1 KiB
Markdown
# Hush
|
|
|
|
A Linux speech-to-text daemon that records audio, transcribes it via the Groq or Fireworks Whisper API, cleans up the text with an LLM, and types the result into whatever window currently has focus.
|
|
|
|
The intended workflow: bind `hush toggle` to a global hotkey, press to start recording, press again to stop, and the transcribed text appears in your active application. Use profiles to switch behaviour per hotkey — e.g. one binding for normal dictation, another for translating speech into a shell command.
|
|
|
|
## Requirements
|
|
|
|
**Runtime dependencies:**
|
|
|
|
- [pw-record](https://pipewire.org/) (PipeWire) or `ffmpeg` (PulseAudio) — audio capture
|
|
- [wtype](https://github.com/atx/wtype) (Wayland) or [xdotool](https://github.com/jordansissel/xdotool) (X11) — text injection
|
|
- `notify-send` — desktop notifications
|
|
- A [Groq](https://console.groq.com/) or [Fireworks](https://fireworks.ai/) API key
|
|
|
|
**Build dependencies:**
|
|
|
|
- [.NET 10.0 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
sudo ./install.sh
|
|
```
|
|
|
|
This builds the project, installs the `hush` binary to `/usr/bin/hush`, sets up zsh tab-completion, and registers `hush.service` as a systemd (or OpenRC) user service.
|
|
|
|
To uninstall:
|
|
|
|
```bash
|
|
sudo ./uninstall.sh
|
|
```
|
|
|
|
## Setup
|
|
|
|
After installing, run the interactive setup wizard to configure your API key and preferences:
|
|
|
|
```bash
|
|
hush setup
|
|
```
|
|
|
|
Config is stored at `~/.config/hush/config` in TOML format.
|
|
|
|
## Commands
|
|
|
|
| Command | Description |
|
|
|---|---|
|
|
| `hush toggle` | Start recording if idle, stop and transcribe if recording |
|
|
| `hush start` | Start recording |
|
|
| `hush stop` | Stop recording and transcribe |
|
|
| `hush abort` | Discard the current recording |
|
|
| `hush status` | Show daemon state and recording duration |
|
|
| `hush show` | Show current configuration |
|
|
| `hush latency-test` | Measure STT and LLM round-trip latency |
|
|
| `hush daemon` | Run the daemon in the foreground |
|
|
| `hush setup` | Interactive configuration wizard |
|
|
| `hush profiles list` | List all profiles |
|
|
| `hush profiles get <name>` | Print the contents of a profile |
|
|
| `hush profiles new <name>` | Create a new profile (manual or AI-generated) |
|
|
| `hush profiles edit <name>` | Open a profile in `$EDITOR` |
|
|
|
|
`hush toggle` and `hush stop` accept a `--profile <name>` flag to apply a named profile when processing the recording:
|
|
|
|
```bash
|
|
hush toggle --profile cmd
|
|
```
|
|
|
|
## Building Manually
|
|
|
|
```bash
|
|
./build.sh
|
|
```
|
|
|
|
Produces a native AOT binary at `Hush.Cli/bin/Release/net10.0/linux-x64/publish/Hush.Cli`.
|
|
|
|
## Configuration
|
|
|
|
Key settings in `~/.config/hush/config`:
|
|
|
|
| Key | Default | Description |
|
|
|---|---|---|
|
|
| `groq_api_key` | | Groq API key |
|
|
| `fireworks_api_key` | | Fireworks API key |
|
|
| `whisper_provider` | `groq` | `groq` or `fireworks` |
|
|
| `llm_provider` | `groq` | `groq` or `fireworks` |
|
|
| `whisper_model` | `whisper-large-v3-turbo` | Whisper model to use |
|
|
| `llm_model` | `openai/gpt-oss-20b` | LLM model for text cleanup |
|
|
| `audio_backend` | `pw-record` | `pw-record` or `ffmpeg` |
|
|
| `typing_backend` | `wtype` | `wtype` or `xdotool` |
|
|
| `whisper_language` | | Optional ISO 639-1 language code (e.g. `en`) |
|
|
| `min_recording_duration` | `500` | Minimum recording length in ms |
|
|
| `system_prompt` | | Custom LLM system prompt (empty = built-in default) |
|
|
|
|
## Profiles
|
|
|
|
Profiles let you switch Hush's behaviour on a per-hotkey basis without touching the main config or restarting the daemon. A profile is a partial TOML file stored in `~/.config/hush/profiles/` — only the fields you list override the base config.
|
|
|
|
Create a profile interactively:
|
|
|
|
```bash
|
|
hush profiles new cmd
|
|
```
|
|
|
|
You will be asked whether to write the prompt manually or have the AI generate it from a description. The profile opens in `$EDITOR` for final review.
|
|
|
|
Example profile at `~/.config/hush/profiles/cmd`:
|
|
|
|
```toml
|
|
whisper_language = "en"
|
|
system_prompt = """
|
|
Convert the spoken input into a single valid bash command. Output only the raw
|
|
command with no explanation, no markdown, and no backticks. If the input is
|
|
unclear, output an empty string.
|
|
"""
|
|
```
|
|
|
|
Bind a second hotkey to use it:
|
|
|
|
```
|
|
Super+R → hush toggle
|
|
Super+Shift+R → hush toggle --profile cmd
|
|
```
|