## File: README.md

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 | Platform | Download | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | macOS (Apple Silicon) | [`.dmg`](https://github.com/OpenWhispr/openwhispr/releases/latest) | | macOS (Intel) \* | [`.dmg`](https://github.com/OpenWhispr/openwhispr/releases/latest) | | Windows | [`.exe`](https://github.com/OpenWhispr/openwhispr/releases/latest) | | Linux | [`.AppImage`](https://github.com/OpenWhispr/openwhispr/releases/latest) / [`.deb`](https://github.com/OpenWhispr/openwhispr/releases/latest) / [`.rpm`](https://github.com/OpenWhispr/openwhispr/releases/latest) / [`.tar.gz`](https://github.com/OpenWhispr/openwhispr/releases/latest) | \* 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](https://github.com/microsoft/onnxruntime/releases/tag/v1.24.1). Meetings still record and transcribe normally, and notes search falls back to keyword matching instead of semantic search. ## Features - **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](https://docs.openwhispr.com/integrations/mcp) ## Quick start ```bash git clone https://github.com/OpenWhispr/openwhispr.git cd openwhispr npm install npm run dev ``` Requires Node.js 24+. See the [full documentation](https://docs.openwhispr.com/quickstart) for setup guides, platform-specific instructions, and build details. ## Documentation Visit **[docs.openwhispr.com](https://docs.openwhispr.com)** for: - [Getting started](https://docs.openwhispr.com/quickstart) - [Platform guides](https://docs.openwhispr.com/platform/macos) (macOS, Windows, Linux) - [API reference](https://docs.openwhispr.com/api/overview) - [MCP server setup](https://docs.openwhispr.com/integrations/mcp) - [Troubleshooting](https://docs.openwhispr.com/troubleshooting) Repo examples: - [Custom ASR shim](examples/custom-asr-shim/) for Self-Hosted transcription against non-OpenAI-compatible ASR APIs ## Tech stack React 19, TypeScript, Tailwind CSS v4, Electron 41, better-sqlite3, whisper.cpp, sherpa-onnx, shadcn/ui ## Star History [](https://www.star-history.com/#OpenWhispr/openwhispr&type=date&legend=top-left) ## Sponsors ## Contributing We welcome contributions. Fork the repo, create a feature branch, and open a pull request. See the [contributing guide](https://docs.openwhispr.com/contributing) for development setup and guidelines. ## License [MIT](LICENSE) — free for personal and commercial use. ## Acknowledgments - **[OpenAI Whisper](https://github.com/openai/whisper)** — speech recognition model powering local and cloud transcription - **[whisper.cpp](https://github.com/ggerganov/whisper.cpp)** — high-performance C++ implementation for local processing - **[NVIDIA Parakeet](https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3)** — fast multilingual ASR model - **[sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx)** — cross-platform ONNX runtime for Parakeet inference - **[Hugging Face](https://huggingface.co/)** — model hub hosting Whisper, Parakeet, and embedding model weights - **[llama.cpp](https://github.com/ggerganov/llama.cpp)** — local LLM inference for AI text processing - **[Electron](https://www.electronjs.org/)** — cross-platform desktop framework - **[React](https://react.dev/)** — UI component library - **[shadcn/ui](https://ui.shadcn.com/)** — accessible components built on Radix primitives - **[Neon](https://console.neon.tech/app/?promo=openwhispr)** — serverless Postgres powering OpenWhispr Cloud --- ## File: docs/network-allowlist.md # 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 Contacted by every install using OpenWhispr Cloud (the default after onboarding). | Host | Protocol | Port | Purpose | | --------------------------------------------- | -------- | ---- | ---------------------------------------------------------------------------------- | | `api.openwhispr.com` | HTTPS | 443 | Cloud API: transcription, sync, agent reasoning, settings, usage. | | `auth.openwhispr.com` | HTTPS | 443 | Account sign-in and session refresh (Better Auth). | | `github.com`, `objects.githubusercontent.com` | HTTPS | 443 | Application auto-update (release artifacts via electron-updater, GitHub provider). | ## Required for streaming transcription OpenWhispr Cloud routes streaming sessions through one of three providers. Allowlist all three unless a specific provider is pinned in configuration. | Host | Protocol | Port | Purpose | | -------------------------- | ---------- | ---- | --------------------------------------------------------------------------------- | | `api.deepgram.com` | WSS | 443 | Deepgram streaming transcription. | | `api.openai.com` | WSS, HTTPS | 443 | OpenAI Realtime streaming transcription. | | `streaming.assemblyai.com` | WSS, HTTPS | 443 | AssemblyAI streaming transcription. Token endpoint is HTTPS; live session is WSS. | ## Required for local model downloads Contacted only when a user opts into a local model (Whisper, Parakeet, or a local GGUF reasoning model). Not required for cloud-only installs. | Host | Protocol | Port | Purpose | | ------------------------------------------------------- | -------- | ---- | --------------------------------------------------------------------------- | | `huggingface.co` | HTTPS | 443 | Whisper GGML, Parakeet, GGUF, and embedding model downloads. | | `cdn-lfs.huggingface.co`, `cdn-lfs-us-1.huggingface.co` | HTTPS | 443 | HuggingFace large-file CDN (LFS-backed model files). | | `github.com`, `objects.githubusercontent.com` | HTTPS | 443 | sherpa-onnx, llama.cpp, whisper.cpp, and Qdrant binaries (GitHub releases). | ## Required for Google Calendar (optional feature) Contacted only if the user connects Google Calendar in settings. | Host | Protocol | Port | Purpose | | ----------------------- | -------- | ---- | ----------------------------------------------------------- | | `accounts.google.com` | HTTPS | 443 | OAuth authorization. | | `oauth2.googleapis.com` | HTTPS | 443 | OAuth token exchange and revoke. | | `www.googleapis.com` | HTTPS | 443 | Calendar event and calendar list reads. | | `openwhispr.com` | HTTPS | 443 | OAuth desktop callback redirect (`/auth/desktop-callback`). | ## Required for URL audio import (optional feature) 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. | Host | Protocol | Port | Purpose | | ----------------------------------- | -------- | ---- | -------------------------------------------------------------------------- | | `www.youtube.com`, `youtube.com`, `youtu.be`, `m.youtube.com`, `music.youtube.com` | HTTPS | 443 | YouTube page/metadata fetch for pasted YouTube links (bundled yt-dlp). | | `*.googlevideo.com` | HTTPS | 443 | YouTube media CDN — the actual audio stream download. | | _User-pasted hosts_ | HTTPS | 443 | Direct audio/video URL imports contact whatever public host the user pastes. | ## BYOK provider hosts (only if configured) Required only when a user configures their own API key for the corresponding provider. Skip any provider not in use. | Host | Protocol | Port | Used when | | -------------------------------------------------------------------------------- | ---------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api.openai.com` | HTTPS | 443 | OpenAI API key configured (transcription or reasoning). | | `*.cognitiveservices.azure.com`, `*.openai.azure.com`, `*.services.ai.azure.com` | HTTPS | 443 | Azure AI Foundry / Azure OpenAI speech-to-text configured (custom transcription provider pointed at your own Azure resource endpoint). | | `api.anthropic.com` | HTTPS | 443 | Anthropic API key configured. | | `generativelanguage.googleapis.com` | HTTPS | 443 | Gemini API key configured. | | `api.groq.com` | HTTPS | 443 | Groq API key configured. | | `atc.tinfoil.sh`, `*.tinfoil.sh` | WSS, HTTPS | 443 | Tinfoil API key configured. `atc.tinfoil.sh` serves the enclave attestation bundle (verified locally against an embedded sigstore root). Inference and realtime transcription connect to an enclave host assigned dynamically at runtime (e.g. `inference.tinfoil.sh`, `router.infN.tinfoil.sh`), so allowlist `*.tinfoil.sh` rather than pinning hosts. | | `api.mistral.ai` | HTTPS | 443 | Mistral API key configured. | | `openrouter.ai` | HTTPS | 443 | OpenRouter selected as a reasoning provider (`/api/v1/models` is fetched even without a key). | ## Notes - 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 Run from a machine on the same network as the user. A successful response (any HTTP status, including `401`) confirms the network path works. ```sh # 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 # Assets Directory This directory contains app icons and other assets for OpenWhispr. ## Required Icons 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 - **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 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 Until you add your own icons, the app will use system default icons during development.