Hotkeys

Overview

VoiceTypr uses system-wide hotkeys to let you start voice recording from anywhere on your system, without switching to the app. Hotkeys work across all applications and can be fully customized to fit your workflow.

Default Hotkeys

VoiceTypr ships with sensible defaults:

macOS

Cmd + Shift + SpaceSystem-wide recording hotkey that works everywhere.

Windows

Ctrl + Shift + SpaceSystem-wide recording hotkey that works everywhere.

Hotkey Configuration

Hotkeys are stored in your app settings:

interface AppSettings {
  hotkey: string;                    // Main recording hotkey
  recording_mode?: RecordingMode;    // 'toggle' | 'push_to_talk'
  use_different_ptt_key?: boolean;   // Use separate push-to-talk key
  ptt_hotkey?: string;               // Optional separate PTT key
}

Hotkey Format

Hotkeys use a standardized format:

// Format: Modifier+Modifier+Key
"CommandOrControl+Shift+Space"  // Cross-platform Cmd/Ctrl
"Control+Alt+R"                  // Specific Control key
"CommandOrControl+Shift+F12"    // Function keys

Supported modifiers:

CommandOrControl - Cmd on macOS, Ctrl on Windows/Linux
Control - Control key (Ctrl on Windows, ^ on macOS)
Alt - Alt/Option key
Shift - Shift key

Supported keys:

Letters: A-Z
Numbers: 0-9
Function keys: F1-F12
Special keys: Space, Return, Escape, Tab, Backspace, Delete
Arrow keys: Up, Down, Left, Right
Punctuation: Comma, Period, Slash, Backslash, etc.

Customizing Your Hotkey

Open Settings

Click the VoiceTypr menubar icon and go to Settings.

Find Recording Section

Scroll to the Recording section with the microphone icon.

Click Edit

Click the edit (pencil) icon next to your current hotkey.

Press Your Keys

Press the key combination you want to use. VoiceTypr will capture it in real-time.

Save

Click the checkmark (✓) to save your new hotkey.

Hotkey Input Component

The hotkey input component provides real-time feedback:

// src/components/HotkeyInput.tsx:25
<HotkeyInput
  value={hotkey}
  onChange={handleHotkeyChange}
  validationRules={ValidationPresets.standard()}
  onEditingChange={(isEditing) => console.log(isEditing)}
/>

Features:

Live preview as you press keys
Automatic validation against system conflicts
ESC to cancel editing
Visual feedback for valid/invalid combinations

Recording Modes

How your hotkey behaves depends on the recording mode:

Toggle Mode
Push-to-Talk Mode

Toggle Mode (Default)

Press the hotkey once to start, press again to stop.

recording_mode: 'toggle'

Behavior:

Press Cmd+Shift+Space → Recording starts
Speak your content
Press Cmd+Shift+Space again → Recording stops

Best for:

Longer dictations
Hands-free operation
Less strain on fingers

Toggle mode is recommended for most users. It’s more comfortable for extended use.

Push-to-Talk Mode

Hold the hotkey while speaking, release to stop.

recording_mode: 'push_to_talk'

Behavior:

Press and hold Cmd+Shift+Space → Recording starts
Speak while holding the keys
Release the keys → Recording stops immediately

Best for:

Quick voice commands
Precise control
Preventing accidental long recordings

Optional: Separate PTT KeyYou can configure a different hotkey specifically for push-to-talk:

use_different_ptt_key: true
ptt_hotkey: "Control+Space"  // Different from main hotkey

This lets you:

Use Cmd+Shift+Space for toggle mode
Use Ctrl+Space for push-to-talk mode
Switch between modes without changing settings

Quick Cancel (Double ESC)

Made a mistake while recording? Quickly cancel without waiting for transcription:

Press ESC twice in quick succession to immediately cancel the current recording.

How It Works

// src-tauri/src/recording/escape_handler.rs:83
log::info!("Second ESC press detected, cancelling recording");

Behavior:

First ESC: Tracked as potential cancel
Second ESC (within ~1 second): Recording cancelled
Recording file is deleted
Returns to idle state immediately

Use cases:

You misspoke and want to start over
Background noise interrupted your recording
You changed your mind mid-recording

Hotkey Validation

VoiceTypr validates hotkeys to prevent conflicts and ensure usability:

Validation Rules

interface KeyValidationRules {
  maxKeys: number;              // Maximum keys in combination
  requireModifier: boolean;     // Must include Cmd/Ctrl/Alt
  allowedModifiers: string[];   // Which modifiers are allowed
  disallowedKeys: string[];     // Keys that can't be used
}

// Standard preset
ValidationPresets.standard() = {
  maxKeys: 4,
  requireModifier: true,
  allowedModifiers: ['CommandOrControl', 'Control', 'Alt', 'Shift'],
  disallowedKeys: ['Escape']  // Reserved for cancel
}

System Conflict Detection

VoiceTypr checks for conflicts with common system hotkeys:

// src/lib/hotkey-conflicts.ts
checkForSystemConflict(shortcut: string): SystemConflict | null

Detected conflicts:

macOS: Spotlight, Mission Control, Screenshots, etc.
Windows: Task Manager, Desktop, Windows Search, etc.

Conflict severity:

error: Hotkey will not work (blocked by system)
warning: May work but could interfere

If your hotkey conflicts with a system shortcut, VoiceTypr will warn you during setup. Choose a different combination to avoid issues.

Best Practices

Choosing a Good Hotkey

Use modifier keys

Always include at least one modifier (Cmd, Ctrl, Alt, Shift) to avoid conflicts with normal typing.✅ Good: Cmd+Shift+Space
❌ Bad: Space (would trigger while typing)

Make it easy to press

Choose keys that are comfortable to press quickly with one hand.✅ Good: Cmd+Shift+Space, Ctrl+Alt+R
❌ Bad: Cmd+Shift+Ctrl+Alt+F12 (too complex)

Avoid system hotkeys

Don’t use combinations already taken by your OS or frequently used apps.✅ Good: Cmd+Shift+Space (rarely used)
❌ Bad: Cmd+Space (Spotlight on macOS)

Consider your workflow

Think about when and how you’ll use VoiceTypr.

Frequent use: Easy single-hand combo like Ctrl+Alt+Space
Occasional use: Less convenient combo is fine
Gaming: Avoid keys near WASD

Test in different apps

After setting a hotkey, test it in various applications to ensure it works consistently.

Recommended Hotkeys

If the defaults don’t work for you, try these:

Hotkey	Platform	Notes
`Cmd+Shift+Space`	macOS	Default, works well
`Ctrl+Shift+Space`	Windows	Default, works well
`Cmd+Option+Space`	macOS	Alternative if Shift is awkward
`Ctrl+Alt+V`	Windows	”V” for voice
`Cmd+Shift+R`	macOS	”R” for record
`Ctrl+Alt+R`	Windows	”R” for record
`F13`	macOS	If you have extended keyboard
`Ctrl+F12`	Windows	Function key combo

Keyboard Mapping

VoiceTypr uses physical key codes for international keyboard support:

// src/lib/keyboard-mapper.ts
mapCodeToKey(code: string): string

This ensures hotkeys work consistently across:

QWERTY, AZERTY, QWERTZ layouts
Different languages and regions
Custom keyboard mappings

Hotkeys are based on physical key position, not the character printed on the key. This ensures consistency across keyboard layouts.

Troubleshooting

Hotkey Not Working

Check permissions: Ensure VoiceTypr has accessibility permissions (macOS)
Verify no conflicts: Check for conflicts with system or app hotkeys
Test in different apps: Try the hotkey in multiple applications
Restart VoiceTypr: Sometimes registration fails and requires restart
Check modifiers: Ensure you’re using supported modifiers

Hotkey Registration Failed

If you see “Hotkey registration failed”:

// Event: hotkey-registration-failed
{
  suggestion: "The hotkey is in use by another application"
}

Solutions:

Choose a different hotkey combination
Close apps that might be using the same hotkey
Disable conflicting system shortcuts
Restart your computer

Hotkey Works Intermittently

If the hotkey only works sometimes:

Some apps capture global hotkeys (games, VMs, remote desktop)
Try using a less common key combination
Check if the app you’re in has special keyboard handling

Can’t Save Hotkey

If the save button stays disabled:

Your combination may be invalid (check validation error message)
You may have exceeded maximum keys (4 keys max)
Required modifier may be missing
Press ESC to cancel and try a different combination

Advanced Configuration

Platform-Specific Hotkeys

While VoiceTypr normalizes hotkeys across platforms, you can use platform-specific configurations:

// macOS
if (isMacOS) {
  hotkey = "CommandOrControl+Shift+Space"  // Becomes Cmd+Shift+Space
}

// Windows
if (!isMacOS) {
  hotkey = "CommandOrControl+Shift+Space"  // Becomes Ctrl+Shift+Space
}

Multiple Hotkeys

Currently, VoiceTypr supports one main hotkey plus an optional separate push-to-talk key:

hotkey: "CommandOrControl+Shift+Space"  // Main recording hotkey
ptt_hotkey: "Control+Space"             // Optional PTT-only hotkey

Programmatic Hotkey Changes

You can update hotkeys programmatically via settings:

import { invoke } from '@tauri-apps/api/core';

await invoke('update_settings', {
  updates: {
    hotkey: 'CommandOrControl+Alt+V'
  }
});

The backend automatically re-registers the new hotkey.

Security Considerations

System-wide hotkeys can be a security risk if not properly validated. VoiceTypr includes protections against malicious hotkey configurations.

Protections:

Hotkeys must include modifiers (can’t use single keys)
Maximum 4 keys to prevent buffer overflow
Validation before registration
Automatic cleanup on app quit

Best practices:

Don’t use simple combinations that could trigger accidentally
Avoid hotkeys that conflict with security features (Task Manager, etc.)
Test thoroughly before relying on them in production workflows

Get Started

Core Features

Guides

Platform Specific

Help

Overview

Default Hotkeys

macOS

Windows

Hotkey Configuration

Hotkey Format

Customizing Your Hotkey

Hotkey Input Component

Recording Modes

Toggle Mode (Default)

Push-to-Talk Mode

Quick Cancel (Double ESC)

How It Works

Hotkey Validation

Validation Rules

System Conflict Detection

Best Practices

Choosing a Good Hotkey

Recommended Hotkeys

Keyboard Mapping

Troubleshooting

Hotkey Not Working

Hotkey Registration Failed

Hotkey Works Intermittently

Can’t Save Hotkey

Advanced Configuration

Platform-Specific Hotkeys

Multiple Hotkeys

Programmatic Hotkey Changes

Security Considerations

Get Started

Core Features

Guides

Platform Specific

Help

​Overview

​Default Hotkeys

macOS

Windows

​Hotkey Configuration

​Hotkey Format

​Customizing Your Hotkey

​Hotkey Input Component

​Recording Modes

​Toggle Mode (Default)

​Push-to-Talk Mode

​Quick Cancel (Double ESC)

​How It Works

​Hotkey Validation

​Validation Rules

​System Conflict Detection

​Best Practices

​Choosing a Good Hotkey

​Recommended Hotkeys

​Keyboard Mapping

​Troubleshooting

​Hotkey Not Working

​Hotkey Registration Failed

​Hotkey Works Intermittently

​Can’t Save Hotkey

​Advanced Configuration

​Platform-Specific Hotkeys

​Multiple Hotkeys

​Programmatic Hotkey Changes

​Security Considerations

Overview

Default Hotkeys

Hotkey Configuration

Hotkey Format

Customizing Your Hotkey

Hotkey Input Component

Recording Modes

Toggle Mode (Default)

Push-to-Talk Mode

Quick Cancel (Double ESC)

How It Works

Hotkey Validation

Validation Rules

System Conflict Detection

Best Practices

Choosing a Good Hotkey

Recommended Hotkeys

Keyboard Mapping

Troubleshooting

Hotkey Not Working

Hotkey Registration Failed

Hotkey Works Intermittently

Can’t Save Hotkey

Advanced Configuration

Platform-Specific Hotkeys

Multiple Hotkeys

Programmatic Hotkey Changes

Security Considerations