File: README.md Copy Chapter

OpenWhispr

OpenWhispr turns your voice into text, notes, and actions from your desktop. Press a hotkey, speak, and your words appear at your cursor. Choose between fully private offline transcription with local speech-to-text engines like Whisper and NVIDIA Parakeet — where your audio never leaves your device — or cloud processing for speed. No data collection, no telemetry, fully open source.

Download Copy Chapter

* On Intel Macs, live speaker identification and voice fingerprinting are unavailable: they depend on ONNX Runtime, which stopped shipping macOS x86_64 binaries in 1.24. Meetings still record and transcribe normally, and notes search falls back to keyword matching instead of semantic search.

Features Copy Chapter

• Voice dictation — global hotkey to dictate into any app with automatic pasting
• Dictation translation — dedicated hotkey to dictate in one language and paste the text in another
• AI agent — talk to GPT-5, Claude, Gemini, Groq, Tinfoil, OpenRouter, or local models with a named voice assistant
• Voice agent hotkey — dedicated hotkey that sends your dictation straight to your AI agent as a command, no wake word needed and no cleanup pass; edit highlighted text in place, or opt in to sending a screenshot of your current screen as context
• Meeting transcription — auto-detect Zoom, Teams, and FaceTime calls with live speaker diarization, voice fingerprinting, and Google, Microsoft, or Apple Calendar integration
• Local speaker diarization — on-device speaker labelling with voice fingerprint recognition across meetings, no cloud required
• Notes — create, organize, and search notes with folders, semantic search, cloud sync, and AI actions
• Team spaces & sharing — free for signed-in users; share notes on the web with link, domain, or invite-only visibility, and collaborate in team spaces with roles, invitations, and server-enforced membership
• Audio import — transcribe existing audio and video: drag in files, batch-upload, or paste a YouTube/audio URL, with optional speaker detection
• Local or cloud — your choice — all core features (transcription, AI reasoning, speaker diarization, semantic search) work with local models or cloud providers — including GPU-accelerated local Whisper on Metal, CUDA, and Vulkan (AMD/Intel)
• Enterprise controls — enforce organization policy, company SSO and SCIM, and centrally managed Amazon Bedrock or Azure OpenAI access without distributing cloud keys
• Public API & MCP — manage notes and transcriptions programmatically or connect your AI assistant via the MCP server

Quick start Copy Chapter

git clone https://github.com/OpenWhispr/openwhispr.git
cd openwhispr
npm install
npm run dev

Requires Node.js 24+. See the full documentation for setup guides, platform-specific instructions, and build details.

Documentation Copy Chapter

Visit docs.openwhispr.com for:

• Getting started
• Platform guides (macOS, Windows, Linux)
• API reference
• MCP server setup
• Troubleshooting

Repo examples:

• Custom ASR shim for Self-Hosted transcription against non-OpenAI-compatible ASR APIs

Tech stack Copy Chapter

React 19, TypeScript, Tailwind CSS v4, Electron 41, better-sqlite3, whisper.cpp, sherpa-onnx, shadcn/ui

Star History Copy Chapter

Sponsors Copy Chapter

Contributing Copy Chapter

We welcome contributions. Fork the repo, create a feature branch, and open a pull request. See the contributing guide for development setup and guidelines.

License Copy Chapter

MIT — free for personal and commercial use.

Acknowledgments Copy Chapter

• OpenAI Whisper — speech recognition model powering local and cloud transcription
• whisper.cpp — high-performance C++ implementation for local processing
• NVIDIA Parakeet — fast multilingual ASR model
• sherpa-onnx — cross-platform ONNX runtime for Parakeet inference
• Hugging Face — model hub hosting Whisper, Parakeet, and embedding model weights
• llama.cpp — local LLM inference for AI text processing
• Electron — cross-platform desktop framework
• React — UI component library
• shadcn/ui — accessible components built on Radix primitives
• Neon — serverless Postgres powering OpenWhispr Cloud

File: docs/network-allowlist.md Copy Chapter

Network Allowlist

Outbound hosts the OpenWhispr desktop app contacts. For firewall, proxy, and
DNS filter configuration.

All connections are client-initiated over TLS. No inbound ports.

Required by default Copy Chapter

Contacted by every install using OpenWhispr Cloud (the default after
onboarding).

Required for streaming transcription Copy Chapter

OpenWhispr Cloud routes streaming sessions through one of three providers.
Allowlist all three unless a specific provider is pinned in configuration.

Required for local model downloads Copy Chapter

Contacted only when a user opts into a local model (Whisper, Parakeet, or a
local GGUF reasoning model). Not required for cloud-only installs.

Required for Google Calendar (optional feature) Copy Chapter

Contacted only if the user connects Google Calendar in settings.

Required for URL audio import (optional feature) Copy Chapter

Contacted only when a user pastes a URL into the Upload view to download and
transcribe its audio. Downloads are HTTPS-only and hosts resolving to
private/internal addresses are rejected.

BYOK provider hosts (only if configured) Copy Chapter

Required only when a user configures their own API key for the corresponding
provider. Skip any provider not in use.

Notes Copy Chapter

• The app uses Electron's network stack, which honors system proxy settings
  (macOS System Settings, Windows Internet Options / WPAD, GNOME proxy) and
  PAC scripts on all platforms.
• Connections fail with ENOTFOUND if DNS is filtered, ECONNREFUSED /
  ETIMEDOUT if a firewall blocks the host, and CERT_HAS_EXPIRED /
  UNABLE_TO_VERIFY_LEAF_SIGNATURE if a TLS-intercepting proxy is in the
  path without its root certificate trusted by the OS.
• IP-pinning is not supported. The hosts above resolve to provider-managed
  IPs that change without notice.
• On minimal Linux containers without a system CA bundle (Alpine, distroless),
  set NODE_EXTRA_CA_CERTS to your CA bundle path so corporate TLS interception
  is trusted.

How to test Copy Chapter

Run from a machine on the same network as the user. A successful response
(any HTTP status, including 401) confirms the network path works.

# OpenWhispr Cloud reachability
curl -v https://api.openwhispr.com/api/health

# Streaming providers
curl -v https://api.deepgram.com/v1/projects
curl -v https://api.openai.com/v1/models
curl -v https://streaming.assemblyai.com/v3/token

# Model downloads (only if local mode is in use)
curl -v -I https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.bin

If a request returns Could not resolve host, the DNS layer (resolver,
filter, or ad blocker) is blocking the domain. If it hangs or returns
Connection refused, a firewall is blocking the port. If it returns a TLS
error, a proxy is intercepting the connection without a trusted root.

File: src/assets/README.md Copy Chapter

Assets Directory

This directory contains app icons and other assets for OpenWhispr.

Required Icons Copy Chapter

For proper app packaging, you'll need the following icon files:

• icon.icns - macOS icon (1024x1024 recommended)
• icon.ico - Windows icon (256x256 recommended)
• icon.png - Linux icon (512x512 recommended)

Icon Specifications Copy Chapter

• macOS (.icns): 1024x1024 pixels, PNG format converted to ICNS
• Windows (.ico): 256x256 pixels, PNG format converted to ICO
• Linux (.png): 512x512 pixels, PNG format

Creating Icons Copy Chapter

You can create these icons using:

• Online converters like https://convertio.co/
• Design tools like Figma, Sketch, or Photoshop
• Command line tools like ImageMagick

Placeholder Copy Chapter

Until you add your own icons, the app will use system default icons during development.