### Whisrs CLI and Daemon Commands

Source: https://github.com/y0sif/whisrs/blob/main/CLAUDE.md

Commands for setting up, running, and interacting with the Whisrs daemon and CLI. Includes first-time setup, starting the daemon, and common CLI operations.

```fish
# First-time setup (interactive, no daemon needed)
whisrs setup
```

```fish
# Start the daemon
whisrsd &
```

```fish
# Or via systemd
systemctl --user enable --now whisrs.service
```

```fish
# Use the CLI (bind to a hotkey)
whisrs toggle    # start/stop recording
```

```fish
whisrs cancel    # cancel and discard audio
```

```fish
whisrs status    # query daemon state
```

```fish
# Debug logging
set -x RUST_LOG debug; whisrsd
```

--------------------------------

### Quick Install Script for Whisrs

Source: https://github.com/y0sif/whisrs/blob/main/README.md

Use this curl command for a quick installation of Whisrs on any Linux distribution. It automates dependency installation, building, and setup.

```bash
curl -sSL https://y0sif.github.io/whisrs/install.sh | bash
```

--------------------------------

### Clone and Install Whisrs Locally

Source: https://github.com/y0sif/whisrs/blob/main/README.md

Clone the Whisrs repository and run the install script locally for manual control over the installation process.

```bash
git clone https://github.com/y0sif/whisrs && cd whisrs && ./install.sh
```

--------------------------------

### Start Whisrs Daemon with Systemd

Source: https://context7.com/y0sif/whisrs/llms.txt

Enable and start the `whisrs` service using systemd for recommended background operation.

```bash
systemctl --user enable --now whisrs.service
```

--------------------------------

### Whisrs Configuration File Example

Source: https://context7.com/y0sif/whisrs/llms.txt

Example TOML configuration file showing settings for general, audio, transcription backends, LLM, and hotkeys.

```toml
[general]
backend = "groq"            # groq | deepgram-streaming | deepgram | openai-realtime | openai | local-whisper
language = "en"             # ISO 639-1 or "auto"
silence_timeout_ms = 2000   # auto-stop after silence (streaming only)
notify = true               # desktop notifications
remove_filler_words = true  # strip "um", "uh", "you know", etc.
filler_words = []           # custom list (empty = use built-in defaults)
audio_feedback = true       # play tones on record start/stop/done
audio_feedback_volume = 0.5 # 0.0 to 1.0
vocabulary = ["whisrs", "Hyprland"]  # custom terms for better transcription accuracy
tray = true                 # system tray icon (requires SNI host like waybar)

[audio] device = "default"

[groq]
api_key = "gsk_..."
model = "whisper-large-v3-turbo"

[deepgram]
api_key = "..."
model = "nova-3"

[openai]
api_key = "sk-..."
model = "gpt-4o-mini-transcribe"

[local-whisper]
model_path = "~/.local/share/whisrs/models/ggml-base.en.bin"

# LLM configuration for command mode (text rewriting)
[llm]
api_key = "sk-..."
model = "gpt-4o-mini"
api_url = "https://api.openai.com/v1/chat/completions"

# Built-in global hotkeys (optional, works without WM keybinds)
[hotkeys]
toggle = "Super+Shift+W"
cancel = "Super+Shift+D"
command = "Super+Shift+G"
```

--------------------------------

### Whisrs Setup Command

Source: https://github.com/y0sif/whisrs/blob/main/README.md

Run the `whisrs setup` command to configure transcription backends, API keys, microphone settings, permissions, and keybindings.

```bash
whisrs setup
```

--------------------------------

### Window Manager Keybinding Examples (Hyprland, Sway, i3)

Source: https://context7.com/y0sif/whisrs/llms.txt

Configuration snippets for binding Whisrs commands to hotkeys in popular window managers: Hyprland, Sway, and i3. These examples show how to map keys to `whisrs toggle`, `whisrs cancel`, and `whisrs command`.

```bash
# Hyprland (~/.config/hypr/hyprland.conf)
bind = $mainMod, W, exec, whisrs toggle
bind = $mainMod SHIFT, W, exec, whisrs cancel
bind = $mainMod, G, exec, whisrs command

# Sway (~/.config/sway/config)
bindsym $mod+w exec whisrs toggle
bindsym $mod+Shift+w exec whisrs cancel
bindsym $mod+g exec whisrs command

# i3 (~/.config/i3/config)
bindsym $mod+w exec whisrs toggle
bindsym $mod+Shift+w exec whisrs cancel
bindsym $mod+g exec whisrs command
```

--------------------------------

### Select Transcription Backend

Source: https://context7.com/y0sif/whisrs/llms.txt

Command to initiate the setup process for selecting a transcription backend. The table in the documentation lists available backends like `groq`, `deepgram-streaming`, `openai`, and `local-whisper` with their respective tradeoffs.

```bash
# Select backend during setup
whisrs setup
```

--------------------------------

### Install Whisrs Dependencies on Debian/Ubuntu

Source: https://github.com/y0sif/whisrs/blob/main/README.md

Install the necessary build dependencies for Whisrs on Debian or Ubuntu systems using apt.

```bash
sudo apt install build-essential libasound2-dev libxkbcommon-dev libclang-dev cmake
```

--------------------------------

### Install Development Dependencies (Fedora)

Source: https://github.com/y0sif/whisrs/blob/main/CONTRIBUTING.md

Installs essential packages for whisrs development on Fedora. Requires alsa-lib-devel, libxkbcommon-devel, and pkg-config.

```bash
sudo dnf install alsa-lib-devel libxkbcommon-devel pkg-config
```

--------------------------------

### Install Development Dependencies (Ubuntu/Debian)

Source: https://github.com/y0sif/whisrs/blob/main/CONTRIBUTING.md

Installs required packages for building whisrs on Ubuntu or Debian systems. This includes build-essential, alsa-lib, libxkbcommon, and pkg-config.

```bash
sudo apt install build-essential libasound2-dev libxkbcommon-dev pkg-config
```

--------------------------------

### Install Whisrs via Cargo

Source: https://github.com/y0sif/whisrs/blob/main/README.md

Install Whisrs using the Cargo package manager. Ensure system dependencies like alsa-lib, libxkbcommon, clang, and cmake are installed.

```bash
cargo install whisrs
```

--------------------------------

### Whisrs Local Transcription Setup

Source: https://github.com/y0sif/whisrs/blob/main/README.md

Initiate the Whisrs setup process and select the 'Local > whisper.cpp' option to configure offline transcription. This step also allows model selection and automatic download.

```bash
whisrs setup   # select Local > whisper.cpp, pick a model, download automatically
```

--------------------------------

### Install Development Dependencies (Arch Linux)

Source: https://github.com/y0sif/whisrs/blob/main/CONTRIBUTING.md

Installs necessary packages for building whisrs on Arch Linux. Ensure you have base-devel, alsa-lib, libxkbcommon, and pkg-config.

```bash
sudo pacman -S base-devel alsa-lib libxkbcommon pkg-config
```

--------------------------------

### Install Whisrs via AUR

Source: https://github.com/y0sif/whisrs/blob/main/README.md

Install the Whisrs package from the Arch User Repository (AUR) using an AUR helper like `yay`.

```bash
yay -S whisrs-git
```

--------------------------------

### Whisrs Hotkey Binding for Hyprland

Source: https://github.com/y0sif/whisrs/blob/main/README.md

Example configuration for binding a hotkey in Hyprland to toggle Whisrs.

```bash
bind = $mainMod, W, exec, whisrs toggle
```

--------------------------------

### Configure Global Hotkeys in TOML

Source: https://context7.com/y0sif/whisrs/llms.txt

Example TOML configuration for setting global hotkeys for Whisrs actions like toggling recording, cancelling, and entering LLM command mode. Supports standard modifiers and keys.

```toml
# In ~/.config/whisrs/config.toml
[hotkeys]
toggle = "Super+Shift+W"    # Start/stop recording
cancel = "Super+Shift+D"    # Cancel recording
command = "Super+Shift+G"   # LLM command mode

# Supported modifiers: Super, Alt, Ctrl, Shift (left/right variants accepted)
# Supported keys: A-Z, F1-F12, Escape, Space, Enter, Tab, etc.
```

--------------------------------

### Build Whisrs from Source

Source: https://github.com/y0sif/whisrs/blob/main/README.md

Clone the Whisrs repository and build the project locally using Cargo after installing dependencies.

```bash
git clone https://github.com/y0sif/whisrs
cd whisrs
cargo install --path .
```

--------------------------------

### Install Whisrs Dependencies on Fedora

Source: https://github.com/y0sif/whisrs/blob/main/README.md

Install the necessary build dependencies for Whisrs on Fedora systems using dnf.

```bash
sudo dnf install gcc-c++ alsa-lib-devel libxkbcommon-devel clang-devel cmake
```

--------------------------------

### Install Whisrs Dependencies on Arch Linux

Source: https://github.com/y0sif/whisrs/blob/main/README.md

Install the necessary build dependencies for Whisrs on Arch Linux using pacman.

```bash
sudo pacman -S base-devel alsa-lib libxkbcommon clang cmake
```

--------------------------------

### Start Whisrs Daemon in Background

Source: https://context7.com/y0sif/whisrs/llms.txt

Start the `whisrsd` daemon in the background using the '&' operator.

```bash
whisrsd &
```

--------------------------------

### Whisrs Hotkey Binding for Sway

Source: https://github.com/y0sif/whisrs/blob/main/README.md

Example configuration for binding a hotkey in Sway to toggle Whisrs.

```bash
bindsym $mod+w exec whisrs toggle
```

--------------------------------

### Install Whisrs via Nix

Source: https://github.com/y0sif/whisrs/blob/main/README.md

Install Whisrs using Nix package manager. This command adds Whisrs to your user profile.

```bash
nix profile install github:y0sif/whisrs
```

--------------------------------

### Start Whisrs Daemon with Debug Logging

Source: https://context7.com/y0sif/whisrs/llms.txt

Launch the `whisrsd` daemon with debug logging enabled by setting the RUST_LOG environment variable.

```bash
RUST_LOG=debug whisrsd
```

--------------------------------

### Run whisrs Daemon with Debug Logging

Source: https://github.com/y0sif/whisrs/blob/main/CONTRIBUTING.md

Starts the whisrs daemon with detailed debug logs enabled. Useful for troubleshooting issues during development.

```bash
RUST_LOG=debug cargo run --bin whisrsd
```

--------------------------------

### Example Commit Message

Source: https://github.com/y0sif/whisrs/blob/main/CONTRIBUTING.md

A well-formatted commit message includes a concise summary in the imperative mood, followed by a blank line and then more detailed explanations if necessary.

```git
Add Sway window tracking via IPC

Use swayipc crate to query focused window and restore focus.
Tested on Sway 1.9 with Wayland.
```

--------------------------------

### Whisrs CLI Toggle Recording

Source: https://context7.com/y0sif/whisrs/llms.txt

Use the toggle command to start or stop dictation and initiate transcription.

```bash
whisrs toggle
```

--------------------------------

### Configure and Use LLM for Text Rewriting

Source: https://context7.com/y0sif/whisrs/llms.txt

Shows how to configure an LLM backend (OpenAI or Groq) and use it to rewrite text based on a voice instruction. The `api_url` can be changed to support different providers.

```rust
use whisrs::llm::{self, LlmConfig};

// Configure LLM backend
let config = LlmConfig {
    api_key: "sk-...".to_string(),
    model: "gpt-4o-mini".to_string(),
    api_url: "https://api.openai.com/v1/chat/completions".to_string(),
};

// Rewrite text based on voice instruction
let selected_text = "Hello world this is a test";
let instruction = "make it more formal";

let result = llm::rewrite_text(&config, selected_text, instruction).await?;
// Result: "Greetings. This is a test."

// Supports multiple providers via api_url
let groq_config = LlmConfig {
    api_key: "gsk_...".to_string(),
    model: "llama-3.3-70b-versatile".to_string(),
    api_url: "https://api.groq.com/openai/v1/chat/completions".to_string(),
};
```

--------------------------------

### Manage Whisrs State Machine Transitions

Source: https://context7.com/y0sif/whisrs/llms.txt

Illustrates the state transitions of the Whisrs application (Idle, Recording, Transcribing) using the `StateMachine`. Actions like `Toggle`, `TranscriptionDone`, and `Cancel` are demonstrated.

```rust
use whisrs::state::{StateMachine, Action};
use whisrs::State;

let mut sm = StateMachine::new();
assert_eq!(sm.state(), State::Idle);

// Toggle: Idle → Recording
sm.transition(Action::Toggle)?;
assert_eq!(sm.state(), State::Recording);

// Toggle: Recording → Transcribing
sm.transition(Action::Toggle)?;
assert_eq!(sm.state(), State::Transcribing);

// TranscriptionDone: Transcribing → Idle
sm.transition(Action::TranscriptionDone)?;
assert_eq!(sm.state(), State::Idle);

// Cancel: Recording → Idle (discard audio)
sm.transition(Action::Toggle)?;
// → Recording
sm.transition(Action::Cancel)?;
assert_eq!(sm.state(), State::Idle);
```

--------------------------------

### Build and Test whisrs

Source: https://github.com/y0sif/whisrs/blob/main/CONTRIBUTING.md

Commands to build the project, run tests, check for clippy warnings, and format the code. Ensure all checks pass before committing.

```bash
cargo build
```

```bash
cargo test
```

```bash
cargo clippy --all-targets -- -D warnings
```

```bash
cargo fmt --check
```

--------------------------------

### Manage Clipboard with ClipboardHandler

Source: https://context7.com/y0sif/whisrs/llms.txt

Provides cross-platform clipboard access for Wayland and X11. Supports standard clipboard operations and primary selection reading.

```rust
use whisrs::input::ClipboardHandler;
use whisrs::input::clipboard::ClipboardOps;

// Auto-detect display server and get appropriate handler
let clipboard = ClipboardOps::detect();

// Read current clipboard text
let text = clipboard.get_text()?;

// Set clipboard content
clipboard.set_text("New clipboard content")?;

// Read primary selection (highlighted text, no Ctrl+C needed)
// Useful for terminal emulators and command mode
let selection = clipboard.get_primary_selection()?;
```

--------------------------------

### Track Window Focus with WindowTracker

Source: https://context7.com/y0sif/whisrs/llms.txt

Provides compositor-independent window focus tracking and restoration. Use detect_tracker to initialize the appropriate implementation.

```rust
use whisrs::window::{self, WindowTracker};

/// Trait for tracking and restoring window focus.
pub trait WindowTracker: Send + Sync {
    /// Get the identifier of the currently focused window.
    fn get_focused_window(&self) -> anyhow::Result<String>;

    /// Focus the window with the given identifier.
    fn focus_window(&self, id: &str) -> anyhow::Result<()>;

    /// Get the window class of the currently focused window (e.g. "Alacritty").
    fn get_focused_window_class(&self) -> Option<String>;
}

// Auto-detect compositor and get appropriate tracker
let tracker: Box<dyn WindowTracker> = window::detect_tracker();

// Save focused window before recording
let window_id = tracker.get_focused_window()?;

// ... perform recording and transcription ...

// Restore focus to original window
tracker.focus_window(&window_id)?;
```

--------------------------------

### Configure Whisrs backend

Source: https://context7.com/y0sif/whisrs/llms.txt

Edit the configuration file to specify the desired backend for dictation.

```toml
[general]
backend = "groq"  # Change to desired backend
```

--------------------------------

### Whisrs Supporting Files

Source: https://github.com/y0sif/whisrs/blob/main/CLAUDE.md

Overview of supporting files and directories within the Whisrs project, including contribution files, systemd service units, man pages, and documentation.

```text
contrib/
├── 99-whisrs.rules         # udev rule for /dev/uinput access
├── whisrs.service          # systemd user service
├── whisrs.1                # man page for whisrs CLI
└── whisrsd.1               # man page for whisrsd daemon
docs/
├── plan.md                 # Implementation plan (phases 0-7)
├── architecture.md         # System architecture and data flow
├── branding.md             # Name, colors, ASCII banner
└── tech-stack.md           # Technology choices and rationale
```

--------------------------------

### AudioCaptureHandle

Source: https://context7.com/y0sif/whisrs/llms.txt

Manages audio capture from the default input device at 16kHz mono 16-bit format.

```APIDOC
## AudioCaptureHandle

The `AudioCaptureHandle` manages audio capture from the default input device at 16kHz mono 16-bit format.

### Methods

- `start() -> anyhow::Result<AudioCaptureHandle>`: Start capturing audio from the default input device.
- `take_receiver() -> mpsc::Receiver<Vec<i16>>`: Take the receiver for streaming pipelines.
- `stop_and_collect() -> anyhow::Result<Vec<i16>>`: Stop capture and collect all samples for batch processing.

### Functions

- `encode_wav(samples: &[i16]) -> anyhow::Result<Vec<u8>>`: Encode raw PCM samples to WAV format.
```

--------------------------------

### Fish Shell Build Commands for Whisrs

Source: https://github.com/y0sif/whisrs/blob/main/CLAUDE.md

Standard commands for building, linting, testing, and formatting the Whisrs project using Cargo. Ensure you are in the project's root directory.

```fish
cargo build                                    # compile debug binaries (includes all backends)
```

```fish
cargo clippy --all-targets -- -D warnings      # lint (strict, warnings = errors)
```

```fish
cargo test                                     # run all tests
```

```fish
cargo fmt                                      # format code
```

```fish
cargo fmt -- --check                           # check formatting (CI)
```

--------------------------------

### Inject Keys with KeyInjector

Source: https://context7.com/y0sif/whisrs/llms.txt

Handles virtual keyboard input using uinput and clipboard fallback. Requires keyboard layout detection and keymap initialization.

```rust
use whisrs::input::{KeyInjector, ClipboardHandler};
use whisrs::input::keymap::XkbKeymap;
use whisrs::input::uinput::UinputKeyboard;
use whisrs::input::clipboard::ClipboardOps;

// Detect keyboard layout and build keymap
let layout = whisrs::input::keymap::KeyboardLayout::detect();
let keymap = XkbKeymap::from_layout(&layout)?;

// Create virtual keyboard with clipboard fallback
let clipboard = ClipboardOps::detect();
let mut keyboard = UinputKeyboard::new(keymap, clipboard)?;

// Type text at the cursor position
keyboard.type_text("Hello, world!")?;

// Send backspace key events
keyboard.backspace(5)?;

// Paste text via clipboard (Ctrl+V) for special characters
keyboard.paste_text("Special: 
F600")?;
```

--------------------------------

### Run CI Checks with Cargo

Source: https://github.com/y0sif/whisrs/blob/main/CLAUDE.md

Execute formatting, linting, testing, and building checks locally before pushing code. Ensure all checks pass to avoid errors and maintain a clean commit history.

```fish
cargo fmt                                      # fix formatting
cargo clippy --all-targets -- -D warnings      # lint (must pass clean)
cargo test                                     # all tests must pass
cargo build                                    # must compile
```

--------------------------------

### Capture Audio with AudioCaptureHandle

Source: https://context7.com/y0sif/whisrs/llms.txt

Manages 16kHz mono 16-bit audio capture. Provides methods for streaming chunks or collecting full buffers for WAV encoding.

```rust
use whisrs::audio::capture::AudioCaptureHandle;

// Start capturing audio from the default input device
let mut capture = AudioCaptureHandle::start()?;

// Take the receiver for streaming pipelines
let audio_rx = capture.take_receiver();

// Process audio chunks as they arrive
while let Some(chunk) = audio_rx.recv().await {
    // chunk is Vec<i16> with 16kHz mono samples
    process_audio(&chunk);
}

// Stop capture and collect all samples for batch processing
let samples = capture.stop_and_collect().await?;

// Encode raw PCM samples to WAV format
use whisrs::audio::capture::encode_wav;
let wav_data = encode_wav(&samples)?;
```

--------------------------------

### Build Whisrs with Cargo

Source: https://context7.com/y0sif/whisrs/llms.txt

Common Cargo commands for building, testing, and formatting the Whisrs project. Includes options for compiling in debug mode, linting, running tests, and managing features like `local-whisper` and `tray`.

```bash
# Compile debug binaries (includes all backends)
cargo build

# Lint with strict warnings
cargo clippy --all-targets -- -D warnings

# Run all tests
cargo test

# Format code
cargo fmt

# Check formatting (CI)
cargo fmt -- --check

# Build with specific features
cargo build --no-default-features                    # Cloud backends only
cargo build --features local-whisper                 # Include local whisper.cpp
cargo build --features tray                          # Include system tray
cargo build --features "local-whisper,tray"          # All features (default)
```

--------------------------------

### Whisrs Project Structure Overview

Source: https://github.com/y0sif/whisrs/blob/main/CLAUDE.md

Directory structure for the Whisrs project, detailing the organization of source files for the library, CLI, daemon, and various modules like audio, transcription, input, and window management.

```text
src/
├── lib.rs                  # Shared types: Config, IPC protocol, errors, helpers
├── cli/
│   └── main.rs             # whisrs CLI (thin client, sends commands over socket)
├── daemon/
│   └── main.rs             # whisrsd daemon (audio, transcription, typing, IPC server)
├── audio/
│   ├── mod.rs              # Audio module exports
│   ├── capture.rs          # cpal audio capture + WAV encoding
│   ├── silence.rs          # VAD/silence detection (RMS energy, auto-stop)
│   └── recovery.rs         # Save/load audio on transcription failure
├── transcription/
│   ├── mod.rs              # TranscriptionBackend trait
│   ├── deepgram.rs         # Deepgram Nova API (REST + WebSocket streaming)
│   ├── groq.rs             # Groq Whisper API (chunked HTTP, timestamp dedup)
│   ├── openai_realtime.rs  # OpenAI Realtime API (WebSocket, true streaming)
│   ├── openai_rest.rs      # OpenAI REST API (simple HTTP POST)
│   ├── local_whisper.rs    # Local whisper.cpp via whisper-rs (feature-gated)
│   ├── local_vosk.rs       # Vosk backend stub (coming soon)
│   ├── local_parakeet.rs   # Parakeet/NVIDIA backend stub (coming soon)
│   └── dedup.rs            # Timestamp + n-gram deduplication for chunked APIs
├── input/
│   ├── mod.rs              # KeyInjector trait
│   ├── uinput.rs           # Virtual keyboard via evdev UinputDevice
│   ├── keymap.rs           # XKB reverse lookup (char → keycode+modifiers)
│   └── clipboard.rs        # Clipboard ops (wl-copy/arboard, save/restore)
├── window/
│   ├── mod.rs              # WindowTracker trait + auto-detection
│   ├── hyprland.rs         # Hyprland window tracking
│   ├── sway.rs             # Sway window tracking (swayipc)
│   ├── x11.rs              # X11 window tracking (x11rb)
│   └── dbus.rs             # GNOME/KDE window tracking (zbus D-Bus)
├── config/
│   ├── mod.rs              # Config module exports
│   └── setup.rs            # Interactive onboarding (whisrs setup)
└── state.rs                # State machine (Idle → Recording → Transcribing → Idle)
```

--------------------------------

### Append and Read Transcription History

Source: https://context7.com/y0sif/whisrs/llms.txt

Demonstrates creating, appending, and reading transcription entries from the history file. Requires `chrono` for timestamps.

```rust
use whisrs::history::{self, HistoryEntry};
use chrono::Local;

// Create a history entry
let entry = HistoryEntry {
    timestamp: Local::now(),
    text: "Hello, this is a test transcription.".to_string(),
    backend: "groq".to_string(),
    language: "en".to_string(),
    duration_secs: 3.5,
};

// Append entry to history file
history::append_entry(&entry)?;

// Read the most recent 20 entries (newest first)
let entries = history::read_entries(20)?;

for entry in entries {
    println!("{}: {} ({} | {} | {:.1}s)",
        entry.timestamp.format("%Y-%m-%d %H:%M:%S"),
        entry.text,
        entry.backend,
        entry.language,
        entry.duration_secs
    );
}

// Clear all history
history::clear_history()?;
```

--------------------------------

### WindowTracker Trait

Source: https://context7.com/y0sif/whisrs/llms.txt

Provides compositor-independent window focus tracking and restoration.

```APIDOC
## WindowTracker Trait

The `WindowTracker` trait provides compositor-independent window focus tracking and restoration.

### Methods

- `get_focused_window(&self) -> anyhow::Result<String>`: Get the identifier of the currently focused window.
- `focus_window(&self, id: &str) -> anyhow::Result<()>`: Focus the window with the given identifier.
- `get_focused_window_class(&self) -> Option<String>`: Get the window class of the currently focused window (e.g. "Alacritty").

### Functions

- `detect_tracker() -> Box<dyn WindowTracker>`: Auto-detect compositor and get appropriate tracker.
```

--------------------------------

### Whisrs CLI Command Mode

Source: https://context7.com/y0sif/whisrs/llms.txt

Enter command mode to select text and issue voice instructions for LLM-based text rewriting.

```bash
whisrs command
```

--------------------------------

### KeyInjector Trait

Source: https://context7.com/y0sif/whisrs/llms.txt

Handles typing text via virtual keyboard injection using uinput.

```APIDOC
## KeyInjector Trait

The `KeyInjector` trait handles typing text via virtual keyboard injection using uinput.

### Methods

- `type_text(&mut self, text: &str) -> anyhow::Result<()>`: Type text at the cursor position.
- `backspace(&mut self, count: usize) -> anyhow::Result<()>`: Send backspace key events.
- `paste_text(&mut self, text: &str) -> anyhow::Result<()>`: Paste text via clipboard (Ctrl+V) for special characters.

### Structs

#### UinputKeyboard

Represents a virtual keyboard using uinput.

- **keymap** (XkbKeymap) - Required - The keyboard layout map.
- **clipboard** (ClipboardOps) - Required - The clipboard handler.

### Functions

- `new(keymap: XkbKeymap, clipboard: impl ClipboardHandler) -> anyhow::Result<Self>`: Create a new virtual keyboard.
- `from_layout(layout: KeyboardLayout) -> anyhow::Result<Self>`: Detect keyboard layout and build keymap.
```

--------------------------------

### Define TranscriptionBackend Trait

Source: https://context7.com/y0sif/whisrs/llms.txt

Defines the interface for transcription backends supporting batch and streaming modes. Requires async_trait and tokio mpsc channels.

```rust
use async_trait::async_trait;
use tokio::sync::mpsc;

/// Configuration for a transcription request.
#[derive(Debug, Clone)]
pub struct TranscriptionConfig {
    /// Language code (ISO 639-1), e.g. "en", or "auto" for auto-detection.
    pub language: String,
    /// Model identifier (backend-specific).
    pub model: String,
    /// Optional prompt hint for the transcription model (vocabulary, context).
    pub prompt: Option<String>,
}

/// Trait for transcription backends.
#[async_trait]
pub trait TranscriptionBackend: Send + Sync {
    /// Transcribe a complete WAV-encoded audio buffer, returning the text.
    async fn transcribe(
        &self,
        audio: &[u8],
        config: &TranscriptionConfig,
    ) -> anyhow::Result<String>;

    /// Streaming transcription: receive audio chunks and send text incrementally.
    async fn transcribe_stream(
        &self,
        audio_rx: mpsc::Receiver<Vec<i16>>,
        text_tx: mpsc::Sender<String>,
        config: &TranscriptionConfig,
    ) -> anyhow::Result<()>;

    /// Whether this backend supports true/chunked streaming.
    fn supports_streaming(&self) -> bool {
        false
    }
}
```

--------------------------------

### ClipboardHandler Trait

Source: https://context7.com/y0sif/whisrs/llms.txt

Provides cross-platform clipboard operations for Wayland and X11.

```APIDOC
## ClipboardHandler Trait

The `ClipboardHandler` trait provides cross-platform clipboard operations for Wayland and X11.

### Methods

- `get_text(&self) -> anyhow::Result<String>`: Read current clipboard text.
- `set_text(&self, text: &str) -> anyhow::Result<()>`: Set clipboard content.
- `get_primary_selection(&self) -> anyhow::Result<String>`: Read primary selection (highlighted text, no Ctrl+C needed).

### Functions

- `detect() -> impl ClipboardHandler`: Auto-detect display server and get appropriate handler.
```

--------------------------------

### Whisrs Environment Variable API Key Overrides

Source: https://context7.com/y0sif/whisrs/llms.txt

Set API keys for Groq, Deepgram, and OpenAI using environment variables to override configuration file settings.

```bash
export WHISRS_GROQ_API_KEY="gsk_..."
```

```bash
export WHISRS_DEEPGRAM_API_KEY="..."
```

```bash
export WHISRS_OPENAI_API_KEY="sk-..."
```

--------------------------------

### Interact with whisrs Daemon via CLI

Source: https://github.com/y0sif/whisrs/blob/main/CONTRIBUTING.md

Commands to control the whisrs daemon from the command line. Includes options for toggling, checking status, and cancelling operations.

```bash
cargo run --bin whisrs -- toggle
```

```bash
cargo run --bin whisrs -- status
```

```bash
cargo run --bin whisrs -- cancel
```

--------------------------------

### TranscriptionBackend Trait

Source: https://context7.com/y0sif/whisrs/llms.txt

Defines the interface for transcription backends, supporting both batch and streaming modes.

```APIDOC
## TranscriptionBackend Trait

The `TranscriptionBackend` trait defines the interface for all transcription backends, supporting both batch and streaming modes.

### Methods

- `transcribe(&self, audio: &[u8], config: &TranscriptionConfig) -> anyhow::Result<String>`: Transcribe a complete WAV-encoded audio buffer, returning the text.
- `transcribe_stream(&self, audio_rx: mpsc::Receiver<Vec<i16>>, text_tx: mpsc::Sender<String>, config: &TranscriptionConfig) -> anyhow::Result<()>`: Streaming transcription: receive audio chunks and send text incrementally.
- `supports_streaming(&self) -> bool`: Whether this backend supports true/chunked streaming.

### Structs

#### TranscriptionConfig

Configuration for a transcription request.

- **language** (String) - Required - Language code (ISO 639-1), e.g. "en", or "auto" for auto-detection.
- **model** (String) - Required - Model identifier (backend-specific).
- **prompt** (Option<String>) - Optional - Optional prompt hint for the transcription model (vocabulary, context).
```

--------------------------------

### Whisrs Environment Variable for Logging

Source: https://context7.com/y0sif/whisrs/llms.txt

Control the daemon's log verbosity by setting the RUST_LOG environment variable.

```bash
export RUST_LOG=debug
```

--------------------------------

### Whisrs CLI Status Command

Source: https://context7.com/y0sif/whisrs/llms.txt

Query the current state of the daemon (idle, recording, transcribing) using the status command.

```bash
whisrs status
```

--------------------------------

### Whisrs Feature Flags

Source: https://github.com/y0sif/whisrs/blob/main/CLAUDE.md

Explanation of feature flags used in the Whisrs project, particularly for enabling offline transcription capabilities. The default configuration includes local whisper.cpp.

```text
- `default = ["local-whisper"]` — builds with all backends (cloud + local whisper.cpp)
- `local-whisper` — enables whisper-rs (whisper.cpp) for offline transcription. Requires C++ toolchain and libclang. Included by default.
```

--------------------------------

### Whisrs CLI Log Commands

Source: https://context7.com/y0sif/whisrs/llms.txt

View recent transcription history with 'log', specify the number of entries with '-n', or clear history with '--clear'.

```bash
whisrs log
```

```bash
whisrs log -n 5
```

```bash
whisrs log --clear
```

--------------------------------

### Whisrs IPC Protocol - CLI Commands

Source: https://context7.com/y0sif/whisrs/llms.txt

JSON messages sent from the `whisrs` CLI to the `whisrsd` daemon for various operations.

```json
{"cmd": "toggle"}
```

```json
{"cmd": "cancel"}
```

```json
{"cmd": "status"}
```

```json
{"cmd": "log", "limit": 20}
```

```json
{"cmd": "clear-history"}
```

```json
{"cmd": "command"}
```

--------------------------------

### Whisrs CLI Cancel Recording

Source: https://context7.com/y0sif/whisrs/llms.txt

Cancel the current recording and discard any captured audio with the cancel command.

```bash
whisrs cancel
```

--------------------------------

### Whisrs IPC Protocol Definition

Source: https://github.com/y0sif/whisrs/blob/main/CLAUDE.md

Details of the Inter-Process Communication protocol used by Whisrs, including the socket location, command formats, and response structures. Uses length-prefixed JSON over a Unix socket.

```text
Socket: $XDG_RUNTIME_DIR/whisrs.sock (fallback: /tmp/whisrs-<uid>.sock)

Commands: {"cmd": "toggle"}, {"cmd": "cancel"}, {"cmd": "status"}
Responses: {"status": "ok", "state": "idle"}, {"status": "error", "message": "..."}
```

--------------------------------

### Whisrs IPC Protocol - Daemon Responses

Source: https://context7.com/y0sif/whisrs/llms.txt

JSON responses received from the `whisrsd` daemon indicating status, errors, or transcription history.

```json
{"status": "ok", "state": "idle"}
```

```json
{"status": "ok", "state": "recording"}
```

```json
{"status": "ok", "state": "transcribing"}
```

```json
{"status": "error", "message": "no microphone found"}
```

```json
{"status": "history", "entries": [...]}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.