Documentation

Setup Guide

Get PulseScribe running on macOS or Windows in under 2 minutes. This guide covers installation, API key configuration, and your first dictation.

Download & Install

Download the latest release from GitHub.

macOS

Move PulseScribe.app to your Applications folder.

Download for macOS

Windows

Run the installer. Choose API-only (~30MB) for cloud transcription or Local (~4GB) for offline CUDA Whisper.

API-only Local

Default hotkeys: Toggle = Ctrl+Alt+R, Hold = Ctrl+Win

View on GitHub

Gatekeeper note: This release is ad-hoc signed (not notarized). macOS may block it with "Apple could not verify…". To open it, run in Terminal:

sudo xattr -dr com.apple.quarantine /Applications/PulseScribe.app
open /Applications/PulseScribe.app

Get an API Key

PulseScribe supports multiple transcription providers. We recommend starting with Deepgram for the best latency (~300ms via streaming).

Provider	Latency	Free Tier	Sign Up
Deepgram	~300ms	$200 credit	console.deepgram.com
Groq	~1s	Free credits	console.groq.com
OpenAI	~2-3s	Pay-as-you-go	platform.openai.com
Local Whisper	varies	Free (offline)	No signup needed

Configure via Settings UI

Open Settings from the menu bar (macOS: 🎤 icon) or system tray (Windows: right-click). All settings can be configured here:

Setup—Quick start & wizard

Hotkeys—Hold/Toggle keys

Providers—API keys & mode

Advanced—Performance tuning

Refine—LLM post-processing

Prompts—Custom prompts

Vocabulary—Domain terms

Logs—View log files

Alternative: Configure via .env file

~/.pulsescribe/.env

# API Keys
DEEPGRAM_API_KEY=your_key_here

# Settings
PULSESCRIBE_MODE=deepgram
PULSESCRIBE_LANGUAGE=en
PULSESCRIBE_REFINE=true

Grant Permissions

PulseScribe needs permissions to work:

✅ Windows: No special permissions needed.

macOS requires:

1.
Microphone — Required for voice recording.
System Settings → Privacy & Security → Microphone → Enable PulseScribe
2.
Accessibility (for Auto-Paste) — Required to paste text automatically.
System Settings → Privacy & Security → Accessibility → Enable PulseScribe
3.
Input Monitoring (for Hold Mode) — Only needed if using Fn/Globe as hold-to-talk.
System Settings → Privacy & Security → Input Monitoring → Enable PulseScribe

Start Dictating

Press your hotkey and speak. On macOS, the default is Fn/Globe. On Windows, use Ctrl+Alt+R (toggle) or Ctrl+Win (hold).

Hold Mode

Hold key → Speak → Release → Text is pasted

Toggle Mode

Press hotkey → Speak → Press again → Text is pasted

Hotkey Configuration

Customize your trigger key in Settings or via environment variables:

~/.pulsescribe/.env

# Hold mode (Push-to-Talk) — recommended
PULSESCRIBE_HOLD_HOTKEY=fn

# Toggle mode (optional, in addition to hold)
PULSESCRIBE_TOGGLE_HOTKEY=f19

# Windows defaults
# PULSESCRIBE_TOGGLE_HOTKEY=ctrl+alt+r
# PULSESCRIBE_HOLD_HOTKEY=ctrl+win

Supported hotkeys

fn— Fn/Globe key (macOS, recommended for Hold mode)
f19— F19 (remap CapsLock via Karabiner on macOS)
ctrl+alt+r— Windows default toggle
ctrl+win— Windows default hold
cmd+shift+r— Custom combination

Visual Feedback

The overlay shows the current recording status with colors and animations:

Listening

Hotkey pressed, waiting for speech

Recording

Speech detected, recording active

Transcribing

Finalizing transcription

Refining

LLM post-processing active

Done

Text pasted successfully

Error

Something went wrong

Advanced Features

LLM Post-Processing (Refine)

Enable PULSESCRIBE_REFINE=true to automatically clean up transcriptions: remove filler words, correct grammar, and format into paragraphs.

Context Awareness

PulseScribe detects the active app and adjusts writing style:

Context	Apps	Style
email	Mail, Outlook, Spark	Formal, complete sentences
chat	Slack, Discord, Messages	Casual, short and concise
code	VS Code, Cursor, Terminal	Technical, preserve terms
default	All others	Standard correction

Voice Commands

Speak formatting commands while dictating (requires Refine):

“new paragraph”→¶

“new line”→↵

“period”→.

“comma”→,

“question mark”→?

“exclamation mark”→!

Custom Vocabulary

Improve recognition for domain-specific terms:

~/.pulsescribe/vocabulary.json

{
  "keywords": ["Anthropic", "Claude", "Kubernetes", "OAuth"]
}

Local Offline Mode

Run completely offline. On macOS (Apple Silicon), use Lightning for ~4x faster transcription. On Windows, use the Local installer with CUDA Whisper:

~/.pulsescribe/.env

PULSESCRIBE_MODE=local
PULSESCRIBE_LOCAL_BACKEND=lightning  # macOS: lightning, mlx, faster, whisper
PULSESCRIBE_LOCAL_MODEL=large
PULSESCRIBE_LANGUAGE=de

Requires: pip install lightning-whisper-mlx

⚡ Lightning mode (macOS) uses batched decoding for near real-time local transcription.

🪟 Windows Local installer includes CUDA Whisper for NVIDIA GPUs (~4GB).

⏳ First-time loading: The model needs to be downloaded on first use (1-5 GB). The app shows "Loading [model]..." during this time. Subsequent launches are much faster.

Troubleshooting

Microphone not working

Grant Microphone permission in System Settings → Privacy & Security. On macOS, you may also need: brew install portaudio

Auto-Paste not working

Grant Accessibility permission. For unsigned builds, remove and re-add PulseScribe in Accessibility settings after each rebuild.

Transcription slow

Switch to Deepgram (streaming) or Groq. For local mode, use MLX on macOS or CUDA on Windows.

Hold mode not detecting key release

Grant Input Monitoring permission in System Settings → Privacy & Security.

App won't start / crashes

Check ~/.pulsescribe/startup.log (macOS) or %USERPROFILE%\.pulsescribe\logs\pulsescribe.log (Windows) for error details.

Windows: Overlay not showing

PySide6 is optional. The app falls back to Tkinter. To enable PySide6 overlay, reinstall with the full installer.

Windows: CUDA/Local mode not working

Ensure you installed the Local variant (~4GB). CUDA requires an NVIDIA GPU with drivers installed.

Windows: Hotkey not detected

Some hotkeys may conflict with Windows shortcuts. Try a different combination like Ctrl+Alt+Space. Configure in Settings → Hotkeys.

Need more help? Check the log files at ~/.pulsescribe/logs/pulsescribe.log or use the menu bar → Export Diagnostics.

CLI Usage (Advanced)

For developers or automation, PulseScribe also works as a CLI tool:

Terminal

# Clone and install
git clone https://github.com/KLIEBHAN/pulsescribe.git
cd pulsescribe
pip install -r requirements.txt

# Record and copy to clipboard
python transcribe.py --record --copy --mode deepgram

# Transcribe a file
python transcribe.py audio.mp3 --mode openai

# Start the daemon manually
python pulsescribe_daemon.py --hotkey cmd+shift+r     # macOS
python pulsescribe_windows.py --debug                  # Windows

Ready to go?

Download PulseScribe and start dictating faster than you can type.

Download for macOS Download for Windows View on GitHub