Skip to main content

​
Quick Start Guide

Get OpenWhispr up and running in under 5 minutes. This guide will walk you through installation, setup, and your first successful transcription.
Already installed? Skip to First Transcription.

​
Installation

1

Download OpenWhispr

Visit the GitHub Releases page and download the appropriate installer for your platform:
  • macOS: OpenWhispr-{version}-mac-{arch}.dmg (Apple Silicon or Intel)
  • Windows: OpenWhispr-{version}-win-x64.exe (NSIS installer)
  • Linux: Choose from .AppImage, .deb, .rpm, or .tar.gz
2

Install the application

  1. Open the .dmg file
  2. Drag OpenWhispr.app to your Applications folder
  3. Right-click the app and select Open (first time only)
  4. Click Open in the security dialog
macOS may show a security warning for unsigned apps. Right-click → Open bypasses this.
3

Grant permissions

When you first launch OpenWhispr, your OS will request necessary permissions:Microphone Access (Required)
  • Needed to record your voice
  • You’ll see a system prompt on first use
Accessibility Permissions (macOS only, recommended)
  • Enables automatic text pasting at cursor
  • Go to System Settings → Privacy & Security → Accessibility
  • Enable checkbox for OpenWhispr
  • Without this, text copies to clipboard (manual paste with Cmd+V)
The Control Panel has a “Fix Permission Issues” button if you need to adjust settings later.

​
First-Time Setup

OpenWhispr guides you through setup with an interactive onboarding flow:
1

Welcome Screen

Choose your setup path:
  • Sign In: Use OpenWhispr Cloud (recommended for beginners)
  • Skip for Now: Set up local or BYOK processing
2

Choose Processing Method

Recommended for first-time users
  1. Click “Sign in with Google” or “Sign in with Email”
  2. Complete authentication flow
  3. Verify email if using email sign-in
  4. Start with 2,000 free words/week (7-day Pro trial included)
No API keys, no downloads. Start transcribing immediately after sign-in.
3

Configure Hotkey

Set your global dictation hotkey:
  • Default: Backtick (`) on most platforms
  • macOS: Option to use Globe/Fn key
  • Custom: Click the input field and press your preferred key combination
Recommended hotkeys:
  • Simple: `, F8, F9
  • Compound: Cmd+Shift+D, Ctrl+Alt+V
Choose an unused key that’s easy to reach. You can change this later in Settings.
4

Select Activation Mode

Choose how the hotkey triggers recording:
  • Tap to Toggle (Default): Press once to start, press again to stop
  • Push to Talk (Windows): Hold key to record, release to transcribe
Push-to-talk requires native keyboard hooks and is currently only available on Windows.
5

Complete Setup

Click “Finish Setup” to save your configuration. OpenWhispr is now ready to use!

​
Your First Transcription

Now let’s create your first transcription:
1

Open any text field

Click into any application where you want text to appear:
  • Email composer
  • Note-taking app
  • Text editor
  • Chat application
  • Anywhere with a text input!
2

Press your hotkey

Press the hotkey you configured (default: backtick `).You’ll see:
  • A small draggable panel appears
  • Panel shows recording animation (pulsing waves)
  • Your microphone starts capturing audio
The panel can be dragged anywhere on screen. Its position is saved for next time.
3

Speak clearly

Say your message naturally. Examples:
  • “Hello, this is a test of OpenWhispr dictation.”
  • “Meeting notes: Discussed Q1 roadmap with Sarah and John.”
  • “Hey OpenWhispr, write a professional email thanking the client for their feedback.”
Speak naturally at a normal pace. Pause briefly between sentences for better punctuation.
4

Stop recording

Press your hotkey again (or release if using push-to-talk).What happens:
  • Recording stops immediately
  • Panel shows processing animation (loading dots)
  • Audio is transcribed (local or cloud, depending on your setup)
  • Processing time: 1-10 seconds depending on method and length
5

See your transcription

Transcribed text appears automatically:
  • With accessibility permissions: Text pastes at cursor location
  • Without permissions: Text copies to clipboard (paste with Cmd+V or Ctrl+V)
  • AI processing: If you addressed your agent (“Hey OpenWhispr…”), the AI-processed result appears
All transcriptions are saved to local history. Access them via the Control Panel.

​
Testing Different Features

​
Basic Dictation

Simple transcription without AI processing: 
Press hotkey → "This is a simple test message" → Press hotkey
Result: This is a simple test message

​
AI-Powered Processing

Address your agent for intelligent text transformation: 
Press hotkey → "Hey OpenWhispr, make this more professional: thanks for the help" → Press hotkey
Result: Thank you for your assistance. I appreciate your help with this matter.
AI processing requires an AI provider to be configured (OpenWhispr Cloud, OpenAI, Anthropic, Gemini, Groq, or local LLM).

​
Custom Dictionary

Improve accuracy for technical terms:
  1. Open Control Panel (right-click tray icon)
  2. Go to Settings → Custom Dictionary
  3. Add terms: “Kubernetes”, “OAuth”, “PostgreSQL”
  4. Dictate: “We deployed the app to Kubernetes using OAuth for authentication”
  5. Results are now more accurate!

​
Accessing the Control Panel

The Control Panel is your hub for settings, history, and model management: How to open:
  • macOS: Right-click the menu bar icon → “Show Control Panel”
  • Windows: Right-click the system tray icon → “Show Control Panel”
  • Linux: Right-click the system tray icon → “Show Control Panel”
What you can do:
  • View and search transcription history
  • Switch between local and cloud processing
  • Download and manage Whisper/Parakeet models
  • Configure API keys for different providers
  • Customize hotkey and activation mode
  • Add words to custom dictionary
  • Check system permissions
  • View usage statistics (for cloud users)

​
Common First-Time Issues

Solutions:
  1. Check microphone permissions in system settings
  2. Select correct input device in Control Panel → Settings
  3. Test microphone with another app to verify hardware
  4. Restart OpenWhispr after granting permissions
Open sound settings:
  • macOS: Control Panel → “Open Sound Settings” button
  • Windows: Control Panel → “Open Sound Settings” button
  • Linux: Use pavucontrol or system sound settings
Solutions:
  1. Check if another app is using the same hotkey
  2. Try a different key (F8, F9, or compound hotkey)
  3. On GNOME Wayland: Check Settings → Keyboard → Shortcuts for conflicts
  4. Restart the app after changing hotkeys
OpenWhispr will automatically fall back to F8 if your chosen hotkey is unavailable.
macOS:
  • Grant accessibility permissions in System Settings
  • Go to Privacy & Security → Accessibility
  • Enable OpenWhispr checkbox
  • Restart app if needed
Windows:
  • No special permissions needed
  • Text should paste automatically via SendInput API
  • If failing, text copies to clipboard (Ctrl+V to paste)
Linux:
  • Install paste tool: sudo apt install xdotool (X11)
  • For Wayland: sudo apt install wtype or ydotool
  • Text always copies to clipboard as fallback
Solutions:
  1. Check internet connection
  2. Ensure sufficient disk space (75MB to 3GB depending on model)
  3. Try downloading manually from Control Panel → Settings → Models
  4. Check ~/.cache/openwhispr/ permissions
  5. Try a smaller model first (tiny or base)
Models download from HuggingFace and may take several minutes on slow connections.
Improve accuracy:
  1. Use a better quality model (small, medium, or large)
  2. Add specialized terms to Custom Dictionary
  3. Speak clearly and at a moderate pace
  4. Reduce background noise
  5. Use a better quality microphone
  6. Set your language explicitly (Settings → Language) instead of auto-detect
The base model offers the best balance for most users. Upgrade to small or medium for technical content.

​
Next Steps

Now that you have OpenWhispr working:

Explore Features

Learn about AI processing, custom dictionary, and advanced options

Configuration Guide

Customize settings, hotkeys, and processing preferences

Platform Guides

Platform-specific features and setup

Troubleshooting

Get help with common issues and error messages

Documentation

Return to main documentation

Configuration Guide

Customize settings, hotkeys, and processing preferences

Keyboard Shortcuts

Master all keyboard shortcuts and productivity tips

Troubleshooting

Solutions for common issues and platform-specific problems

​
Getting Help

GitHub Issues

Report bugs or request features

Documentation

Browse complete documentation

Community

Ask questions and share tips

Build docs developers (and LLMs) love

Get started for freeTalk to us